How to Test PostHog Feature Flags with Playwright: Complete 2026 Guide

1. Why Testing PostHog Feature Flags Is Harder Than It Looks

PostHog feature flags look simple on the surface. You create a flag in the dashboard, wrap a UI element in a conditional check, and toggle it on or off. But the moment your test suite tries to assert that a flag is evaluated correctly in a real browser, five structural challenges emerge that make reliable testing genuinely difficult.

First, feature flags are evaluated asynchronously. The PostHog JavaScript SDK calls the /decide endpoint after initialization, which means there is always a window where flags are undefined. If your test checks for flag-gated UI immediately after page load, you will get intermittent failures because the SDK has not yet received the flag values from PostHog. Second, multivariate flags return string values (not just booleans), and the variant a user sees depends on a hash of their distinct ID. Your tests need deterministic control over which variant is active, which requires either overriding the distinct ID to match a pre-computed hash bucket or intercepting the API response entirely.

Third, flag payloads add a second layer of dynamic data. A multivariate flag might return "variant-b" as the flag value, but also attach a JSON payload like {"cta_text": "Start free trial", "color": "#22c55e"} that drives the actual rendering. Your test must verify both the variant and the payload separately. Fourth, server-side rendering with bootstrapped flags introduces a timing issue: the server evaluates flags via the PostHog Node SDK before HTML is sent to the browser, and then the client SDK re-evaluates on load. If the two evaluations disagree (due to timing or eventual consistency), the UI flickers. Your test must catch that flicker and fail if it happens. Fifth, rollout percentages are probabilistic. A flag set to 30% rollout does not guarantee that exactly 30 out of 100 test users see it, making assertion logic tricky.

2. Setting Up a Reliable Test Environment

Before writing a single test, you need a PostHog project configured for testability. Create a dedicated project in PostHog (free tier works fine for testing) with its own API key. Never run tests against your production project because flag evaluations generate events that pollute your analytics data and can trigger rate limits under heavy parallel test execution.

PostHog Feature Flag Helper for Tests

Use the PostHog API to programmatically create, update, and clean up feature flags in your test suite. The personal API key (not the project API key) is required for flag management. This helper ensures each test run starts with flags in a known state.

Playwright Configuration for Feature Flag Tests

Feature flag tests need extra time for the SDK to call the /decide endpoint and render conditional UI. Set a comfortable action timeout and configure route interception for deterministic flag control.

3. Scenario: Boolean Flag Controls UI Visibility

The simplest feature flag test verifies that a boolean flag toggles a UI element on or off. This is the smoke test every flag-driven feature needs. When the flag is enabled, the new component renders. When it is disabled, the old UI remains. The catch is timing: you cannot check for the element immediately after navigation because the PostHog SDK evaluates flags asynchronously via the /decide endpoint.

import { test, expect } from '@playwright/test';

test('shows banner when flag is enabled', async ({ page }) => {
  await page.route('**/decide/**', async (route) => {
    const response = await route.fetch();
    const body = await response.json();
    body.featureFlags = {
      ...body.featureFlags,
      'new-pricing-banner': true,
    };
    await route.fulfill({
      response,
      body: JSON.stringify(body),
    });
  });

  await page.goto('/pricing');

  await expect(
    page.getByTestId('pricing-banner')
  ).toBeVisible({ timeout: 10_000 });

  await expect(
    page.getByText('Try our new pricing plan')
  ).toBeVisible();
});

4. Scenario: Multivariate Flag Renders Correct Variant

Multivariate flags return a string value instead of a boolean. In PostHog, you define variants like "control", "variant-a", and "variant-b", each with a rollout percentage. The tricky part is that the variant a user receives depends on a hash of their distinct ID combined with the flag key. In production this creates a consistent experience, but in tests it means you need deterministic control over which variant is active, or you will get different results every time a test user ID changes.

import { test, expect } from '@playwright/test';

test('checkout-flow-experiment: single-page variant', async ({ page }) => {
  await page.route('**/decide/**', async (route) => {
    const response = await route.fetch();
    const body = await response.json();
    body.featureFlags = {
      ...body.featureFlags,
      'checkout-flow-experiment': 'single-page',
    };
    await route.fulfill({
      response,
      body: JSON.stringify(body),
    });
  });

  await page.goto('/checkout');

  await expect(
    page.getByRole('heading', { name: 'Quick Checkout' })
  ).toBeVisible({ timeout: 10_000 });

  const steps = page.getByTestId('checkout-step');
  await expect(steps).toHaveCount(1);
});

