vitest-chrome

library0.1.0jsnpmunverified

vitest-chrome is a testing utility designed to provide a comprehensive mock of the Chrome Extension API, enabling developers to test their Chrome extension logic within a Vitest environment without requiring a real browser. As of version 0.1.0, it offers a complete set of mocked functions and events, all type-checked and based on the official `@types/chrome` definitions. This allows for robust and reliable testing of Chrome API interactions, including event listeners, synchronous API calls, and asynchronous functions relying on callbacks or `chrome.runtime.lastError`. The library is primarily used as a development dependency and integrates directly with Vitest's global setup to expose the mocked `chrome` object, simplifying the testing workflow for extension development.

testing

npm install vitest-chrome

github ↗package ↗

INSTALL

IMPORT

SIG · VITEST-CHROME

vitest-chrome

testingjavascriptv0.1.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 'vitest-chrome'

✗ const chrome = require('vitest-chrome')

The primary named export, used for type-checking and direct access to the mocked Chrome API. This object must then be assigned to the global scope for your extension code to use it at runtime during tests.

global.chrome

✓ Object.assign(global, chrome)

✗ global.chrome = chrome

This pattern is essential for setting up the mocked `chrome` object in the global scope via Vitest's `setupFiles` (e.g., in `vitest.init.ts`), making it accessible to your extension's code during tests. The `Object.assign` method is preferred for robust assignment.

chrome as Namespace

✓ import * as chrome from 'vitest-chrome'

An alternative ESM import style that also works, providing the 'chrome' object as a module namespace object, though `import { chrome } from 'vitest-chrome'` is more common for a single named export.

Demonstrates mocking Chrome API events, adding listeners, programmatically triggering them with specific arguments using `callListeners`, and clearing them with `clearListeners`.

import { vi, test, expect } from 'vitest'; import { chrome } from 'vitest-chrome'; // vitest.init.ts (example setup file content) // Object.assign(global, chrome); test('chrome api events', () => { const listenerSpy = vi.fn(); const sendResponseSpy = vi.fn(); // Add a listener to a mocked Chrome API event chrome.runtime.onMessage.addListener(listenerSpy); expect(listenerSpy).not.toBeCalled(); expect(chrome.runtime.onMessage.hasListeners()).toBe(true); // Trigger the event listeners with specific arguments chrome.runtime.onMessage.callListeners( { greeting: 'hello' }, // message {}, // MessageSender object sendResponseSpy, // SendResponse function ); // Assert that the listener was called with the correct arguments expect(listenerSpy).toBeCalledWith( { greeting: 'hello' }, {}, sendResponseSpy, ); expect(sendResponseSpy).not.toBeCalled(); // Clean up listeners after the test chrome.runtime.onMessage.clearListeners(); expect(chrome.runtime.onMessage.hasListeners()).toBe(false); });

Debug

Known issues

gotchaMocked Chrome API functions do not have default implementations. You must explicitly mock their behavior using Vitest's `mockImplementation` for them to return expected values or handle callbacks.

fix

Use `.mockImplementation(() => { /* return value */ })` for synchronous functions and `.mockImplementation((args, callback) => callback(response))` for asynchronous functions with callbacks.

affects: >=0.1.0

breakingThe 'chrome' object must be explicitly assigned to the global scope (`global` or `window`) within a Vitest setup file for your extension code to access it. Without this, the global 'chrome' will be undefined, leading to runtime errors.

fix

Configure `setupFiles` in your `vitest.config.js` and add `import { chrome } from 'vitest-chrome'; Object.assign(global, chrome);` in the specified setup file (e.g., `vitest.init.ts`).

affects: >=0.1.0

gotchaThe `chrome.runtime.lastError` object is only defined and accessible within the callback function of an asynchronous Chrome API call. Attempting to read it outside this context will result in `undefined`.

fix

Ensure your tests that assert on `lastError` explicitly set it within the mock implementation of the callback-based function, and access it only inside the mocked callback provided to the API call.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'onMessage')

The global `chrome` object was not properly assigned or imported within the test environment, so your extension code cannot find it.

fix

Ensure your Vitest configuration includes a `setupFiles` entry, and that the setup file contains `import { chrome } from 'vitest-chrome'; Object.assign(global, chrome);`

TypeError: chrome.runtime.getManifest is not a function

A Chrome API function was called but no mock implementation was provided, leading to it being an undefined function.

fix

Add a mock implementation for the specific API function, e.g., `chrome.runtime.getManifest.mockImplementation(() => ({ /* mock manifest data */ }));`

TS2305: Module '"vitest-chrome"' has no exported member 'default'. Did you mean to use 'import * as chrome from ...' or 'import { chrome } from ...'?

Attempting to import `chrome` as a default export when it is exported as a named export.

fix

Change `import chrome from 'vitest-chrome'` to `import { chrome } from 'vitest-chrome'` (or `import * as chrome from 'vitest-chrome'`).

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/probil/vitest-chrome ↗

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