Skip to main content

Jest API and options

You can use the @metamask/snaps-jest package for end-to-end Snaps testing. This reference describes the available API methods, Jest matchers, and options.

API methods

installSnap

Installs a Snap in the execution environment. We recommend using this function in each test to ensure that it starts with a clean slate.

Parameters

By default, if the built-in server is enabled, installSnap installs the Snap from the built-in server. Otherwise, you must specify a Snap ID to install.

Returns

An object with functions that can be used to interact with the Snap.

Example

import { installSnap } from "@metamask/snaps-jest"

describe("MySnap", () => {
it("should do something", async () => {
await installSnap(/* optional Snap ID */)
// ...
})
})

request

Sends a JSON-RPC request to the Snap.

Parameters

A JSON-RPC request object with an addition optional origin property.

Returns

A promise that resolves to the response from the onRpcRequest entry point, which can be checked using Jest matchers.

Example

import { installSnap } from "@metamask/snaps-jest"

describe("MySnap", () => {
it("should respond to foo with bar", async () => {
const { request } = await installSnap(/* Optional snap ID */)
const response = await request({
origin: "http://localhost:8080",
method: "foo",
params: [],
})

/* Check the response using Jest matchers. Since the response is a standard JSON-RPC response,
* you can use any standard Jest matchers to check it, including snapshot matchers. */
expect(response).toRespondWith("bar")
expect(response).not.toRespondWithError("baz")
expect(response).toMatchSnapshot()
})
})

onTransaction

Sends a transaction to the Snap.

Parameters

A transaction object with the following properties:

  • origin
  • chainId
  • from
  • to
  • value
  • data
  • gasLimit
  • maxFeePerGas
  • maxPriorityFeePerGas
  • nonce

All properties are optional. The addresses are randomly generated by default. Most values can be specified as a hex string or a decimal number.

Returns

An object with the user interface that was shown by the Snap, in the onTransaction entry point.

Example

import { installSnap } from "@metamask/snaps-jest"
import { panel, text } from "@metamask/snaps-sdk"

describe("MySnap", () => {
it("should return insights", async () => {
const { onTransaction } = await installSnap(/* Optional Snap ID */)
const response = await onTransaction({
value: "0x0",
data: "0x",
gasLimit: "0x5208",
maxFeePerGas: "0x5208",
maxPriorityFeePerGas: "0x5208",
nonce: "0x0",
})

expect(response).toRender(panel([text("Hello, world!")]))
})
})

onCronjob

Runs a cronjob in the Snap. The request is normally specified in the Snap manifest file under the endowment:cronjob permission, but this method allows you to run cronjobs that are not specified in the manifest as well.

Parameters

A JSON-RPC request object.

Returns

A promise that resolves to the response from the onCronjob entry point, which can be checked using Jest matchers.

Example

import { installSnap } from "@metamask/snaps-jest"

describe("MySnap", () => {
it("should end foo cronjobs with response bar", async () => {
const { onCronjob } = await installSnap(/* Optional snap ID */)
const response = await onCronjob({
method: "foo",
params: [],
})

// Check the response using Jest matchers.
expect(response).toRespondWith("bar")
expect(response).not.toRespondWithError("baz")
})
})

onHomePage

Requests the home page of the Snap. It takes no arguments, and returns a promise that resolves to the response from the onHomePage entry point.

import { installSnap } from "@metamask/snaps-jest"
import { panel, text } from "@metamask/snaps-sdk"

describe("MySnap", () => {
it("should render the home page", async () => {
const { onHomePage } = await installSnap(/* Optional snap ID */)
const response = await onHomePage()

expect(response).toRender(panel([text("Hello, world!")]))
})
})

getInterface

If your Snap uses snap_dialog to show user interfaces, you can use the request.getInterface method to interact with the user interfaces. This method is present on the return value of the request method.

Returns

This method waits for the user interface to be shown, and returns an object with functions that can be used to interact with the user interface.

Example

import { installSnap } from "@metamask/snaps-jest"
import { text } from "@metamask/snaps-sdk"
import { assert } from "@metamask/utils"

describe("MySnap", () => {
it("should render an alert with hello world", async () => {
const { request } = await installSnap(/* Optional Snap ID */)

// Note: You cannot resolve the promise yet!
const response = request({
method: "foo",
})

const ui = await response.getInterface()

// This is useful if you're using TypeScript, since it infers the type of the user interface.
assert(ui.type === "alert")
expect(ui).toRender(text("Hello, world!"))

// Select the OK button.
await ui.ok()

// Now you can resolve the promise.
const result = await response
expect(result).toRespondWith("bar")
})
})

Jest matchers

@metamask/snaps-jest includes the following Jest matchers that you can use to assert that a response from a Snap matches an expected value:

  • toRespondWith(expectedResponse) - Checks if a response matches an expected response. This matcher checks the result property of the response. If the response is an error, this matcher fails.
  • toRespondWithError(expectedError) - Checks if a response matches an expected error. This matcher checks the error property of the response. If the response is not an error, this matcher fails.
  • toSendNotification(notificationText) - Checks if a Snap sent a notification.
  • toRender(expectedInterface) - Checks if a Snap rendered an interface. This is useful for testing the user interface of a Snap, either for a snap_dialog or a user interface rendered by the transaction insights API.

Options

You can pass the following options when configuring @metamask/snaps-jest. All options are optional.

server

Options for the built-in HTTP server included with this package. This server serves the execution environment, simulator, and the Snap bundle during tests.

The server options are:

  • enabled - Enables or disables the built-in HTTP server. Set to false to use your own HTTP server, which you can specify when calling installSnap, e.g. installSnap("local:http://my-server"). The default is true.
  • port - The port to use for the built-in HTTP server. The default is a random available (unprivileged) port.
  • root - The path to the root directory to serve the Snap files from. This is useful if you want to serve the Snap files from a different directory than the one Jest is running from. The default is the current working directory.

Example

jest.config.js
module.exports = {
preset: "@metamask/snaps-jest",
testEnvironmentOptions: {
server: {
port: 8080,
root: "/path/to/snap/files",
},
},
}