🎭 jest-globals

Mocks out global variables with Jest spies.

Usage

jest-globals sets up a collection of global mocks such as location and navigator and assigns them to global variables on globalThis. If a typeof window !== undefined then it will assign the same values to window as well.

Your source code can then still refer to global variables normally...

1// Source file: ./example.ts
2export function example() {
3  window.location.assign("/path");
4}

...and your test files can import and use their test versions, as long as jest-globals is imported before the code under test:

1// Test file: ./example.test.ts
2import { location } from "jest-globals";
3import { example } from "./example";
4
5describe("example", () => {
6  it("assigns /path to location", () => {
7    example();
8    expect(location.assign).toHaveBeenCalledWith("/path");
9  });
10});

See #Custom Usage below for more details.

Available Globals

For each global available, you can import it from jest-globals directly.

addEventListener

1import { addEventListener } from "jest-globals";
2
3expect(addEventListener).toHaveBeenCalledWith("load", expect.any(Function));

alert

1import { alert } from "jest-globals";
2
3expect(alert).toHaveBeenCalledWith(expect.any(Function));

blur

1import { blur } from "jest-globals";
2
3expect(blur).toHaveBeenCalledTimes(1);

close

1import { close } from "jest-globals";
2
3expect(close).toHaveBeenCalledTimes(1);

confirm

1import { confirm } from "jest-globals";
2
3expect(confirm).toHaveBeenCalledTimes(1);

dispatchEvent

1import { dispatchEvent } from "jest-globals";
2
3expect(dispatchEvent).toHaveBeenCalledTimes(1);

focus

1import { focus } from "jest-globals";
2
3expect(focus).toHaveBeenCalledTimes(1);

getSelection

Use createMockSelection to create a valid Selection with stub data for any field not explicitly provided.

1import { createMockSelection, getSelection } from "jest-globals";
2
3getSelection.mockReturnValue(
4  createMockSelection({
5    focusOffset: 2,
6  })
7);

localStorage

localStorage is assigned an instance of a MockStorage class of assigned items under an items Map.

1import { localStorage } from "jest-globals";
2
3localStorage.setItem("powerLevel", "9001");
4
5expect(localStorage.setItem).toHaveBeenCalledWith("powerLevel", "9001");
6expect(localStorage.items.getItem("powerLevel")).toEqual("9001");

MockStorage's constructor includes a beforeEach(() => this.items.clear()).

location

1import { location } from "jest-globals";
2
3expect(location.assign).toHaveBeenCalledWith("/path");

matchMedia

1import { createMockMediaQueryList, matchMedia } from "jest-globals";
2
3matchMedia.mockReturnValue(
4  createMockMediaQueryList({
5    //
6  })
7);

moveBy

1import { moveBy } from "jest-globals";
2
3expect(moveBy).toHaveBeenCalledWith(12, 34);

navigator

1import { navigator } from "jest-globals";
2
3navigator.mockUserAgent.mockReturnValue("Mozilla/123");
4navigator.clipboard.readText.mockResolvedValue("It's over 9,000!");
5expect(navigator.serviceWorker.register).toHaveBeenCalled();

open

1import { open } from "jest-globals";
2
3expect(open).toHaveBeenCalledWith("https://hi.joshuakgoldberg.com");

performance

1import { performance } from "jest-globals";
2
3performance.now.mockReturnValue(9001);

postMessage

1import { postMessage } from "jest-globals";
2
3expect(postMessage).toHaveBeenCalledWith("Is anybody out there?", "*");

print

1import { print } from "jest-globals";
2
3expect(print).toHaveBeenCalledTimes(1);

prompt

1import { prompt } from "jest-globals";
2
3expect(prompt).toHaveBeenCalledWith("Hello my baby");

removeEventListener

1import { removeEventListener } from "jest-globals";
2
3expect(removeEventListener).toHaveBeenCalledWith(expect.any(Function));

requestAnimationFrame

1import { requestAnimationFrame } from "jest-globals";
2
3expect(requestAnimationFrame).toHaveBeenCalledWith(expect.any(Function));

requestIdleCallback

1import { requestIdleCallback } from "jest-globals";
2
3expect(requestIdleCallback).toHaveBeenCalledWith(expect.any(Function));

resizeBy

1import { resizeBy } from "jest-globals";
2
3expect(resizeBy).toHaveBeenCalledWith(12, 34);

