Test Chrome extensions with Vitest. A complete mock of the Chrome API.
npm install vitest-chrome
---
vitest-chromeA complete mock of the Chrome API for Chrome extensions, for use
with Vitest.
TypeScript support is built in. Each function and event is based
on the@types/chrome
package.
``sh`
npm i vitest-chrome -D
Set chrome in the global scope during setup so that it isvite.config.js
mocked in imported modules. Add a setup file to :
`javascript
// vitest.config.js
export default defineConfig({
test: {
// Add this line to your Vitest config (if you don't have it yet)
setupFiles: './vitest.init.ts',
}
})
`
Use the setup file to assign the mocked chrome object to theglobal object:
`javascript
// vitest.init.js
import * as chrome from '../src/index'
// Add chrome object to global scope
Object.assign(global, chrome)
`
Import chrome from vitest-chrome for Intellisense and linting.chrome
This is the same object as in the global scope.
`javascript`
import { chrome } from 'vitest-chrome'
> All of the following code blocks come from
> tests/demo.test.ts.
Each mocked Event has all the normal methods (addListener,hasListener, hasListeners, and removeListener) plus twocallListeners
more: and clearListeners.
callListeners triggers a specific Event. Call callListeners
with the arguments you expect Chrome to pass to your event
listeners. Each event listener for that Event will be called with
those arguments.
clearListeners removes all listeners for a specific Event.
`javascript
test('chrome api events', () => {
const listenerSpy = vi.fn()
const sendResponseSpy = vi.fn()
chrome.runtime.onMessage.addListener(listenerSpy)
expect(listenerSpy).not.toBeCalled()
expect(chrome.runtime.onMessage.hasListeners()).toBe(true)
chrome.runtime.onMessage.callListeners(
{ greeting: 'hello' }, // message
{}, // MessageSender object
sendResponseSpy, // SendResponse function
)
expect(listenerSpy).toBeCalledWith(
{ greeting: 'hello' },
{},
sendResponseSpy,
)
expect(sendResponseSpy).not.toBeCalled()
})
`
Some Chrome API functions are synchronous. Use these like any
mocked function:
`javascript
test('chrome api functions', () => {
const manifest = {
name: 'my chrome extension',
manifest_version: 2,
version: '1.0.0',
}
chrome.runtime.getManifest.mockImplementation(() => manifest)
expect(chrome.runtime.getManifest()).toEqual(manifest)
expect(chrome.runtime.getManifest).toBeCalled()
})
`
Most Chrome API functions do something asynchronous. They use
callbacks to handle the result. The mock implementation should be
set to handle the callback.
> Mocked functions have no default mock implementation!
`javascript
test('chrome api functions with callback', () => {
const message = { greeting: 'hello?' }
const response = { greeting: 'here I am' }
const callbackSpy = vi.fn()
chrome.runtime.sendMessage.mockImplementation(
(message, callback) => {
callback(response)
},
)
chrome.runtime.sendMessage(message, callbackSpy)
expect(chrome.runtime.sendMessage).toBeCalledWith(
message,
callbackSpy,
)
expect(callbackSpy).toBeCalledWith(response)
})
`
When something goes wrong in a callback, Chrome sets
chrome.runtime.lastError to an object with a message property.lastError
If you need to test this, set and clear in the mock
implementation.
> Remember that lastError is always undefined outside of a
> callback!
lastError is an object with amessage
getter function
for the property. If message is not checked, ChromelastError
will log the error to the console. To emulate this, simply set to an object with a getter that wraps a mock, as seen
below:
`javascript
test('chrome api functions with lastError', () => {
const message = { greeting: 'hello?' }
const response = { greeting: 'here I am' }
// lastError setup
const lastErrorMessage = 'this is an error'
const lastErrorGetter = vi.fn(() => lastErrorMessage)
const lastError = {
get message() {
return lastErrorGetter()
},
}
// mock implementation
chrome.runtime.sendMessage.mockImplementation(
(message, callback) => {
chrome.runtime.lastError = lastError
callback(response)
// lastError is undefined outside of a callback
delete chrome.runtime.lastError
},
)
// callback implementation
const lastErrorSpy = vi.fn()
const callbackSpy = vi.fn(() => {
if (chrome.runtime.lastError) {
lastErrorSpy(chrome.runtime.lastError.message)
}
})
// send a message
chrome.runtime.sendMessage(message, callbackSpy)
expect(callbackSpy).toBeCalledWith(response)
expect(lastErrorGetter).toBeCalled()
expect(lastErrorSpy).toBeCalledWith(lastErrorMessage)
// lastError has been cleared
expect(chrome.runtime.lastError).toBeUndefined()
})
`
The chrome object is based on schemas from the Chromiumsinon-chrome
project, with thanks to for
compiling the schemas.
Special thanks to @jacksteamdev
the author of jest-chrome` (which this project is based on)