chore: adding predefined sdk wrappers for test data (#1413)

This PR will create test data wrappers for `js-client-sdk` and
`react-sdk` to make the tooling more ergonomic.

This PR will also pull in the eslint upgrade.

NOTE: we did not wrap the `react-native-sdk` test data wrapper because
unit testing react native in this way requires a much more robust setup
that we are not pursuing yet.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Test-only tooling and package exports with no production SDK behavior
changes; ESLint upgrade is confined to this package.
> 
> **Overview**
> Adds ergonomic **offline test helpers** for
`@launchdarkly/js-client-sdk` and `@launchdarkly/react-sdk` via new
subpath exports `@launchdarkly/client-testing-plugin/js-client-sdk` and
`.../react-sdk`.
> 
> Each **`createTestClient`** builds a client with `TestData` appended
after any user `plugins`, plus `sendEvents: false` and `streaming:
false`, and returns `{ client, testData }` so tests can seed
`initialFlags` and mutate flags at runtime. The React entry also exposes
**`createTestClientProvider`**, which pairs the same client with a
pre-wired Provider from `createLDReactProviderWithClient`.
> 
> **Build and packaging:** `tsup` now emits the two client modules;
**optional peer dependencies** on the JS and React SDKs were added so
consumers import only what they need. **Jest** coverage verifies
seeding, plugin composition, dynamic overrides, and the React Provider
helper. Lint tooling in this package was bumped to **ESLint 9** with
updated scripts.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
c790a1a. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: joker23

packages/tooling/client-testing-plugin/__tests__/clients/js-client-sdk.test.ts

@@ -0,0 +1,62 @@
+/**
+ * @jest-environment jsdom
+ */
+import { createTestClient } from '../../src/clients/js-client-sdk';
+import TestData from '../../src/TestData';
+
+afterEach(async () => {
+  // close any leaked clients via global registry would be nicer; for now,
+  // each test that constructs a client is responsible for closing it.
+});
+
+it('seeds the TestData with initialFlags', async () => {
+  const { client, testData } = createTestClient(
+    { kind: 'user', key: 'tester' },
+    { 'bool-flag': true, greeting: 'hello' },
+  );
+  await client.start({ bootstrap: {} });
+
+  expect(testData).toBeInstanceOf(TestData);
+  expect(client.boolVariation('bool-flag', false)).toBe(true);
+  expect(client.stringVariation('greeting', 'default')).toBe('hello');
+
+  await client.close();
+});
+
+it('appends TestData to user-supplied plugins rather than replacing them', async () => {
+  const userPluginRegisterDebug = jest.fn();
+  const userPlugin = {
+    getMetadata: () => ({ name: 'user-plugin' }),
+    register: jest.fn(),
+    registerDebug: userPluginRegisterDebug,
+  };
+
+  const { client, testData } = createTestClient(
+    { kind: 'user', key: 'tester' },
+    { 'bool-flag': true },
+    { plugins: [userPlugin] },
+  );
+  await client.start({ bootstrap: {} });
+
+  expect(userPluginRegisterDebug).toHaveBeenCalled();
+  expect(client.boolVariation('bool-flag', false)).toBe(true);
+  // testData is still the TestData we returned, not shadowed by the user plugin
+  expect(testData).toBeInstanceOf(TestData);
+
+  await client.close();
+});
+
+it('updates flag values dynamically via testData after the client is started', async () => {
+  const { client, testData } = createTestClient(
+    { kind: 'user', key: 'tester' },
+    { 'show-banner': true },
+  );
+  await client.start({ bootstrap: {} });
+
+  expect(client.boolVariation('show-banner', false)).toBe(true);
+
+  testData.setBool('show-banner', false);
+  expect(client.boolVariation('show-banner', true)).toBe(false);
+
+  await client.close();
+});

packages/tooling/client-testing-plugin/__tests__/clients/react-sdk.test.ts

@@ -0,0 +1,65 @@
+/**
+ * @jest-environment jsdom
+ */
+import { createTestClient, createTestClientProvider } from '../../src/clients/react-sdk';
+import TestData from '../../src/TestData';
+
+it('seeds the TestData with initialFlags and resolves overrides after start', async () => {
+  const { client, testData } = createTestClient(
+    { kind: 'user', key: 'tester' },
+    { 'bool-flag': true, greeting: 'hello' },
+  );
+  await client.start({ bootstrap: {} });
+
+  expect(testData).toBeInstanceOf(TestData);
+  expect(client.boolVariation('bool-flag', false)).toBe(true);
+  expect(client.stringVariation('greeting', 'default')).toBe('hello');
+
+  await client.close();
+});
+
+it('appends TestData to user-supplied plugins rather than replacing them', async () => {
+  const userPluginRegisterDebug = jest.fn();
+  const userPlugin = {
+    getMetadata: () => ({ name: 'user-plugin' }),
+    register: jest.fn(),
+    registerDebug: userPluginRegisterDebug,
+  };
+
+  const { client } = createTestClient(
+    { kind: 'user', key: 'tester' },
+    { 'bool-flag': true },
+    { plugins: [userPlugin] },
+  );
+  await client.start({ bootstrap: {} });
+
+  expect(userPluginRegisterDebug).toHaveBeenCalled();
+  expect(client.boolVariation('bool-flag', false)).toBe(true);
+
+  await client.close();
+});
+
+it('createTestClientProvider returns a pre-wired Provider, client, and testData', () => {
+  const { Provider, client, testData } = createTestClientProvider(
+    { kind: 'user', key: 'tester' },
+    { 'show-banner': true },
+  );
+  expect(Provider).toBeInstanceOf(Function);
+  expect(client).toBeDefined();
+  expect(testData).toBeInstanceOf(TestData);
+});
+
+it('updates flag values dynamically via testData after the client is started', async () => {
+  const { client, testData } = createTestClient(
+    { kind: 'user', key: 'tester' },
+    { 'show-banner': true },
+  );
+  await client.start({ bootstrap: {} });
+
+  expect(client.boolVariation('show-banner', false)).toBe(true);
+
+  testData.setBool('show-banner', false);
+  expect(client.boolVariation('show-banner', true)).toBe(false);
+
+  await client.close();
+});

packages/tooling/client-testing-plugin/package.json

@@ -23,6 +23,18 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs",
       "default": "./dist/index.js"
+    },
+    "./js-client-sdk": {
+      "types": "./dist/clients/js-client-sdk.d.ts",
+      "import": "./dist/clients/js-client-sdk.js",
+      "require": "./dist/clients/js-client-sdk.cjs",
+      "default": "./dist/clients/js-client-sdk.js"
+    },
+    "./react-sdk": {
+      "types": "./dist/clients/react-sdk.d.ts",
+      "import": "./dist/clients/react-sdk.js",
+      "require": "./dist/clients/react-sdk.cjs",
+      "default": "./dist/clients/react-sdk.js"
     }
   },
   "files": [
@@ -32,24 +44,40 @@
     "clean": "rimraf dist",
     "build": "tsup",
     "test": "npx jest --ci",
-    "lint": "eslint . --ext .ts,.tsx"
+    "lint": "eslint .",
+    "lint:fix": "yarn run lint --fix"
   },
   "dependencies": {
     "@launchdarkly/js-client-sdk-common": "workspace:^"
   },
