jest-chrome

library0.8.0jsnpmunverified

jest-chrome provides a comprehensive mock of the Chrome Extension API, designed specifically for testing Chrome extensions with Jest. It aims for a complete and accurate representation of the Chrome API, with built-in TypeScript support derived directly from the `@types/chrome` package, ensuring type safety and intellisense. The package is actively maintained, with the current stable version being 0.8.0. Releases occur periodically to address Jest compatibility, improve API coverage, and fix build-related issues, though there isn't a strict time-based cadence. Its primary differentiator is the completeness of the mock and its strong adherence to the official Chrome API types, enabling robust testing of extension logic without needing a real browser environment. This allows for faster, more reliable unit and integration tests for Chrome extensions.

testing

npm install jest-chrome

github ↗package ↗

INSTALL

IMPORT

SIG · JEST-CHROME

jest-chrome

testingjavascriptv0.8.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

chrome

✓ import { chrome } from 'jest-chrome'

✗ import chrome from 'jest-chrome'

The `chrome` object is a named export, not a default export. Used for Intellisense and linting in test files.

global chrome assignment

✓ Object.assign(global, require('jest-chrome'))

✗ import { chrome } from 'jest-chrome'; Object.assign(global, { chrome });

This CommonJS pattern is recommended for Jest setup files (`setupFilesAfterEnv`) to make the mocked `chrome` object globally available to all tests.

types

✓ import type { Browser } from 'jest-chrome'

✗ import { Browser } from 'jest-chrome'

While types are automatically inferred with `jest-chrome`, explicit type imports for specific mocked browser features may be useful for stricter type checking, often utilizing `type` keyword for tree-shaking benefits.

This example demonstrates how to mock asynchronous Chrome API functions, specifically `chrome.runtime.sendMessage`, including handling callbacks and simulating `chrome.runtime.lastError` for robust error testing.

import { chrome } from 'jest-chrome'; describe('chrome.runtime.sendMessage', () => { test('should handle messages and callbacks', () => { const message = { greeting: 'hello?' }; const response = { greeting: 'here I am' }; const callbackSpy = jest.fn(); // Mock the sendMessage function to call the callback with a response chrome.runtime.sendMessage.mockImplementation( (msg, callback) => { expect(msg).toEqual(message); callback(response); }, ); // Call the function under test chrome.runtime.sendMessage(message, callbackSpy); // Assertions expect(chrome.runtime.sendMessage).toBeCalledWith( message, callbackSpy, ); expect(callbackSpy).toBeCalledWith(response); }); test('should handle lastError in callback', () => { const message = { greeting: 'error test' }; const callbackSpy = jest.fn(); chrome.runtime.sendMessage.mockImplementation( (msg, callback) => { // Simulate an error by setting lastError before calling the callback Object.defineProperty(chrome.runtime, 'lastError', { get: () => ({ message: 'Something went wrong' }), configurable: true, }); callback(undefined); // Clear lastError after the callback, as Chrome does delete chrome.runtime.lastError; }, ); chrome.runtime.sendMessage(message, callbackSpy); expect(callbackSpy).toBeCalledWith(undefined); // You might also check if your extension's error handling was triggered }); });

Debug

Known issues

breakingThe package moved to a new npm organization. The import path changed from `jest-chrome` to `@extend-chrome/jest-chrome`.

fix

Update all `import` and `require` statements in your project from `jest-chrome` to `@extend-chrome/jest-chrome`.

affects: >=0.6.0

breakingThe internal implementation for mock functions changed from `jest.Mock` to `jest.MockedFunction`. While this might not directly break runtime code, it can affect type definitions or custom test utilities relying on the old type.

fix

Review any custom type definitions or test helpers that interact directly with Jest's mock types and update them to use `jest.MockedFunction` if necessary.

affects: >=0.5.0

gotchaThe `chrome` object must be assigned to the global scope in a Jest setup file (`setupFilesAfterEnv`) for it to be available in your test files.

fix

Add a `jest.setup.js` file (or similar) to your Jest configuration, and within it, use `Object.assign(global, require('jest-chrome'))`.

affects: >=0.5.0

gotchaChrome API functions that use callbacks for asynchronous operations have no default mock implementation. You must explicitly `mockImplementation` for each function you call in your tests.

fix

Always provide a `mockImplementation` for asynchronous Chrome API functions (e.g., `chrome.runtime.sendMessage.mockImplementation(...)`) to define their behavior during testing.

affects: >=0.5.0

deprecatedVersion 0.5.2 was deprecated on NPM due to a broken build caused by stricter TypeScript plugin versions.

fix

Avoid using version 0.5.2. Upgrade to version 0.5.3 or later to ensure a stable build.

affects: 0.5.2

Errors

Common errors & fixes

ReferenceError: chrome is not defined

The mocked `chrome` object has not been made globally available to your tests.

fix

Ensure your `jest.config.js` includes `setupFilesAfterEnv: ['./jest.setup.js']` and `jest.setup.js` contains `Object.assign(global, require('jest-chrome'))`.

TypeError: (some chrome method).mockImplementation is not a function

The `chrome` object or its methods are not recognized as Jest mock functions.

fix

Verify that `jest-chrome` is correctly loaded in your setup file, and that you are trying to mock a valid Chrome API method that `jest-chrome` intercepts.

Error: expect(jest.fn()).toBeCalledWith(...). Call stack: ... Async callback was not invoked within the 5000ms timeout specified by jest.DEFAULT_TIMEOUT_INTERVAL.

An asynchronous Chrome API function mock did not call its callback, leading to a Jest timeout.

fix

Review your `mockImplementation` for asynchronous functions to ensure the callback argument is correctly invoked (e.g., `callback(response)` or `Promise.resolve(response)` if it's a promise-based API).

Upgrade

Version history

0.8.0latest on npm

Audit

Dependencies

jestrequiredRuntime peer dependency for Jest testing framework.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/extend-chrome/jest-chrome ↗

packagehttps://www.npmjs.com/package/jest-chrome ↗