jsdom-testing-mocks
A set of tools for emulating browser behavior in jsdom environment
Mocks
matchMedia
Intersection Observer
Resize Observer
Web Animations API
Installation
npm i -D jsdom-testing-mocks
yarn add -D jsdom-testing-mocks
Setup
With react
To avoid having to wrap everything in act
calls, you can pass act
to configMocks
:
import { configMocks } from 'jsdom-testing-mocks';
import { act } from '...';
configMocks({ act });
It can be done in a setup file, or in a test file, before rendering the component.
With vitest
Some mocks require lifecycle hooks to be defined on the global object. To make it work with vitest, you need to enable globals in your config. If you don't want to do that you can pass it manually using configMocks
.
Also, if you're using fake timers, at the time of writing this, vitest doesn't enable faking performance.now
, requestAnimationFrame
and cancelAnimationFrame
by default, so you need to do it manually:
vi.useFakeTimers({
toFake: [
'setTimeout',
'clearTimeout',
'setInterval',
'clearInterval',
'setImmediate',
'clearImmediate',
'Date',
'performance',
'requestAnimationFrame',
'cancelAnimationFrame',
],
});
vitest defaults
Testing framework support
We aim to support all major testing frameworks that support jsdom. Internally, there are no dependencies on any of them, so it's likely that it will work out of the box. Currently tested and confirmed to work with jest, @swc/jest and vitest (with some setup). If you encounter any problems with other testing frameworks, please open an issue.
Mock viewport
Mocks matchMedia
, allows testing of component's behavior depending on the viewport description (supports all of the Media Features). mockViewport
must be called before rendering the component
Example, using React Testing Library
:
import { mockViewport } from 'jsdom-testing-mocks';
it('shows the right lines on desktop and mobile', () => {
const viewport = mockViewport({ width: '320px', height: '568px' });
render(<TestComponent />);
expect(
screen.getByText('Content visible only on small screens')
).toBeInTheDocument();
expect(
screen.queryByText('Content visible only on large screens')
).not.toBeInTheDocument();
act(() => {
viewport.set({ width: '1440px', height: '900px' });
});
expect(
screen.queryByText('Content visible only on small screens')
).not.toBeInTheDocument();
expect(
screen.getByText('Content visible only on large screens')
).toBeInTheDocument();
viewport.cleanup();
});
Also, you can mock the viewport for a group of tests, using mockViewportForTestGroup
:
import { mockViewportForTestGroup } from 'jsdom-testing-mocks'
describe('Desktop specific tests', () => {
mockViewportForTestGroup({ width: '1440px', height: '900px' })
test('this', () = {
})
test('that', () = {
})
})
Mock IntersectionObserver
Provides a way of triggering intersection observer events
Example, using React Testing Library
:
import { mockIntersectionObserver } from 'jsdom-testing-mocks';
const io = mockIntersectionObserver();
it('loads the image when the component is in the viewport', () => {
const { container } = render(<TestComponent />);
expect(screen.queryByAltText('alt text')).not.toBeInTheDocument();
act(() => {
io.enterNode(screen.getByTestId('container'));
});
expect(screen.getByAltText('alt text')).toBeInTheDocument();
});
API
mockIntersectionObserver
returns an object, that has several useful methods:
.enterNode(node, desc)
Triggers all IntersectionObservers observing the node
, with isIntersected
set to true
and intersectionRatio
set to 1
. Other IntersectionObserverEntry
params can be passed as desc
argument, you can override any parameter except isIntersected
.leaveNode(node, desc)
Triggers all IntersectionObservers observing the node
, with isIntersected
set to false
and intersectionRatio
set to 0
. Other IntersectionObserverEntry
params can be passed as desc
argument, you can override any parameter except isIntersected
.enterNodes(nodeDescriptions)
Triggers all IntersectionObservers observing the nodes in nodeDescriptions
with multiple nodes entering at once. Each IntersectionObserver callback will receive only the nodes it's observing:
io.enterNodes([
{ node: screen.getByText('First Node'), desc: { intersectionRatio: 0.5 } },
{ node: screen.getByText('Second Node') },
screen.getByText('Third Node'),
]);
.leaveNodes(nodeDescriptions)
Triggers all IntersectionObservers observing the nodes in nodeDescriptions
with multiple nodes leaving at once. Each IntersectionObserver callback will receive only the nodes it's observing.
.triggerNodes(nodeDescriptions)
Triggers all IntersectionObservers observing the nodes in nodeDescriptions
with multiple nodes at once with custom descriptions (isIntersected
is not enforced). Each IntersectionObserver callback will receive only the nodes it's observing
.enterAll(desc) and .leaveAll(desc)
Triggers all IntersectionObservers for each of the observed nodes
Mock ResizeObserver
Mocks ResizeObserver
class. Resize callbacks are triggered manually using resize
method returned by the mock. Elements' size must not be 0 (at least on one axis) for the element to appear in the list of callback entries (you can mock the size using mockElementSize
or mockElementBoundingClientRect
)
Example, using React Testing Library
:
import { mockResizeObserver } from 'jsdom-testing-mocks';
const DivWithSize = () => {
const [size, setSize] = useState({ width: 0, height: 0 });
const ref = useRef(null);
useEffect(() => {
const observer = new ResizeObserver((entries) => {
setSize({
width: entries[0].contentRect.width,
height: entries[0].contentRect.height,
});
});
observer.observe(ref.current);
return () => {
observer.disconnect();
};
}, []);
return (
<div data-testid="theDiv" ref={ref}>
{size.width} x {size.height}
</div>
);
};
const resizeObserver = mockResizeObserver();
it('prints the size of the div', () => {
render(<DivWithSize />);
const theDiv = screen.getByTestId('theDiv');
expect(screen.getByText('0 x 0')).toBeInTheDocument();
resizeObserver.mockElementSize(theDiv, {
contentBoxSize: { inlineSize: 300, blockSize: 200 },
});
act(() => {
resizeObserver.resize();
});
expect(screen.getByText('300 x 200')).toBeInTheDocument();
resizeObserver.mockElementSize(theDiv, {
contentBoxSize: { inlineSize: 200, blockSize: 500 },
});
act(() => {
resizeObserver.resize(theDiv);
});
expect(screen.getByText('200 x 500')).toBeInTheDocument();
});
Caveats
Triggering the callback on observe
Although the mock doesn't call the resize callback on its own, it keeps track of all the cases when it should be implicitly called (like when the element first begins being observed), and it auto-adds them to the list of elements when resize
is called. You can disable this in ResizeOptions
Mocking element's size
The mock uses the size provided by mockElementSize
if present and fallbacks to getBoundingClientRect
(that you can mock using mockElementBoundingClientRect
). The issue with getBoundingClientRect
however is that in the real world the value it returns takes CSS Transforms into account, while the values returned in the observer callback don't. It doesn't really matter because it is you who mocks sizes, but for consistency it is preferred that you use mockElementSize
API
mockResizeObserver
returns an object, that has several methods:
.resize(elements?: HTMLElement | HTMLElement[], options: ResizeOptions)
Triggers all resize observer callbacks for all observers that observe the passed elements. Some elements are implicitly resized by the Resize Observer itself, for example when they first attached using observe
. This mock doesn't call the callback by itself. Instead, it adds them to the list of entries
when the next resize
is called (it happens only once per observe
per element).
In this example the resize callback will be triggered with all observed elements from within TestedComponent
:
render(<TestedComponent />);
act(() => {
resizeObserver.resize();
});
ResizeOptions.ignoreImplicit (false
by default)
If true
, do not include imlicit elements in the resize callback entries array
.mockElementSize(element: HTMLElement, size: Size)
Mocks element
's size only for the ResizeObserver. size
accepts 2 properties: contentBoxSize
and borderBoxSize
they're both similar to what you see in the ResizeObserver's callback entry. At least one of them must be present (if the other isn't it is set to be equal to the one present), and the other entry properties are derived from these two (and window.devicePixelRatio
).
Example:
mockElementSize(myDiv, {
contentBoxSize: { inlineSize: 400, blockSize: 200 },
});
mockElementSize(myOtherDiv, {
borderBoxSize: { inlineSize: 200 },
});
.getObservers(element?: HTMLElement)
Returns all observers (observing the element
if passed)
.getObservedElements(observer?: ResizeObserver)
Returns all observed elements (of the observer
if passed)
Mock Web Animations API
Warning: experimental, bug reports, tests and feedback are greatly appreciated
Mocks WAAPI functionality using requestAnimationFrame
. With one important limitation — there are no style interpolations. Each frame applies the closest keyframe from list of passed keyframes or a generated "initial keyframe" if only one keyframe is passed (initial keyframe removes/restores all the properties set by the one keyframe passed). As the implementation is based on the official spec it should support the majority of cases, but the test suite is far from complete, so here be dragons
Example, using React Testing Library
:
import { mockAnimationsApi } from 'jsdom-testing-mocks';
const TestComponent = () => {
const [isShown, setIsShown] = useState(false);
return (
<div>
{/* AnimatePresence is a component that adds its children in the dom
and fades it in using WAAPI, with 2 keyframes: [{ opacity: 0 }, { opacity: 1 }],
also adding a div with the word "Done!" after the animation has finished
You can find implementation in examples
*/}
<AnimatePresence>{isShown && <div>Hehey!</div>}</AnimatePresence>
<button
onClick={() => {
setIsShown(true);
}}
>
Show
</button>
</div>
);
};
mockAnimationsApi();
it('adds an element into the dom and fades it in', async () => {
render(<TestComponent />);
expect(screen.queryByText('Hehey!')).not.toBeInTheDocument();
await userEvent.click(screen.getByText('Show'));
const element = screen.getByText('Hehey!');
const animation = document.getAnimations()[0];
await animation.ready;
expect(element).not.toBeVisible();
await waitFor(() => {
expect(element).toBeVisible();
});
await waitFor(() => {
expect(screen.getByText('Done!')).toBeInTheDocument();
});
});
Using with fake timers
It's perfectly usable with fake timers, except for the issue with promises. Also note that you would need to manually advance timers by the duration of the animation taking frame duration (which currently is set to 16ms in jest
/sinon.js
) into account. So if you, say, have an animation with a duration of 300ms
, you will need to advance your timers by the value that is at least the closest multiple of the frame duration, which in this case is 304ms
(19
frames * 16ms
). Otherwise the last frame may not fire and the animation won't finish.
Current issues