How to Test LaunchDarkly Flags with Playwright: Complete 2026 Guide

1. Why Testing LaunchDarkly Flags Is Harder Than It Looks

Feature flags look simple on the surface: a boolean that toggles a code path. In practice, LaunchDarkly flags introduce several layers of indirection that make end-to-end testing genuinely difficult. The SDK evaluates flags client-side using a context object (user key, email, custom attributes), and the evaluation result depends on targeting rules, percentage rollouts, and prerequisite flags configured in the LaunchDarkly dashboard. Your test needs to control all of those inputs to get deterministic output.

The first structural challenge is timing. The LaunchDarkly JavaScript SDK initializes asynchronously. When your React app mounts, it calls LDClient.initialize()with a client-side ID and a context object. The SDK fetches the evaluated flag values from LaunchDarkly's edge CDN, and only then does your app know which variation to render. If your Playwright test checks the DOM before the SDK has initialized, you will see the default (fallback) value, not the actual flag value. This race condition is the most common source of flaky flag tests.

The second challenge is evaluation context. LaunchDarkly evaluates flags per context: a combination of user key, anonymous flag, custom attributes like plan or country, and multi-context kinds (user, organization, device). If your test does not control the exact context the SDK sends, you cannot predict which variation the flag will return. Percentage rollouts hash the context key to assign a bucket, so even a different test user email changes the outcome.

Third, streaming adds real-time complexity. In streaming mode (the default for browser SDKs), the SDK opens a Server-Sent Events connection to LaunchDarkly. When someone changes a flag in the dashboard mid-test, the SDK receives the update and triggers a re-render. This is powerful for production, but in tests it means your flag values can change underneath you if another developer modifies the test environment. Polling mode avoids the real-time updates but introduces its own timing issues because flag changes only take effect after the next poll interval.

Fourth, the LaunchDarkly test data source (the recommended approach for unit and integration tests) works differently from the production SDK initialization path. Tests that pass with the test data source may fail in production because of subtle differences in initialization timing, event flushing, and context evaluation. Your end-to-end tests need to cover both the happy path with real SDK initialization and the controlled path with test data.

A thorough LaunchDarkly test suite must account for all of these surfaces. The sections below walk through each scenario with runnable Playwright TypeScript you can paste directly into your project.

2. Setting Up a Reliable Test Environment

Before writing any test scenarios, configure an isolated LaunchDarkly environment for testing. LaunchDarkly supports multiple environments per project (Development, Staging, Production). Create a dedicated test environment that your CI pipeline uses exclusively. This prevents developers from accidentally changing flag values that your tests depend on.

Environment Variables

REST API Helper for Flag State Management

The LaunchDarkly REST API lets you programmatically toggle flags, update targeting rules, and add individual targets before each test. This is essential for deterministic test setup. Use semantic patch operations to modify flag configurations without overwriting the entire flag definition.

Playwright Configuration for LaunchDarkly

LaunchDarkly SDK initialization is asynchronous, so your Playwright tests need to wait for the SDK to be ready before asserting on flag-dependent UI. The most reliable pattern is to expose a global ready signal from your app and wait for it in your test setup.

3. Scenario: Boolean Flag Controls a UI Component

The most common flag type is a simple boolean that shows or hides a UI component. For example, a new-dashboard flag that controls whether users see the redesigned dashboard or the legacy version. The test must verify both variations render correctly and that the toggle is responsive to flag changes.

import { test, expect } from '@playwright/test';
import { addUserTarget } from '../helpers/ld-api';

test('new dashboard visible when flag on', async ({ page }) => {
  await addUserTarget('new-dashboard', 0, 'e2e-test-user-001');
  await page.goto('/dashboard');
  await page.waitForFunction(
    () => (window as any).__LD_READY__ === true
  );
  await expect(
    page.getByTestId('new-dashboard-panel')
  ).toBeVisible();
});

4. Scenario: Multivariate Flag with String Variations

Not all flags are simple on/off toggles. LaunchDarkly supports multivariate flags that return strings, numbers, or JSON objects. A common pattern is a string flag that selects between multiple UI themes or checkout flow versions: "control", "variant-a", and "variant-b". Testing these requires iterating over every variation and verifying each one renders the correct UI.

5. Scenario: Targeting Rules and User Segments

