chore: init @launchdarkly/client-testing-plugin

Author: joker23

.gitignore

@@ -28,5 +28,5 @@ stats.html
 .env.local
 .env.*.local
 .claude/worktrees
-.claude/stacks
+.claude/tmp
 .mcp.json

package.json

@@ -40,6 +40,7 @@
     "packages/store/node-server-sdk-redis",
     "packages/store/node-server-sdk-dynamodb",
     "packages/telemetry/node-server-sdk-otel",
+    "packages/tooling/client-testing-plugin",
     "packages/tooling/contract-test-utils",
     "packages/tooling/jest",
     "packages/tooling/jest/example/react-native-example",

packages/tooling/client-testing-plugin/README.md

@@ -0,0 +1,72 @@
+# LaunchDarkly Client Testing Plugin
+
+A testing plugin for LaunchDarkly client-side JavaScript SDKs. Use it to inject deterministic flag values into a real SDK client during unit tests, integration tests, and local development.
+
+## Install
+
+```bash
+yarn add --dev @launchdarkly/client-testing-plugin @launchdarkly/js-client-sdk
+```
+
+## Usage
+
+```ts
+import { createClient } from '@launchdarkly/js-client-sdk';
+import { TestData } from '@launchdarkly/client-testing-plugin';
+
+// Seed with a base set of flag values.
+const td = new TestData({
+  'new-ui': true,
+  greeting: 'Hello!',
+});
+
+const client = createClient(
+  '<ldClientSideId>', // placeholder -- fill in only for real environments
+  { kind: 'user', key: 'tester' },
+  {
+    plugins: [td],
+    sendEvents: false,
+    streaming: false,
+  },
+);
+
+await client.start({ bootstrap: {} });
+
+client.boolVariation('new-ui', false);          // true
+client.stringVariation('greeting', '(default)'); // 'Hello!'
+
+// Update flags at any time -- the SDK fires change events. Setters chain.
+td.setBool('new-ui', false).setString('greeting', 'Welcome');
+```
+
+### Why these options matter
+
+- **`plugins: [td]`** -- registers the testing plugin so it can inject overrides.
+- **`sendEvents: false`** -- keeps analytics events off in tests.
+- **`streaming: false`** -- prevents the SDK from auto-starting a streaming connection when a `change` listener is registered. Without this, the React SDK provider (and any other code that registers `change` listeners) will trigger a real network call to `clientstream.launchdarkly.com`.
+- **`bootstrap: {}` (passed to `start()`)** -- gives the SDK an empty initial flag set so it does not block on a network identify call. The plugin's overrides are applied immediately afterward.
+
+If you forget any of these, the SDK may attempt to fetch flags from LaunchDarkly during initialization and produce real network traffic, console errors, or stray evaluation events.
+
+## API
+
+### `TestData`
+
+```ts
+class TestData implements LDPlugin {
+  constructor(initialFlags?: { [key: string]: LDFlagValue });
+
+  setBool(key: string, value: boolean): this;
+  setString(key: string, value: string): this;
+  setNumber(key: string, value: number): this;
+  setJson(key: string, value: object | unknown[]): this;
+
+  remove(key: string): this;
+  clear(): this;
+}
+```
+
+- **`new TestData(initialFlags?)`** -- seed the instance with a base map of flag keys to values. The values are applied to the SDK client when it initializes.
+- **`setBool` / `setString` / `setNumber` / `setJson`** -- set or update a single flag. If the SDK is already running, the change propagates immediately and listeners receive a `change:<key>` event. Updates dedup by reference equality (`===`); pass a fresh object/array reference if you want a change event after mutating a previous value.
+- **`remove(key)`** -- drop the override for a single key. If the SDK is connected, also calls `removeOverride`.
+- **`clear()`** -- drop all overrides. Useful in `beforeEach` for shared `TestData` instances.

packages/tooling/client-testing-plugin/__tests__/TestData.test.ts

