@alemm12/testkit

Typed client for reading tests authored in variantry at runtime, in browser or server apps.

variantry is a UI for defining tests as PostHog multivariate feature flags — each variant gets a rollout percentage and a typed set of fields (booleans, text, numbers, arrays, objects). testkit is the other half: a small typed wrapper so a consuming app (e.g. soldoutcr) doesn't have to know it's PostHog underneath, or hand-roll getFeatureFlagResult calls and untyped payloads.

This is a standalone package — it does not depend on eventlens (analytics: track/identify/errors) or on variantry itself. If an app also uses eventlens, testkit initializes its own separate PostHog client rather than sharing eventlens's.

Install

npm install @alemm12/testkit

Browser

import { createBrowserTestClient } from "@alemm12/testkit/browser";

const testkit = createBrowserTestClient({
  apiKey: "phc_...",
  apiHost: "https://us.i.posthog.com", // optional, this is the default
});

interface CheckoutFields {
  headline: string;
  showBanner: boolean;
}

testkit.onReady(() => {
  const result = testkit.getTest<CheckoutFields>("checkout-redesign");
  if (result?.variant === "treatment" && result.payload) {
    // result.payload is typed as CheckoutFields
  }
});

Call createBrowserTestClient once during app startup (e.g. a root layout/provider) — later calls reuse the same underlying PostHog instance. onReady fires once flags have loaded (and again on reload); calling getTest before that returns undefined. Call reset() on logout to clear the local distinct ID.

Server

import { createServerTestClient } from "@alemm12/testkit/server";

const testkit = createServerTestClient({ apiKey: "phc_..." });

const result = await testkit.getTest<CheckoutFields>(userId, "checkout-redesign");
if (result?.variant === "treatment" && result.payload) {
  // ...
}

// Before the process exits (e.g. end of a serverless handler):
await testkit.shutdown();

Server clients have no persisted identity, so getTest always takes an explicit distinctId — the user (or session) the test is being evaluated for.

What getTest returns

interface TestResult<T> {
  key: string;
  enabled: boolean;
  variant: string | undefined;
  payload: T | undefined;
}

This mirrors PostHog's own flag-evaluation result, not variantry's authoring-time model — at runtime you only ever see the variant that was picked for this user and its payload, never the other variants or their rollout percentages. The T type parameter is a type assertion, not runtime validation: it's on you to keep it in sync with the fields you defined for that test in variantry.

Development

npm install
npm run typecheck
npm run lint
npm run test
npm run build