Unit testing with Jest

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.

Migrating from users to contexts

The 2.0 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
COPY

Then, configure Jest:

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

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.

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

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:

it('should click correctly', () => {
  mockFlags({
    camelFlag: true,
    snake_flag: 'rabbit',
    'kebab-flag': true,
    'original-unchanged_flag': 0,
  })
  // ...act & assert
})
COPY

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:

describe('button', () => {
  beforeEach(() => {
    resetLDMocks()
  })
  // ...tests
})
COPY

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:

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: 'context-key-123abc' })
})
COPY

Full example

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

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: 'context-key-123abc' })
  })
})
COPY