> For the complete documentation index, see [llms.txt](/llms.txt).

# Jest API and options

You can use the `@metamask/snaps-jest` package for [end-to-end Snaps testing](/snaps/how-to/test-a-snap/). This reference describes the available [API methods](#api-methods), [Jest matchers](#jest-matchers), and [options](#options).

## API methods[​](#api-methods "Direct link to API methods")

### `installSnap`[​](#installsnap "Direct link to installsnap")

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

#### Parameters[​](#parameters "Direct link to 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[​](#returns "Direct link to Returns")

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

#### Example[​](#example "Direct link to Example")

```
import { installSnap } from '@metamask/snaps-jest'

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

```

### `request`[​](#request "Direct link to request")

Sends a JSON-RPC request to the Snap.

#### Parameters[​](#parameters-1 "Direct link to Parameters")

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

#### Returns[​](#returns-1 "Direct link to Returns")

A promise that resolves to the response from the [onRpcRequest](/snaps/reference/entry-points/#onrpcrequest) entry point, which can be checked using [Jest matchers](#jest-matchers).

#### Example[​](#example-1 "Direct link to 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`[​](#ontransaction "Direct link to ontransaction")

Sends a transaction to the Snap.

#### Parameters[​](#parameters-2 "Direct link to 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[​](#returns-2 "Direct link to Returns")

An object with the user interface that was shown by the Snap, in the [onTransaction](/snaps/reference/entry-points/#ontransaction) entry point.

#### Example[​](#example-2 "Direct link to 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`[​](#oncronjob "Direct link to oncronjob")

Runs a cron job in the Snap. The request is normally specified in the Snap manifest file under the [endowment:cronjob](/snaps/reference/permissions/#endowmentcronjob) permission, but this method allows you to run cron jobs that are not specified in the manifest as well.

#### Parameters[​](#parameters-3 "Direct link to Parameters")

A JSON-RPC request object.

#### Returns[​](#returns-3 "Direct link to Returns")

A promise that resolves to the response from the [onCronjob](/snaps/reference/entry-points/#oncronjob) entry point, which can be checked using [Jest matchers](#jest-matchers).

#### Example[​](#example-3 "Direct link to Example")

```
import { installSnap } from '@metamask/snaps-jest'

describe('MySnap', () => {
  it('should end foo cron jobs 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`[​](#onhomepage "Direct link to onhomepage")

Requests the home page of the Snap. It takes no arguments, and returns a promise that resolves to the response from the [onHomePage](/snaps/reference/entry-points/#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`[​](#getinterface "Direct link to getinterface")

If your Snap uses [snap_dialog](/snaps/reference/snaps-api/snap%5Fdialog/) 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](#request) method.

#### Returns[​](#returns-4 "Direct link to 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[​](#example-4 "Direct link to 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[​](#jest-matchers "Direct link to 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](/snaps/reference/snaps-api/snap%5Fdialog/)or a user interface rendered by the [transaction insights API](/snaps/reference/entry-points/#ontransaction).

## Options[​](#options "Direct link to Options")

You can pass the following options when [configuring @metamask/snaps-jest](/snaps/how-to/test-a-snap/#2-configure-metamasksnaps-jest). All options are optional.

### `server`[​](#server "Direct link to 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](#installsnap), for example, `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[​](#example-5 "Direct link to Example")

jest.config.js

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

```