Jest Utils
Collection of helpers useful in Jest tests.
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 intoreact
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.
- render() — Removed in v1.34.0. Migrate to render() provided by @testing-library/react.
- shallowRender() — Removed in v1.34.0. Starting with React v19 it is recommended to avoid shallow rendering in tests.
- shallowSnapshot() — Removed in v1.34.0. Starting with React v19 it is recommended to avoid shallow rendering in tests.
- simulate — Removed in v1.34.0. Use instead @testing-library/user-event, or the lower-level fireEvent from @testing-library/dom.
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. Defaults0
.
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()
Removed in v1.34.0. Migrate to render() provided by @testing-library/react.
shallowRender()
Removed in v1.34.0. Starting with React v19 it is recommended to avoid shallow rendering in tests.
shallowSnapshot()
Removed in v1.34.0. Starting with React v19 it is recommended to avoid shallow rendering in tests.
simulate()
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>);
});
-
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
- RenderResult — render result from @testing-library/react.
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.