PostHog

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of PostHog for test suites: remote feature-flag evaluation (/flags v2 and the legacy /decide shape), remote config, event capture (/batch/, /e/, /i/v0/e/), session-recording intake, the posthog-js asset and survey endpoints, and the slice of the management API our tooling and crons call (feature-flag list/create/patch, HogQL). Every flag is set per test through admin routes, so paths our in-app overrides cannot reach (strict booleans, getConfig payloads, EMR server gates, member-app variants) become controllable, and a stack run never reaches us.i.posthog.com.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from the wire shapes of posthog-node 5.52.2, @posthog/core 1.54.0 (posthog-react-native 4.72.1's base) and posthog-js 1.433.2, and from our own raw fetches. All three SDKs are proven against it (posthog.sdk.test.ts).

#Install

npm install -D @crvouga/mockingbird-service-posthog

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-posthog serve, createServer from ./server (Node), or createRuntime with any Fetch server.

#Usage

Point the app's PostHog host at the emulator (port 8795 by default):

npx mockingbird-posthog serve --port 8795 --import-flags dev

import { PostHog } from "posthog-node"
import { createRuntime } from "@crvouga/mockingbird-service-posthog"

// Test setup: the emulator and the flags this worker should see.
const emulator = createRuntime()
const admin = (path: string, body: unknown, method = "PUT") =>
  emulator.fetch(
    new Request(`http://posthog.test/__admin${path}`, { method, body: JSON.stringify(body) }),
  )
// Per-worker namespaces: map each worker's project token (the SDKs cannot add headers)…
await admin("/credentials", { credentials: { phc_worker1: "w1" } })
// …then set flags in that namespace.
await admin("/flags/shop-coupons?namespace=w1", { default: true })
await admin("/flags/rx-category-intake?namespace=w1", {
  default: true,
  payload: { categories: ["trt"] },
  overrides: [{ distinct_id: "42", value: false }, { email: "qa@example.test", value: "beta" }],
})
await admin("/flags/mobile-smart-links?namespace=w1", undefined, "DELETE") // absent again

// The application's posthog-node client. Only its fetch changes: requests reach the
// emulator in this process instead of us.i.posthog.com.
const posthog = new PostHog("phc_worker1", {
  fetch: (url, options) => emulator.fetch(new Request(url, options)),
})
await posthog.getFeatureFlag("shop-coupons", "7") // true
await posthog.getFeatureFlag("rx-category-intake", "42") // false
posthog.capture({ distinctId: "7", event: "coupon_applied" })
await posthog.shutdown()

#Routes

Every route answers with and without its trailing slash. Errors use PostHog's {type, code, detail, attr} body: 401 invalid_api_key without a project token, 400 missing_distinct_id, 400 invalid_payload for an undecodable body, 404 not_found.

#Flag semantics

• Absent vs false. A flag whose default is omitted (or null) is not returned at all unless an override matches; default: false returns enabled: false. The member app's hasFlag falls through to static defaults only for the absent case. Inactive or deleted flags are never returned (as in PostHog).
• Targeting: overrides in order, by exact distinct_id or by person_properties.email (case-insensitive), then the default.
• Variants: a string value is a variant (enabled: true, variant: "<key>"); our backend, EMR and Python clients all read it as true.
• Payloads: any JSON; stored and sent as the JSON string PostHog uses. The backend's getConfig only accepts object payloads.
• Management filters → model: distinct_id / email property groups become overrides; a property-less group at 100 % is the default (its variant, else the largest multivariate variant, else true); at 0 % or a partial rollout it is false; cohort and other property groups are ignored (deterministic, no hashing). Create/patch reject array/scalar filters.payloads with 400 before changing flag or linked experiment state. The dictionary requirement is verified against PostHog's serializer regression and the local contract; seed 172181039 passes self-parity, not live management parity.

#Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets), each on /flags and /decide: flags_5xx, flags_429 (retry-after: 1), flags_hang (1.5 s, past the backend strict and EMR 1 s races), errors_while_computing (errorsWhileComputingFlags: true, flags still present), quota_limited (quotaLimited: ["feature_flags"], no flags). Plus capture_5xx on the capture endpoints. Each preset adds one rule per route, so count applies per route.

#Namespaces

PostHog SDKs cannot add headers. Choose a namespace by:

• host prefix (primary): POSTHOG_HOST=http://127.0.0.1:8795/__admin/ns/w1. Every SDK builds ${host}/path, so /__admin/ns/w1/flags/?v=2 selects w1.
• project token: PUT /__admin/credentials {"credentials": {"phc_…": "w1"}}. The token is read from /array/{token}/…, ?token=, the body (token, api_key, or a batch's first event's properties.token, after decoding gzip/base64), or a personal key's Authorization: Bearer on the management API.
• x-mockingbird-namespace, for raw clients.

The management API's next page URL preserves the configured admin prefix and namespace. Send the personal key in the Authorization header on each page request.

#Deliberately not modelled

• Percentage rollouts, cohorts, group (organisation) targeting and local evaluation (/api/feature_flag/local_evaluation): flags evaluate deterministically from explicit overrides and a default.
• Experiment statistics, exposure cohorts, metric execution, special launch/archive/ship endpoints, approval policies, advanced experiment filters, and feature_flag configuration writes through experiments. Management flags use the existing namespace-wide project alias model; experiment records additionally filter by project id.
• Session-recording content, heatmaps, surveys and web experiments (the endpoints answer empty).
• HogQL execution: queries answer canned results.
• Person profiles: $identify / $set events are stored for assertions but do not feed targeting; send person_properties on /flags as the SDKs do.
• Project isolation by project id on the management API: one flag set per namespace.
• Real remote-config fields beyond what the SDKs read.

#API

Part of mockingbird.