Skip to main content

Jest Utils

Collection of helpers useful in Jest tests.

caution

Prior to v1.35.0 these utilities were exported as JU module of the main package export, now they are exposed via a dedicated secondary export.

Details

For example, to use snapshot() helper in a test prior to v1.35.0 you would do (and JU would be null when imported in non-development build, or outside the server-side environment):

import { JU } from '@dr.pogodin/react-utils';

test('Example', () => {
  JU!.snapshot(<div>Hello World</div>);
});

Starting with v1.35.0 you must do:

/** @jest-environment jsdom */

import { snapshot } from '@dr.pogodin/react-utils/jest';

test('Example', () => {
  snapshot(<div>Hello World</div>);
});

The change was done to avoid module resolution issues when using JSDom environment for Jest tests.

E2eSsrEnv​

Although it is not exported from this module for technical reasons, E2eSsrEnv class implements Jest environment for end-to-end testing of SSR and client-side execution of Webpack-built code with Jest, and thus should be considered as a very important part of Jest-testing utilities provided by the library.

Methods​

  • act() — An alias for the act() function from react (moved into react package since React v18.3).
  • getMockUuid() - Generates a mock UUID (formats the given seed into an UUID-formatted string).
  • mockAxios() — A helper which simplifies mocking out of axios (our selected HTTP(S) client library) in tests.
  • mockClientSide() - Tricks react-utils into thinking the test is running within the client-side (browser) environment.
  • mockTimer() - Advances mock timers, and mock date by the specified time step.
  • mount() - Mounts scene to the DOM, and returns the root scene element with .destroy() method attached.
  • snapshot() - Does does a snapshot test of the give ReactJS component, and also returns JSON representation of is render.
  • unmockClientSide() - Reverts the effect of previous mockClientSide() call.
Deprecated Methods

act()​

import { act } from '@dr.pogodin/react-utils/jest';

This method is just an alias for act() function from react (moved into react since v18.3).

getMockUuid()​

import { getMockUuid } from '@dr.pogodin/react-utils/jest';

function getMockUuid(seed = 0): string;

Generates a mock UUID by determenistically transforming the given seed into a UUID-formatted string.

Arguments

  • seed — number — Optional. Defaults 0.

Returns

  • string - Mock UUID.

mockAxios()​

import { mockAxios } from '@dr.pogodin/react-utils/jest';

function mockAxios(handlers: AxiosRequestHandler[]): Axios;

mockAxios() is a helper which simplifies mocking out of axios (our selected HTTP(S) client library) in tests. To use it, you want to create __mock__/axios.ts, or __mock__/axios/index.ts file in the root of the host codebase:

// Basic __mock__/axios.ts example.

import { type AxiosRequestHandlerT, mockAxios } from '@dr.pogodin/react-utils/jest';

const sampleHandler: AxiosRequestHandlerT = (config) {
  if (config.url === 'https://dr.pogodin.studio/docs/react-utils') {
    return { data: 'mock reponse' };
  }
};

export default mockAxios([
  sampleHandler,
]);

With such setup, every call to axios within Jest tests will be run through each of provided mock request handlers; if any handler returns an object, the corresponding axios call will be returned to that result (with any omitted fields of axios response set to reasonable default values). If all handlers return null or undefined results, the mock will fallback to the real network call, and it will print a warning to the console, with details of the corresponding request and response (which will help you to mock that out).

For further details refer to axios documentation for request config (the argument of mock request handlers), and response schema (the result of mock request handlers should be a partial of it).

mockClientSide()​

import { mockClientSide } from '@dr.pogodin/react-utils/jest';

function mockClientSide();

Tricks react-utils library into thinking the test is running within the client-side (browser) environment.

mockTimer()​

import { mockTimer } from '@dr.pogodin/react-utils/jest';

async function mockTimer(time: number): Promise<void>;

Advances mock timers, and mock date by the specified time step.

Arguments

  • time - number - The time step [ms].

Returns

  • Promise - Resolves once all async operations triggered by the mock time advance have completed.

mount()​

import { mount } from '@dr.pogodin/react-utils/jest';

function mount(scene: ReactNode): MountedSceneT;

Mounts given scene into DOM and returns the root scene element (DOM node) with .destroy() and .snapshot() methods attached. The former of these methods unmounts the scene from DOM; and the later snapshots the scene (i.e. is is an alias for expect(scene).toMatchSnapshot()).

Arguments

  • scene - React.ReactNode - The scene.

Returns

  • HTMLElement - The root DOM element of the mounted scene with .destroy() and .snapshot() methods attached.

render()​

Deprecated

Removed in v1.34.0. Migrate to render() provided by @testing-library/react.

shallowRender()​

Deprecated

Removed in v1.34.0. Starting with React v19 it is recommended to avoid shallow rendering in tests.

shallowSnapshot()​

Deprecated

Removed in v1.34.0. Starting with React v19 it is recommended to avoid shallow rendering in tests.

simulate()​

Deprecated

Removed in v1.34.0. Use instead @testing-library/user-event, or the lower-level fireEvent from @testing-library/dom.

snapshot()​

import { snapshot } from '@dr.pogodin/react-utils/jest';

// 1st overload (synchronous):
function snapshot(element: ReactElement): RenderResult;

// 2nd overload (asynchronous):
async function snapshot(
  element: ReactElement,
  options: SnapshotOptionsT,
): Promise<RenderResult>;

It does the snapshot test of given React component.

Example
/** @jest-environment jsdom */

import { snapshot } from '@dr.pogodin/react-utils/jest';

test('A snapshot test', () => {
  snapshot(<div>Example</div>);
});
Beware

  • It relies on render() function provided by @testing-library/react, thus it renders provided component into DOM (appends it to the current DOM content), and snapshots HTML representation of the generated DOM node.

  • It requires JSDom test environment, thus a Jest test relying on this method should start with the magic comment /** @jest-environment jsdom */, or it should provide a virtual DOM in an alternative way.

  • Prior to v1.34.0 this method relied on now deprecated react-test-renderer, and thus it was snapshotting and returning a JSON representation of the rendered component tree, without requiring or modifying the virtual DOM.

Arguments

  • component — ReactElement — React element to snapshot.
  • options — SnapshotOptionsT | undefined — Optional settings. If provided, the function will be considered asynchronous, otherwise synchronous.

Returns

SnapshotOptionsT​

type SnapshotOptionsT = {
  await?: Promise<void>;
};

Optional settings for snapshot() method.

  • await — Promise<void> | undefined — Optional. If provided, snapshot() will await for this promise prior to capturing the result of component render (it is awaited after the render is triggered).

unmockClientSide()​

import { unmockClientSide } from '@dr.pogodin/react-utils/jest';

function unmockClientSide();

Reverts the effect of previous mockClientSide() call.