resizeTo

1import { resizeTo } from "jest-globals";
2
3expect(resizeTo).toHaveBeenCalledWith(123, 456);

scrollBy

1import { scrollBy } from "jest-globals";
2
3expect(scrollBy).toHaveBeenCalledWith(12, 34);

scrollTo

1import { scrollTo } from "jest-globals";
2
3expect(scrollTo).toHaveBeenCalledWith(123, 456);

sessionStorage

sessionStorage is assigned an instance of a MockStorage class that keeps track of assigned items under an items member of type Map<string, string>:

1import { sessionStorage } from "jest-globals";
2
3sessionStorage.setItem("powerLevel", "9001");
4
5expect(sessionStorage.setItem).toHaveBeenCalledWith("powerLevel", "9001");
6expect(sessionStorage.items.getItem("powerLevel")).toEqual("9001");

MockStorage's constructor includes a beforeEach(() => this.items.clear()).

setImmediate

1import { setImmediate } from "jest-globals";
2
3expect(setImmediate).toHaveBeenCalledWith(expect.any(Function));

stop

1import { stop } from "jest-globals";
2
3expect(stop).toHaveBeenCalledTimes(1);

top

window.top is by default a reference to an identical mock window object, except its .top references itself.

1import { top } from "jest-globals";
2
3expect(top.postMessage).toHaveBeenCalledWith("I'll be back one day", "*");

Strongly Typed Usage

jest-globals is written in TypeScript and generally type safe. Imported objects from jest-globals are typed as having jest.Mocks for their functions with parameters and return types corresponding to their original mocks.

Global mocks that return complex original objects therefore require mockReturnValue and co. to be provided with objects that match up to the original type:

1import { getSelection } from "jest-globals";
2
3getSelection.mockReturnValue({
4  focusOffset: 2,
5});
6// Error: Argument of type '{ focusOffset: number; }' is not assignable to parameter of type 'Selection'.
7//   Type '{ focusOffset: number; }' is missing the following properties from type 'Selection': anchorNode, anchorOffset, focusNode, focusOffset, and 16 more.

Each of these APIs has a corresponding createMock* function exported by jest-globals that takes in a Partial of the returned type and fills in any missing fields:

1import { createMockSelection, getSelection } from "jest-globals";
2
3getSelection.mockReturnValue(
4  createMockSelection({
5    focusOffset: 2,
6  })
7);

What's Not Provided

The following global members are complex enough that they warrant their own dedicated packages:

• document: jest-environment-jsdom
• fetch: fetch-mock / fetch-mock-jest
• getComputedStyle: similar to document
• XMLHTTPRequest: use fetch instead 😄

Custom Usage

Auto-Sorted Involvement

If you'd like jest-globals to run after library code, it may be inconvenient to also have a linter plugin thatt auto-sorts your imports.

1// example.test.js
2import "jest-globals"; // runs first 😔
3import userEvent from "@testing-library/user-event";

If your configuration puts imports under a prefix such as ~/ last, you can create a file whose sole purpose is to import jest-globals:

1// tests/globals
2export * from "jest-globals";

1// example.test.js
2import userEvent from "@testing-library/user-event";
3import "~/tests/globals"; // runs last 😌

Another (less type safe) workaround is to use Jest's moduleNameMapper to allow importing under a name like zzzest-globals, pushing it alphabetically below other absolute imports:

1{
2  "moduleNameMapper": {
3    "^zzzest-globals$": "jest-globals"
4  }
5}

1// example.test.js
2import userEvent from "@testing-library/user-event";
3import "zzzest-globals"; // runs last 😌

Permanent Involvement

If you'd like jest-globals to always be run before all your files, you can include it in your setupFilesAfterEnv:

1// ./jest.setup.js
2require("jest-globals");

Development

Requires:

• Node.js >14
• Yarn

After forking the repo from GitHub:

git clone https://github.com/<your-name-here>/jest-globals
cd jest-globals
yarn

Contribution Guidelines

We'd love to have you contribute! Check the issue tracker for issues labeled accepting prs to find bug fixes and feature requests the community can work on. If this is your first time working with this code, the good first issue label indicates good introductory issues.

Please note that this project is released with a Contributor Covenant. By participating in this project you agree to abide by its terms. See CODE_OF_CONDUCT.md.