|
1 | 1 | # LaunchDarkly Client Testing Plugin |
2 | 2 |
|
| 3 | +[![NPM][client-testing-plugin-npm-badge]][client-testing-plugin-npm-link] |
| 4 | +[![Actions Status][client-testing-plugin-ci-badge]][client-testing-plugin-ci] |
| 5 | +[![Documentation][client-testing-plugin-ghp-badge]][client-testing-plugin-ghp-link] |
| 6 | +[![NPM][client-testing-plugin-dm-badge]][client-testing-plugin-npm-link] |
| 7 | +[![NPM][client-testing-plugin-dt-badge]][client-testing-plugin-npm-link] |
| 8 | + |
| 9 | +> [!CAUTION] |
| 10 | +> This plugin is in pre-release and not subject to backwards compatibility |
| 11 | +> guarantees. The API may change based on feedback. |
| 12 | +> |
| 13 | +> Pin to a specific minor version and review the [changelog](CHANGELOG.md) before upgrading. |
| 14 | +
|
3 | 15 | 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. |
4 | 16 |
|
5 | 17 | ## Install |
6 | 18 |
|
7 | 19 | ```bash |
8 | | -yarn add --dev @launchdarkly/client-testing-plugin @launchdarkly/js-client-sdk |
| 20 | +yarn add --dev @launchdarkly/client-testing-plugin |
| 21 | +``` |
| 22 | + |
| 23 | +You also need the client-side SDK you're testing against. The plugin declares each supported SDK as an optional peer dependency, so only install the one you use: |
| 24 | + |
| 25 | +```bash |
| 26 | +# pick one |
| 27 | +yarn add --dev @launchdarkly/js-client-sdk |
| 28 | +yarn add --dev @launchdarkly/react-sdk |
9 | 29 | ``` |
10 | 30 |
|
11 | 31 | ## Usage |
12 | 32 |
|
13 | | -```ts |
14 | | -import { createClient } from '@launchdarkly/js-client-sdk'; |
15 | | -import { TestData } from '@launchdarkly/client-testing-plugin'; |
| 33 | +The plugin ships a small per-SDK wrapper under a subpath export. Each wrapper returns a real SDK client with `TestData` already registered and the required test settings applied -- no boilerplate. |
16 | 34 |
|
17 | | -// Seed with a base set of flag values. |
18 | | -const td = new TestData({ |
19 | | - 'new-ui': true, |
20 | | - greeting: 'Hello!', |
21 | | -}); |
| 35 | +### `@launchdarkly/js-client-sdk` |
22 | 36 |
|
23 | | -const client = createClient( |
24 | | - '<ldClientSideId>', // placeholder -- fill in only for real environments |
| 37 | +```ts |
| 38 | +import { createTestClient } from '@launchdarkly/client-testing-plugin/js-client-sdk'; |
| 39 | + |
| 40 | +const { client, testData } = createTestClient( |
25 | 41 | { kind: 'user', key: 'tester' }, |
26 | | - { |
27 | | - plugins: [td], |
28 | | - sendEvents: false, |
29 | | - streaming: false, |
30 | | - }, |
| 42 | + { 'new-ui': true, greeting: 'Hello!' }, |
31 | 43 | ); |
32 | 44 |
|
33 | 45 | await client.start({ bootstrap: {} }); |
34 | 46 |
|
35 | 47 | client.boolVariation('new-ui', false); // true |
36 | 48 | client.stringVariation('greeting', '(default)'); // 'Hello!' |
37 | 49 |
|
38 | | -// Update flags at any time -- the SDK fires change events. Setters chain. |
39 | | -td.setBool('new-ui', false).setString('greeting', 'Welcome'); |
| 50 | +// Update flags at any time - the SDK fires change events. Setters chain. |
| 51 | +testData.setBool('new-ui', false).setString('greeting', 'Welcome'); |
40 | 52 | ``` |
41 | 53 |
|
42 | | -### Required LD client options |
43 | | -In order to successfully set up a LD client to use the testing plugin, you **MUST** set the following options: |
| 54 | +### `@launchdarkly/react-sdk` |
44 | 55 |
|
45 | | -- **`plugins: [td]`** - registers the testing plugin so it can inject overrides. |
46 | | -- **`sendEvents: false`** - keeps analytics events off in tests. |
47 | | -- **`streaming: false`** - (required for `js-client-sdk` and its derivativs, eg `react-sdk`), having streaming on will cause the `js-client-sdk` to automatically open a streaming connection. |
48 | | -- **`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. |
| 56 | +```ts |
| 57 | +import { createTestClient } from '@launchdarkly/client-testing-plugin/react-sdk'; |
| 58 | +import { createLDReactProviderWithClient } from '@launchdarkly/react-sdk'; |
49 | 59 |
|
50 | | -> Refer to the usage example above. |
| 60 | +const { client, testData } = createTestClient( |
| 61 | + { kind: 'user', key: 'tester' }, |
| 62 | + { 'show-banner': true, greeting: 'Welcome' }, |
| 63 | +); |
51 | 64 |
|
52 | | -## API |
| 65 | +await client.start({ bootstrap: {} }); |
| 66 | + |
| 67 | +const LDProvider = createLDReactProviderWithClient(client); |
| 68 | +render(<LDProvider><MyComponent /></LDProvider>); |
| 69 | + |
| 70 | +// Drive UI updates by mutating testData in `act(...)`. |
| 71 | +testData.setString('greeting', 'Updated'); |
| 72 | +``` |
| 73 | + |
| 74 | +A runnable example lives under [`example/sdks/react-sdk/`](./example/sdks/react-sdk/). |
53 | 75 |
|
54 | | -### `TestData` |
| 76 | +## Manual setup (advanced) |
| 77 | + |
| 78 | +If you need to wire `TestData` into an SDK the plugin does not yet provide a wrapper for, or you want full control over client options, register `TestData` as a plugin yourself: |
55 | 79 |
|
56 | 80 | ```ts |
57 | | -class TestData implements LDPlugin { |
58 | | - constructor(initialFlags?: { [key: string]: LDFlagValue }); |
| 81 | +import { createClient } from '@launchdarkly/js-client-sdk'; |
| 82 | +import { TestData } from '@launchdarkly/client-testing-plugin'; |
| 83 | + |
| 84 | +const td = new TestData({ 'new-ui': true }); |
59 | 85 |
|
60 | | - setBool(key: string, value: boolean): this; |
61 | | - setString(key: string, value: string): this; |
62 | | - setNumber(key: string, value: number): this; |
63 | | - setJson(key: string, value: object | unknown[]): this; |
| 86 | +const client = createClient( |
| 87 | + '<ldClientSideId>', |
| 88 | + { kind: 'user', key: 'tester' }, |
| 89 | + { |
| 90 | + plugins: [td], |
| 91 | + sendEvents: false, |
| 92 | + streaming: false, |
| 93 | + }, |
| 94 | +); |
64 | 95 |
|
65 | | - remove(key: string): this; |
66 | | - clear(): this; |
67 | | -} |
| 96 | +await client.start({ bootstrap: {} }); |
68 | 97 | ``` |
69 | 98 |
|
70 | | -- **`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. |
71 | | -- **`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. Every write applies the override, even when the value is unchanged -- mirroring a real connection that can re-deliver a flag and fire a `change` event without the value differing. |
72 | | -- **`remove(key)`** -- drop the override for a single key. If the SDK is connected, also calls `removeOverride`. |
73 | | -- **`clear()`** -- drop all overrides. Useful in `beforeEach` for shared `TestData` instances. |
| 99 | +The required SDK settings when wiring manually: |
| 100 | + |
| 101 | +- **`plugins: [td]`** -- registers the testing plugin so it can inject overrides. |
| 102 | +- **`sendEvents: false`** -- keeps analytics events off in tests. |
| 103 | +- **`streaming: false`** -- (required for `js-client-sdk` and its derivatives, e.g. `react-sdk`); leaving streaming on causes the SDK to open a streaming connection. |
| 104 | +- **`bootstrap: {}`** -- passed to `start()`; gives the SDK an empty initial flag set so initialization does not block on a network identify call. The plugin's overrides are applied immediately afterward. |
| 105 | + |
| 106 | +## About LaunchDarkly |
| 107 | + |
| 108 | +- LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can: |
| 109 | + - Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases. |
| 110 | + - Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?). |
| 111 | + - Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file. |
| 112 | + - Grant access to certain features based on user attributes, like payment plan (eg: users on the 'gold' plan get access to more features than users in the 'silver' plan). |
| 113 | + - Disable parts of your application to facilitate maintenance, without taking everything offline. |
| 114 | +- LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Read [our documentation](https://docs.launchdarkly.com/sdk) for a complete list. |
| 115 | +- Explore LaunchDarkly |
| 116 | + - [launchdarkly.com](https://www.launchdarkly.com/ 'LaunchDarkly Main Website') for more information |
| 117 | + - [docs.launchdarkly.com](https://docs.launchdarkly.com/ 'LaunchDarkly Documentation') for our documentation and SDK reference guides |
| 118 | + - [apidocs.launchdarkly.com](https://apidocs.launchdarkly.com/ 'LaunchDarkly API Documentation') for our API documentation |
| 119 | + - [blog.launchdarkly.com](https://blog.launchdarkly.com/ 'LaunchDarkly Blog Documentation') for the latest product updates |
| 120 | + |
| 121 | +[client-testing-plugin-ci-badge]: https://github.com/launchdarkly/js-core/actions/workflows/client-testing-plugin.yml/badge.svg |
| 122 | +[client-testing-plugin-ci]: https://github.com/launchdarkly/js-core/actions/workflows/client-testing-plugin.yml |
| 123 | +[client-testing-plugin-npm-badge]: https://img.shields.io/npm/v/@launchdarkly/client-testing-plugin.svg?style=flat-square |
| 124 | +[client-testing-plugin-npm-link]: https://www.npmjs.com/package/@launchdarkly/client-testing-plugin |
| 125 | +[client-testing-plugin-ghp-badge]: https://img.shields.io/static/v1?label=GitHub+Pages&message=API+reference&color=00add8 |
| 126 | +[client-testing-plugin-ghp-link]: https://launchdarkly.github.io/js-core/packages/tooling/client-testing-plugin/docs/ |
| 127 | +[client-testing-plugin-dm-badge]: https://img.shields.io/npm/dm/@launchdarkly/client-testing-plugin.svg?style=flat-square |
| 128 | +[client-testing-plugin-dt-badge]: https://img.shields.io/npm/dt/@launchdarkly/client-testing-plugin.svg?style=flat-square |
0 commit comments