@shopify/jest-dom-mocks
[![Build Status](https://travis-ci.org/Shopify/quilt.svg?branch=master)](https://travis-ci.org/Shopify/quilt) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md) [![npm version](https://badge.fury.io/js/%40shopify%2Fjest-dom-
Last updated 17 days ago by shopify-dep .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @shopify/jest-dom-mocks 
SYNC missed versions from official npm registry.

@shopify/jest-dom-mocks

Build Status License: MIT npm version

Jest mocking utilities for working with the DOM.

Installation

$ yarn add @shopify/jest-dom-mocks

Setup

This package provides two methods that should be included in the jest setup files:

  • ensureMocksReset
  • installMockStorage

ensureMocksReset

Should be called in the beforeEach method of the jest each-test setup file. For example:

import {ensureMocksReset} from '@shopify/jest-dom-mocks';

beforeEach(() => {
  ensureMocksReset();
});

this will ensure that appropriate error messages are shown if a DOM object is mocked without beign restored for the next test.

installMockStorage

Should be called in the jest setup file. For example:

import {installMockStorage} from '@shopify/jest-dom-mocks';

installMockStorage();

this will install the localStorage and sessionStorage mocks onto the global window object.

Example Usage

In this example, we are testing a NumberTransitioner component using Jest and Enzyme. Note that parts of this file have been omitted in order to focus in on the relevant parts of the example.

import {clock, animationFrame} from '@shopify/jest-dom-mocks';

it('transitions to the next number after being updated', () => {
  clock.mock();
  animationFrame.mock();

  const duration = 1000;
  const rendered = mount(
    <NumberTransitioner duration={duration}>{100}</NumberTransitioner>,
  );
  rendered.setProps({children: 200});

  clock.tick(duration / 4);
  animationFrame.runFrame();
  expect(rendered.text()).toBe('125');

  clock.tick(duration / 2);
  animationFrame.runFrame();
  expect(rendered.text()).toBe('175');

  clock.restore();
  animationFrame.restore();
});

API Reference

The mocks provided can be divided into 3 primary categories:

  • standard mocks
  • fetch mock
  • storage mocks

Standard Mocks

The following standard mocks are available:

  • animationFrame
  • requestIdleCallback
  • clock
  • location
  • matchMedia
  • timer
  • promise
  • intersectionObserver
  • dimension
  • connection

Each of the standard mocks can be installed, for a given test, using standardMock.mock(), and must be restored before the end of the test using standardMock.restore().

For example:

import {location} from '@shopify/jest-dom-mocks';

beforeEach(() => {
  location.mock();
});

afterEach(() => {
  location.restore();
});

it('does a thing', () => {
  // run test code here
});

Or, if you just need to mock something for a single test:

import {location} from '@shopify/jest-dom-mocks';

it('does a thing', () => {
  location.mock();

  // run test code here

  location.restore();
});

Some of the standard mocks include additional features:

AnimationFrame.runFrame(): void

Executes all queued animation callbacks.

RequestIdleCallback.mockAsUnsupported(): void

Removes window.requestIdleCallback and window.cancelIdleCallback, which can be useful for testing features that should work with and without idle callbacks available.

RequestIdleCallback.runIdleCallbacks(timeRemaining?: number, didTimeout?: boolean): void

Runs all currently-scheduled idle callbacks. If provided, timeRemaining/ didTimeout will be used to construct the argument for these callbacks. Once called, all callbacks are removed from the queue.

RequestIdleCallback.cancelIdleCallbacks(): void

Cancels all currently-scheduled idle callbacks.

RequestIdleCallback.cancelIdleCallback(callback: any): void

Cancels the idle callback specified by the passed argument. This value should be the one returned from a call to window.requestIdleCallback.

Clock.mock(now: number | Date): void

In addition to the usual .mock() functionality (with no arguments), the Clock object can be mocked by passing in a number or Date object to use as the current system time.

Clock.tick(time: number): void

Ticks the mocked Clock ahead by time milliseconds.

Clock.setTime(time: number): void

Sets the system time to the given time.

MatchMedia.mock(media?: MediaMatching): void

In addition to the usual .mock() functionality (with no arguments), the MatchMedia object can be mocked by passing in a MediaMatching function to use as the implementation.

The MediaMatching function has the following interface:

interface MediaMatching {
  (mediaQuery: string): Partial<MediaQueryList>;
}

it takes a mediaQuery string as input and returns a partial MediaQueryList to use as the result of window.matchMedia(mediaQuery). The partial result will be merged with the default values:

{
  media: '',
  addListener: noop,
  removeListener: noop,
  matches: false
}

MatchMedia.setMedia(media?: MediaMatching): void

Sets the implementation function for the mocked MatchMedia object. see above (MatchMedia.mock(media?: MediaMatching): void) for details on how MediaMatching works.

You can also call setMedia with no arguments to restore the default implementation.

Timer.runAllTimers(): void

Runs all system timers to completion.

Timer.runTimersToTime(time: number): void

Runs all system timers to the given time.

Promise.runPending(): void

Runs all promise resolvers that have been queued.

IntersectionObserver.observers

Returns an array of records representing elements currently being observed with an IntersectionObserver. Each record contains a target (the element being observed), callback (the function used when constructing the observer), options (optional object used when constructing the observer), and a source (the fake IntersectionObserver instance that was used to observe).

IntersectionObserver.simulate(entry: Partial<IntersectionObserverEntry> | Partial<IntersectionObserverEntry>[]): void

Simulates a call on all matching observers. If you pass a target on the passed entry/ entries, only observers with a matching target element will be triggered. Otherwise, all observers will be triggered. If you do not provide a full IntersectionObserverEntry in any case, the missing fields will be filled out with sensible defaults.

Fetch Mock

We use a version of fetch-mock that is augmented to ensure that it is properly unmocked after each test run. See the API of fetch-mock for more details.

Storage mock

The storage mocks are a bit different than the other mocks, because they serve primarily as a polyfill for the localStorage and sessionStorage APIs. The following standard API methods are implemented:

  • getItem
  • setItem
  • removeItrem
  • clear

Each of these are wrapped in a jest spy, which is automatically restored at the end of the test run.

Dimension mocks

The dimension mocks allow mocking the following DOM properties:

  • scrollWidth
  • scrollHeight
  • offsetWidth
  • offsetHeight

Pass the dimension you want to mock and the value you want returned for all calls when calling mock:

import {dimension} from '@shopify/jest-dom-mocks';

beforeEach(() => {
  dimension.mock({
    scrollWidth: 100,
    offsetHeight: 200,
  });
});

afterEach(() => dimension.restore());

You can also pass in a function as a mock that returns a number. The element is passed as the only argument to the function:

beforeEach(() => {
  dimension.mock({
    scrollWidth(element: HTMLElement) {
      return element.id === 'test-id' ? 200 : 0;
    },
  });
});

afterEach(() => dimension.restore());

describe('DOM tests', () => {
  it('returns the element width', () => {
    function Component() {
      return <div id="some-id" />;
    }
    const element = mount(<Component />);
    const elementWidth =
      element.domNode == null ? undefined : element.domNode.scrollWidth;

    expect(elementWidth).toBe(200);
  });
});

Current Tags

  • 2.8.7                                ...           latest (17 days ago)

40 Versions

  • 2.8.7                                ...           17 days ago
  • 2.8.6                                ...           23 days ago
  • 2.8.5                                ...           a month ago
  • 2.8.4                                ...           2 months ago
  • 2.8.3                                ...           2 months ago
  • 2.8.2                                ...           2 months ago
  • 2.8.1                                ...           2 months ago
  • 2.8.0                                ...           2 months ago
  • 2.7.7                                ...           3 months ago
  • 2.7.6                                ...           3 months ago
  • 2.7.5                                ...           3 months ago
  • 2.7.4                                ...           3 months ago
  • 2.7.3                                ...           3 months ago
  • 2.7.2                                ...           4 months ago
  • 2.7.1                                ...           5 months ago
  • 2.7.0                                ...           5 months ago
  • 2.6.1                                ...           7 months ago
  • 2.6.0                                ...           7 months ago
  • 2.5.6                                ...           7 months ago
  • 2.5.5                                ...           7 months ago
  • 2.5.4                                ...           7 months ago
  • 2.5.3                                ...           7 months ago
  • 2.5.2                                ...           8 months ago
  • 2.5.1                                ...           8 months ago
  • 2.5.0                                ...           8 months ago
  • 2.4.0                                ...           8 months ago
  • 2.3.1                                ...           9 months ago
  • 2.3.0                                ...           9 months ago
  • 2.2.1                                ...           9 months ago
  • 2.2.0                                ...           a year ago
  • 2.1.3                                ...           a year ago
  • 2.1.1                                ...           a year ago
  • 2.0.9                                ...           a year ago
  • 2.0.8                                ...           a year ago
  • 2.0.7                                ...           a year ago
  • 2.0.6                                ...           2 years ago
  • 2.0.5                                ...           2 years ago
  • 2.0.4                                ...           2 years ago
  • 2.0.3                                ...           2 years ago
  • 1.0.1                                ...           2 years ago
Downloads
Today 0
This Week 0
This Month 83
Last Day 0
Last Week 43
Last Month 766
Dependencies (9)
Dev Dependencies (0)
None

Copyright 2014 - 2016 © taobao.org |