@@ -0,0 +1,214 @@
+import type { LDDebugOverride } from '@launchdarkly/js-client-sdk-common';
+
+import TestData from '../src/TestData';
+
+function createMockDebugOverride(): LDDebugOverride & {
+  overrides: Record<string, unknown>;
+} {
+  const overrides: Record<string, unknown> = {};
+  return {
+    overrides,
+    setOverride: jest.fn((key: string, value: unknown) => {
+      overrides[key] = value;
+    }),
+    removeOverride: jest.fn((key: string) => {
+      delete overrides[key];
+    }),
+    clearAllOverrides: jest.fn(() => {
+      Object.keys(overrides).forEach((k) => delete overrides[k]);
+    }),
+    getAllOverrides: jest.fn(() => ({})),
+  };
+}
+
+describe('TestData', () => {
+  it('returns correct plugin metadata', () => {
+    expect(new TestData().getMetadata()).toEqual({ name: 'test-data' });
+  });
+
+  it('register is a no-op', () => {
+    const td = new TestData();
+    expect(() =>
+      td.register(undefined, {
+        sdk: { name: 'test', version: '0.0.0' },
+        clientSideId: 'test-key',
+      } as never),
+    ).not.toThrow();
+  });
+
+  it('seeds initial flags from the constructor and applies them on registerDebug', () => {
+    const td = new TestData({
+      'show-banner': true,
+      greeting: 'Hello',
+      'max-retries': 3,
+      config: { theme: 'dark' },
+    });
+
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    expect(debugOverride.overrides['show-banner']).toBe(true);
+    expect(debugOverride.overrides.greeting).toBe('Hello');
+    expect(debugOverride.overrides['max-retries']).toBe(3);
+    expect(debugOverride.overrides.config).toEqual({ theme: 'dark' });
+  });
+
+  it('typed setters chain and apply pre-registration', () => {
+    const td = new TestData()
+      .setBool('show-banner', true)
+      .setString('greeting', 'Hello')
+      .setNumber('max-retries', 3)
+      .setJson('config', { theme: 'dark' });
+
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    expect(debugOverride.overrides['show-banner']).toBe(true);
+    expect(debugOverride.overrides.greeting).toBe('Hello');
+    expect(debugOverride.overrides['max-retries']).toBe(3);
+    expect(debugOverride.overrides.config).toEqual({ theme: 'dark' });
+  });
+
+  it('typed setters propagate live updates after registration', () => {
+    const td = new TestData();
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    td.setBool('show-banner', true);
+    expect(debugOverride.setOverride).toHaveBeenCalledWith('show-banner', true);
+
+    td.setString('greeting', 'Howdy');
+    expect(debugOverride.setOverride).toHaveBeenCalledWith('greeting', 'Howdy');
+
+    td.setNumber('max-retries', 5);
+    expect(debugOverride.setOverride).toHaveBeenCalledWith('max-retries', 5);
+
+    td.setJson('config', [1, 2, 3]);
+    expect(debugOverride.setOverride).toHaveBeenCalledWith('config', [1, 2, 3]);
+  });
+
+  it('skips setOverride when the same primitive value is set twice', () => {
+    const td = new TestData();
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    td.setBool('flag', true);
+    expect(debugOverride.setOverride).toHaveBeenCalledTimes(1);
+
+    td.setBool('flag', true);
+    expect(debugOverride.setOverride).toHaveBeenCalledTimes(1);
+
+    td.setBool('flag', false);
+    expect(debugOverride.setOverride).toHaveBeenCalledTimes(2);
+  });
+
+  it('dedups by reference equality, so passing a new object always fires', () => {
+    const td = new TestData();
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    td.setJson('cfg', { showBanner: true });
+    expect(debugOverride.setOverride).toHaveBeenCalledTimes(1);
+
+    // New object reference -- fires even though structurally identical.
+    td.setJson('cfg', { showBanner: true });
+    expect(debugOverride.setOverride).toHaveBeenCalledTimes(2);
+
+    // Same reference twice in a row -- deduped.
+    const same = { showBanner: false };
+    td.setJson('cfg', same);
+    td.setJson('cfg', same);
+    expect(debugOverride.setOverride).toHaveBeenCalledTimes(3);
+  });
+
+  it('remove clears stored state and the active override', () => {
+    const td = new TestData({ flag: true });
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    td.remove('flag');
+
+    expect(debugOverride.removeOverride).toHaveBeenCalledWith('flag');
+    expect(debugOverride.overrides.flag).toBeUndefined();
+  });
+
+  it('remove before registerDebug prevents the flag from being applied later', () => {
+    const td = new TestData({ flag: true });
+    td.remove('flag');
+
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    expect(debugOverride.setOverride).not.toHaveBeenCalled();
+    expect(debugOverride.overrides.flag).toBeUndefined();
+  });
+
+  it('clear resets all flags and clears the override interface', () => {
+    const td = new TestData({ a: true, b: 'x' });
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    td.clear();
+
+    expect(debugOverride.clearAllOverrides).toHaveBeenCalledTimes(1);
+  });
+
+  it('clear before registerDebug drops queued flags', () => {
+    const td = new TestData({ a: true });
+    td.clear();
+
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    expect(debugOverride.setOverride).not.toHaveBeenCalled();
+  });
+
+  it('throws if registerDebug is called twice', () => {
+    const td = new TestData();
+    td.registerDebug(createMockDebugOverride());
+
+    expect(() => td.registerDebug(createMockDebugOverride())).toThrow(
+      /already been registered/,
+    );
+  });
+
+  it('setJson rejects undefined and other non-object values', () => {
+    const td = new TestData();
+    expect(() => td.setJson('flag', undefined as unknown as object)).toThrow(TypeError);
+    expect(() => td.setJson('flag', null as unknown as object)).toThrow(TypeError);
+    expect(() => td.setJson('flag', 'string' as unknown as object)).toThrow(TypeError);
+    expect(() => td.setJson('flag', 42 as unknown as object)).toThrow(TypeError);
+  });
+
+  it('dedups NaN values via Object.is semantics', () => {
+    const td = new TestData();
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    td.setNumber('flag', NaN);
+    expect(debugOverride.setOverride).toHaveBeenCalledTimes(1);
+
+    td.setNumber('flag', NaN);
+    expect(debugOverride.setOverride).toHaveBeenCalledTimes(1);
+
+    td.setNumber('flag', 0);
+    expect(debugOverride.setOverride).toHaveBeenCalledTimes(2);
+  });
+
+  it('remove and clear return this for chaining', () => {
+    const td = new TestData({ a: true, b: 'x' });
+    expect(td.remove('a')).toBe(td);
+    expect(td.clear()).toBe(td);
+  });
+
+  it('handles flag keys that collide with Object prototype names safely', () => {
+    const td = new TestData();
+    const debugOverride = createMockDebugOverride();
+    td.registerDebug(debugOverride);
+
+    td.setString('toString', 'overridden').setNumber('hasOwnProperty', 42);
+
+    expect(debugOverride.setOverride).toHaveBeenCalledWith('toString', 'overridden');
+    expect(debugOverride.setOverride).toHaveBeenCalledWith('hasOwnProperty', 42);
+  });
+});