5. Scenario: Flag Payload Drives Dynamic Configuration

PostHog feature flag payloads let you attach arbitrary JSON data to each flag variant. Instead of hardcoding configuration per variant in your frontend code, you read the payload from PostHog and use it to drive rendering. This is powerful for A/B testing copy, colors, pricing values, and other parameters without deploying new code. But it also means your tests need to verify both the flag value and the payload content separately, because a correct variant with a malformed payload will still break the UI.

6. Scenario: Bootstrap Flags for SSR Without Flicker

When you use server-side rendering with PostHog, the server evaluates feature flags via the PostHog Node SDK and embeds the results into the HTML. On the client side, you pass these pre-evaluated flags as the bootstrap option in posthog.init(). This eliminates the flash of default content that happens while the client SDK calls /decide. But bootstrapping introduces a subtle failure mode: if the server and client evaluate the flag differently (because the flag was updated between the server render and the client hydration), the UI will switch from one variant to another after hydration. Your test must detect this flicker.

7. Scenario: Verifying Rollout Percentage Distribution

Rollout percentages are one of the most misunderstood aspects of feature flags. A flag set to 30% rollout does not mean "30% of page loads see it." It means 30% of distinct user IDs hash into the enabled bucket. PostHog uses a deterministic hashing algorithm (based on the distinct ID and flag key) so the same user always gets the same result. This is great for user consistency but makes statistical verification in tests more nuanced. You cannot just run 100 requests and expect exactly 30 to be enabled.

8. Scenario: Local Overrides for Deterministic CI

The biggest problem with testing feature flags in CI is nondeterminism. If your tests rely on the live PostHog API, a flag change in the dashboard during a test run can cause unexpected failures. The solution is local flag overrides: intercept every PostHog API call in your test and return predetermined values. This removes the network dependency entirely and makes your tests deterministic, fast, and runnable offline.

PostHog supports two override mechanisms. First, the JavaScript SDK accepts a bootstrap property at initialization time that provides flag values synchronously. Second, you can call posthog.featureFlags.override() after initialization to force specific flag values for the current session. In Playwright tests, the cleanest approach is route interception because it works regardless of how your app initializes the SDK.

import { test, expect } from '../fixtures/posthog-override';

test('deterministic flag test', async ({ page, posthog }) => {
  await posthog.withFlags({
    'new-pricing-banner': true,
    'checkout-flow-experiment': 'wizard',
    'promo-banner-config': 'active',
  }, {
    'promo-banner-config': JSON.stringify({
      cta_text: 'Limited time offer',
      discount_percent: 25,
    }),
  });

  await page.goto('/');

  await expect(page.getByTestId('pricing-banner')).toBeVisible();
  await expect(page.getByText('Limited time offer')).toBeVisible();
});

9. Common Pitfalls That Break Feature Flag Test Suites

Feature flag testing has a unique set of failure modes that differ from standard UI testing. These pitfalls come from real PostHog GitHub issues, community discussions, and production incident reports. Understanding them before you build your test suite will save you hours of debugging flaky tests.

10. Writing These Scenarios in Plain English with Assrt

Every Playwright test in this guide follows the same pattern: intercept the PostHog /decide endpoint, override the flag values, navigate to the page, and assert the UI matches the expected variant. That pattern is powerful but verbose. Each scenario requires 20 to 40 lines of TypeScript with route interception boilerplate, JSON body manipulation, and explicit timeout management. Assrt lets you express the same intent in plain English and compiles it to the same Playwright code.

Assrt compiles each scenario block into the same Playwright TypeScript shown in the preceding sections. The route interception boilerplate, JSON body manipulation, and timeout handling are all generated automatically. When PostHog changes their /decide API response format or your app restructures its flag-gated components, Assrt detects the failure, analyzes the updated DOM and API responses, and opens a pull request with the updated test code. Your scenario files stay untouched.

Start with the boolean flag scenario. Once it passes in CI, add the multivariate test, then the payload verification, then the SSR bootstrap flicker check, then the local overrides fixture. Within an afternoon you will have complete feature flag coverage that most teams never achieve because the interception boilerplate is too tedious to maintain by hand.