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).
  • 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.

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 scene to the DOM and returns the root scene element (DOM node) with .destroy() method attached, which unmounts the scene from DOM.

Arguments

  • scene - React.ReactNode - The scene.

Returns

  • HTMLElement - The root DOM element of the mounted scene with .destroy() method 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 { mount } from '@dr.pogodin/react-utils/jest';

function snapshot(element: React.ReactElement): Node | null;

It does a snapshot test of the given ReactJS 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 — React.ReactElement — React element to snapshot.

Returns

  • Node — rendered DOM node.

unmockClientSide()​

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

function unmockClientSide();

Reverts the effect of previous mockClientSide() call.