+  "peerDependencies": {
+    "@launchdarkly/js-client-sdk": "workspace:^",
+    "@launchdarkly/react-sdk": "workspace:^"
+  },
+  "peerDependenciesMeta": {
+    "@launchdarkly/js-client-sdk": {
+      "optional": true
+    },
+    "@launchdarkly/react-sdk": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@eslint/js": "^9.0.0",
     "@launchdarkly/js-client-sdk": "workspace:^",
+    "@launchdarkly/react-sdk": "workspace:^",
     "@types/jest": "^29.5.0",
-    "@typescript-eslint/eslint-plugin": "^6.20.0",
-    "@typescript-eslint/parser": "^6.20.0",
-    "eslint": "^8.45.0",
-    "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-jest": "^27.6.3",
+    "eslint": "^9.0.0",
+    "eslint-import-resolver-typescript": "^4.0.0",
+    "eslint-plugin-import-x": "^4.0.0",
+    "eslint-plugin-jest": "^28.0.0",
+    "globals": "^16.0.0",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.0.0",
     "rimraf": "6.0.1",
     "ts-jest": "^29.1.1",
     "tsup": "^8.5.1",
-    "typescript": "5.1.6"
+    "typescript": "5.1.6",
+    "typescript-eslint": "^8.0.0"
   }
 }

packages/tooling/client-testing-plugin/src/clients/js-client-sdk.ts

