Unit testing with Jest

This guide explains how to unit test LaunchDarkly React applications with Jest. jest-launchdarkly-mock allows you to mock flag evaluations locally to ensure intended testing behavior while still directly utilizing the React SDK in your React application.

Overview

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.

The jest-launchdarkly-mock package is only compatible with the React Web SDK.

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

    yarn add -D jest-launchdarkly-mock

Then, configure Jest:

jest.config.js

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

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.

button.test.js

    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:

button.test.js

    it('should click correctly', () => {

      mockFlags({
        camelFlag: true,
        snake_flag: 'rabbit',
        'kebab-flag': true,
        'original-unchanged_flag': 0,
      })

      // ...act & assert
    })

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:

button.test.js

    describe('button', () => {

      beforeEach(() => {
        resetLDMocks()
      })

      // ...tests
    })

Testing `ld

ClientYou can use ldClientMockto write tests involving theldClient. This is a Jest mock of the ldClient. All functions of ldClientMockare also Jest mocks.For example, if you have a button that callsldClient.identifyon click, then you can write an assertion usingldClientMock`.Here’s how:

button.test.js

    it('should identify on click', () => {
      // ...arrange

      // act
      const { getByTestId } = render(<Button />)
      fireEvent.click(getByTestId('test-button'))

      // assert: identify gets called
      expect(ldClientMock.identify).toBeCalledWith({ key: 'example-context-key' })
    })

Full example

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

button.test.js

    import React from 'react'
    import { render, fireEvent } from '@testing-library/react'
    import { mockFlags, ldClientMock, resetLDMocks } from 'jest-launchdarkly-mock'

    describe('button', () => {
      beforeEach(() => {
        // resets flags and ldClientMock before each test
        resetLDMocks()
      })

      test('flag on', () => {
        // mocking a camelCased flag
        mockFlags({ devTestFlag: true })

        const { getByTestId } = render(<Button />)

        expect(getByTestId('test-button')).toBeTruthy()
      })

      test('identify', () => {
        // mocking a kebab-cased-flag
        mockFlags({ 'dev-test-flag': true })

        const { getByTestId } = render(<Button />)
        fireEvent.click(getByTestId('test-button'))

        // asserting ldClient.identify gets called
        expect(ldClientMock.identify).toBeCalledWith({ key: 'example-context-key' })
      })
    })