Targeting rules are where LaunchDarkly flags get complex. A single flag can have multiple rules that evaluate in order: "if user is in segment 'beta-testers' serve variation 1, else if user attribute 'plan' equals 'enterprise' serve variation 2, else serve the default." Testing this requires creating contexts with specific attributes and verifying each rule fires correctly.

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

test('enterprise user gets premium features', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('enterprise@yourapp.com');
  await page.getByLabel('Password').fill('TestPass123!');
  await page.getByRole('button', { name: /sign in/i }).click();
  await page.waitForURL('/dashboard');
  await page.waitForFunction(
    () => (window as any).__LD_READY__ === true
  );
  await expect(page.getByTestId('premium-analytics')).toBeVisible();
  await expect(page.getByTestId('premium-exports')).toBeVisible();
  await expect(page.getByTestId('premium-api-access')).toBeVisible();
});

6. Scenario: Real-Time Flag Changes via Streaming

One of LaunchDarkly's most powerful features is real-time flag updates via Server-Sent Events (SSE). When a flag changes in the dashboard, the browser SDK receives the update within milliseconds and triggers a re-render. Testing this behavior requires changing a flag value while the page is loaded and verifying the UI updates without a page refresh. This is also the scenario most likely to introduce flakiness if not handled carefully.

7. Scenario: Using the Test Data Source for Deterministic Tests

LaunchDarkly provides a TestDatasource that lets you create a fully local, in-process flag evaluation engine. Instead of connecting to LaunchDarkly's servers, the SDK evaluates flags against data you define in your test setup. This eliminates network latency, rate limits, and cross-test interference. It is the recommended approach for integration tests and can also be used for end-to-end tests when you control the app's initialization.

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

test('override flags via route interception', async ({ page }) => {
  await page.route('**/sdk/evalx/**', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({
        'new-dashboard': {
          value: true, variation: 0, version: 100,
          reason: { kind: 'FALLTHROUGH' },
        },
      }),
    });
  });
  await page.goto('/dashboard');
  await page.waitForFunction(
    () => (window as any).__LD_READY__ === true
  );
  await expect(page.getByTestId('new-dashboard-panel')).toBeVisible();
});

8. Scenario: Testing Fallback Behavior When LD Is Unavailable

What happens when LaunchDarkly is down? Your app should degrade gracefully, falling back to default flag values. This is a critical scenario that most teams skip. The LaunchDarkly SDK caches flag values in localStorage (browser) or in memory (server-side), so a temporary outage should not break your app. But you need to verify that the fallback values are correct and that the app renders a reasonable experience.

9. Common Pitfalls That Break Feature Flag Test Suites

These are real problems sourced from LaunchDarkly community forums, GitHub issues, and Stack Overflow threads. Each one has broken production test suites and wasted hours of debugging time.

The Initialization Race Condition in Detail

The most insidious pitfall is the initialization timing issue. The LaunchDarkly JavaScript SDK exposes a ready event and a waitForInitialization() promise. If your React app renders before the SDK is ready, all flag evaluations return fallback values. The fix is to gate your app's render on the SDK's ready event. In your app code, expose a global signal that your tests can wait for.

10. Writing These Scenarios in Plain English with Assrt

The Playwright tests above work, but they require deep knowledge of the LaunchDarkly SDK, API, and evaluation model. Every team member who reads or maintains these tests needs to understand route interception, SSE streams, context evaluation, and the LD REST API's semantic patch format. Assrt lets you express the same test intent in plain English.

Here is the real-time streaming scenario (Section 6) compiled into an Assrt file. Assrt handles the LaunchDarkly API calls, SDK initialization wait, and UI assertions behind the scenes.

Compare the 60+ lines of Playwright code for the streaming test (including the API helper, route interception, SSE monitoring, and navigation checks) with the 16 lines of Assrt above. The test intent is identical. The difference is that Assrt encapsulates the LaunchDarkly integration details so your test reads like a specification, not an implementation.

For the targeting rules scenario (Section 5), the Assrt version eliminates the login ceremony, the SDK wait boilerplate, and the manual attribute matching. You declare which user should see which features, and Assrt handles the rest.

Each of these Assrt files can run against your real app, against a staging environment, or against a local dev server. Assrt translates the plain-English steps into the same Playwright API calls, LD REST API operations, and SDK initialization waits that you would write by hand. The advantage is that anyone on your team can read, write, and review these tests without being a LaunchDarkly SDK expert.