@@ -0,0 +1,38 @@
+import type { LDFlagValue } from '@launchdarkly/js-client-sdk-common';
+import type { LDClient, LDContext, LDOptions } from '@launchdarkly/js-client-sdk';
+import { createClient } from '@launchdarkly/js-client-sdk';
+
+import TestData from '../TestData';
+
+const TEST_CLIENT_SIDE_ID = 'client-testing-plugin';
+
+export interface CreateTestClientResult {
+  client: LDClient;
+  testData: TestData;
+}
+
+/**
+ * Creates a `@launchdarkly/js-client-sdk` client wired with the `TestData`
+ * plugin and the settings required for offline test usage.
+ *
+ * @param context the LDContext to identify the test client as
+ * @param initialFlags optional seed map of flag keys to values
+ * @param options optional LDOptions
+ *
+ * @returns an object containing the test client and test data
+ */
+export function createTestClient(
+  context: LDContext,
+  initialFlags?: { [key: string]: LDFlagValue },
+  options?: Partial<LDOptions>,
+): CreateTestClientResult {
+  const testData = new TestData(initialFlags);
+  const userPlugins = options?.plugins ?? [];
+  const client = createClient(TEST_CLIENT_SIDE_ID, context, {
+    ...options,
+    plugins: [...userPlugins, testData],
+    sendEvents: false,
+    streaming: false,
+  });
+  return { client, testData };
+}

packages/tooling/client-testing-plugin/src/clients/react-sdk.ts

@@ -0,0 +1,64 @@
+import type { LDFlagValue } from '@launchdarkly/js-client-sdk-common';
+import type { LDContext, LDReactClient, LDReactClientOptions } from '@launchdarkly/react-sdk';
+import { createClient, createLDReactProviderWithClient } from '@launchdarkly/react-sdk';
+
+import TestData from '../TestData';
+
+const TEST_CLIENT_SIDE_ID = 'client-testing-plugin';
+
+export interface CreateTestClientResult {
+  client: LDReactClient;
+  testData: TestData;
+}
+
+export interface CreateTestClientProviderResult {
+  Provider: ReturnType<typeof createLDReactProviderWithClient>;
+  client: LDReactClient;
+  testData: TestData;
+}
+
+/**
+ * Creates a `@launchdarkly/react-sdk` client wired with the `TestData` plugin
+ * and the settings required for offline test usage.
+ *
+ * @param context the LDContext to identify the test client as
+ * @param initialFlags optional seed map of flag keys to values
+ * @param options optional react-sdk options
+ *
+ * @returns an object containing the test client and test data
+ */
+export function createTestClient(
+  context: LDContext,
+  initialFlags?: { [key: string]: LDFlagValue },
+  options?: Partial<LDReactClientOptions>,
+): CreateTestClientResult {
+  const testData = new TestData(initialFlags);
+  const userPlugins = options?.plugins ?? [];
+  const client = createClient(TEST_CLIENT_SIDE_ID, context, {
+    ...options,
+    plugins: [...userPlugins, testData],
+    sendEvents: false,
+    streaming: false,
+  });
+  return { client, testData };
+}
+
+/**
+ * Creates a `@launchdarkly/react-sdk` client and a pre-wired Provider component,
+ * ready to wrap components under test.
+ *
+ * @param context the LDContext to identify the test client as
+ * @param initialFlags optional seed map of flag keys to values
+ * @param options optional react-sdk options
+ *
+ * @returns an object containing the Provider component, client, and testData
+ */
+export function createTestClientProvider(
+  context: LDContext,
+  initialFlags?: { [key: string]: LDFlagValue },
+  options?: Partial<LDReactClientOptions>,
+): CreateTestClientProviderResult {
+  const { client, testData } = createTestClient(context, initialFlags, options);
+  const Provider = createLDReactProviderWithClient(client);
+  return { Provider, client, testData };
+}

packages/tooling/client-testing-plugin/tsup.config.js

@@ -2,7 +2,11 @@ import { defineConfig } from 'tsup';
 
 export default defineConfig([
   {
-    entry: { index: 'src/index.ts' },
+    entry: {
+      'index': 'src/index.ts',
+      'clients/js-client-sdk': 'src/clients/js-client-sdk.ts',
+      'clients/react-sdk': 'src/clients/react-sdk.ts',
+    },
     format: ['esm', 'cjs'],
     dts: true,
     clean: true,