Unit testing with Jest

This guide explains how to unit test LaunchDarkly React applications with Jest. jest-launchdarkly-mock allows you to simulate, or “mock,” flag evaluations locally. This lets you verify testing behavior happens correctly, while also letting you use the React SDK in your React application.

Migrating from users to contexts

The 2.x version of jest-launchdarkly-mock only operates on contexts. When you migrate from version 1.x, replace getUser with getContext and remove all references to the alias function because it has been removed.

Getting started

First, install jest-launchdarkly-mock with a package manager:

$
yarn add -D jest-launchdarkly-mock

Then, configure Jest:

1
module.exports = {
2
  setupFiles: ['jest-launchdarkly-mock'],
3
}

Usage

The jest-launchdarkly-mock package contains three exports to help unit test LaunchDarkly in your app:

• mockFlags, to mock flags at the start of each test case. This only mocks flags returned by the useFlags hook.
• resetLDMocks, to reset.
• ldClientMock, to mock the ldClient in the React Web SDK.

To learn more, read the Readme.

1
import { mockFlags, resetLDMocks, ldClientMock } from 'jest-launchdarkly-mock'

Mocking flags

Use the mockFlags function to mock flags. This only mocks flags returned by the useFlags hook. Pass an LDFlagSet containing the flag keys and values you want to mock. You can use camelCase, snake_case, kebab-case, or unchanged flag keys when mocking flags.

Here’s how:

1
it('should click correctly', () => {
2
3
  mockFlags({
4
    camelFlag: true,
5
    snake_flag: 'rabbit',
6
    'kebab-flag': true,
7
    'original-unchanged_flag': 0,
8
  })
9
10
  // ...act & assert
11
})

Resetting mocks

In the setup step of your test suite, use resetLDMocks() to reset all mocks and ensure each test runs with a clean slate. This function resets all mocked flags and ldClientMock.

Here’s how:

1
describe('button', () => {
2
3
  beforeEach(() => {
4
    resetLDMocks()
5
  })
6
7
  // ...tests
8
})

Testing ldClient

You can use ldClientMock to write tests involving the ldClient. This is a Jest mock of the ldClient. All functions of ldClientMock are also Jest mocks.

For example, if you have a button that calls ldClient.identify on click, then you can write an assertion using ldClientMock.

Here’s how:

1
it('should identify on click', () => {
2
  // ...arrange
3
4
  // act
5
  const { getByTestId } = render(<Button />)
6
  fireEvent.click(getByTestId('test-button'))
7
8
  // assert: identify gets called
9
  expect(ldClientMock.identify).toBeCalledWith({ key: 'example-context-key' })
10
})

Full example

Putting it all together, the following is a complete example of the snippets above:

1
import React from 'react'
2
import { render, fireEvent } from '@testing-library/react'
3
import { mockFlags, ldClientMock, resetLDMocks } from 'jest-launchdarkly-mock'
4
5
describe('button', () => {
6
  beforeEach(() => {
7
    // resets flags and ldClientMock before each test
8
    resetLDMocks()
9
  })
10
11
  test('flag on', () => {
12
    // mocking a camelCased flag
13
    mockFlags({ devTestFlag: true })
14
15
    const { getByTestId } = render(<Button />)
16
17
    expect(getByTestId('test-button')).toBeTruthy()
18
  })
19
20
  test('identify', () => {
21
    // mocking a kebab-cased-flag
22
    mockFlags({ 'dev-test-flag': true })
23
24
    const { getByTestId } = render(<Button />)
25
    fireEvent.click(getByTestId('test-button'))
26
27
    // asserting ldClient.identify gets called
28
    expect(ldClientMock.identify).toBeCalledWith({ key: 'example-context-key' })
29
  })
30
})