@metamask/snaps-jest 0.35.1-flask.1

package/dist/types/internals/structs.d.ts

@@ -0,0 +1,164 @@
+export declare const TransactionOptionsStruct: import("superstruct").Struct<{
+    data: `0x${string}`;
+    from: `0x${string}`;
+    origin: string;
+    value: `0x${string}`;
+    chainId: string;
+    nonce: `0x${string}`;
+    maxPriorityFeePerGas: `0x${string}`;
+    maxFeePerGas: `0x${string}`;
+    to: `0x${string}`;
+    gasLimit: `0x${string}`;
+}, {
+    /**
+     * The CAIP-2 chain ID to send the transaction on. Defaults to `eip155:1`.
+     */
+    chainId: import("superstruct").Struct<string, null>;
+    /**
+     * The origin to send the transaction from. Defaults to `metamask.io`.
+     */
+    origin: import("superstruct").Struct<string, null>;
+    /**
+     * The address to send the transaction from. Defaults to a randomly generated
+     * address.
+     */
+    from: import("superstruct").Struct<`0x${string}`, null>;
+    /**
+     * The address to send the transaction to. Defaults to a randomly generated
+     * address.
+     */
+    to: import("superstruct").Struct<`0x${string}`, null>;
+    /**
+     * The value to send with the transaction. The value may be specified as a
+     * `number`, `bigint`, `string`, or `Uint8Array`. Defaults to `0`.
+     */
+    value: import("superstruct").Struct<`0x${string}`, null>;
+    /**
+     * The gas limit to use for the transaction. The gas limit may be specified
+     * as a `number`, `bigint`, `string`, or `Uint8Array`. Defaults to `21_000`.
+     */
+    gasLimit: import("superstruct").Struct<`0x${string}`, null>;
+    /**
+     * The max fee per gas (in Wei) to use for the transaction. The max fee per
+     * gas may be specified as a `number`, `bigint`, `string`, or `Uint8Array`.
+     * Defaults to `1`.
+     */
+    maxFeePerGas: import("superstruct").Struct<`0x${string}`, null>;
+    /**
+     * The max priority fee per gas (in Wei) to use for the transaction. The max
+     * priority fee per gas may be specified as a `number`, `bigint`, `string`,
+     * or `Uint8Array`. Defaults to `1`.
+     */
+    maxPriorityFeePerGas: import("superstruct").Struct<`0x${string}`, null>;
+    /**
+     * The nonce to use for the transaction. The nonce may be specified as a
+     * `number`, `bigint`, `string`, or `Uint8Array`. Defaults to `0`.
+     */
+    nonce: import("superstruct").Struct<`0x${string}`, null>;
+    /**
+     * The data to send with the transaction. The data may be specified as a
+     * `number`, `bigint`, `string`, or `Uint8Array`. Defaults to `0x`.
+     */
+    data: import("superstruct").Struct<`0x${string}`, null>;
+}>;
+export declare const SnapOptionsStruct: import("superstruct").Struct<{
+    timeout?: number | undefined;
+}, {
+    /**
+     * The timeout in milliseconds to use for requests to the snap. Defaults to
+     * `1000`.
+     */
+    timeout: import("superstruct").Struct<number | undefined, null>;
+}>;
+export declare const InterfaceStruct: import("superstruct").Struct<{
+    content?: import("@metamask/snaps-ui").Panel | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Copyable;
+    } | {
+        type: import("@metamask/snaps-ui").NodeType.Divider;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Heading;
+    } | {
+        type: import("@metamask/snaps-ui").NodeType.Spinner;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Text;
+    } | undefined;
+}, {
+    content: import("superstruct").Struct<import("@metamask/snaps-ui").Panel | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Copyable;
+    } | {
+        type: import("@metamask/snaps-ui").NodeType.Divider;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Heading;
+    } | {
+        type: import("@metamask/snaps-ui").NodeType.Spinner;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Text;
+    } | undefined, null>;
+}>;
+export declare const SnapResponseStruct: import("superstruct").Struct<{
+    response: {
+        result: import("@metamask/utils").Json;
+    } | {
+        error: import("@metamask/utils").Json;
+    };
+    id: string;
+    notifications: {
+        message: string;
+        type: "native" | "inApp";
+        id: string;
+    }[];
+    content?: import("@metamask/snaps-ui").Panel | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Copyable;
+    } | {
+        type: import("@metamask/snaps-ui").NodeType.Divider;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Heading;
+    } | {
+        type: import("@metamask/snaps-ui").NodeType.Spinner;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Text;
+    } | undefined;
+}, {
+    id: import("superstruct").Struct<string, null>;
+    response: import("superstruct").Struct<{
+        result: import("@metamask/utils").Json;
+    } | {
+        error: import("@metamask/utils").Json;
+    }, null>;
+    notifications: import("superstruct").Struct<{
+        message: string;
+        type: "native" | "inApp";
+        id: string;
+    }[], import("superstruct").Struct<{
+        message: string;
+        type: "native" | "inApp";
+        id: string;
+    }, {
+        id: import("superstruct").Struct<string, null>;
+        message: import("superstruct").Struct<string, null>;
+        type: import("superstruct").Struct<"native" | "inApp", null>;
+    }>>;
+    content: import("superstruct").Struct<import("@metamask/snaps-ui").Panel | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Copyable;
+    } | {
+        type: import("@metamask/snaps-ui").NodeType.Divider;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Heading;
+    } | {
+        type: import("@metamask/snaps-ui").NodeType.Spinner;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-ui").NodeType.Text;
+    } | undefined, null>;
+}>;

package/dist/types/internals/types.d.ts

@@ -0,0 +1,19 @@
+import { NotificationType } from '@metamask/rpc-methods';
+import { ApplicationState, Dispatch } from '@metamask/snaps-simulator';
+import { EnumToUnion } from '@metamask/snaps-utils';
+declare global {
+    interface Window {
+        __SIMULATOR_API__: {
+            dispatch: Dispatch;
+            subscribe: (listener: () => void) => () => void;
+            getState: () => ApplicationState;
+            getRequestId: () => string;
+            getNotifications: (requestId: string) => {
+                id: string;
+                message: string;
+                type: EnumToUnion<NotificationType>;
+            }[];
+        };
+    }
+}
+export {};

package/dist/types/internals/wait-for.d.ts

@@ -0,0 +1,38 @@
+import { HandlerType } from '@metamask/snaps-utils';
+import { Page } from 'puppeteer';
+export declare type WaitForOptions = {
+    /**
+     * The timeout in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * The error message to throw if the condition is not met.
+     */
+    message?: string;
+};
+/**
+ * Wait for a condition to be true. This is a wrapper around
+ * `pptr-testing-library`'s `waitFor` function, with the addition of a custom
+ * error message.
+ *
+ * @param fn - The condition to wait for.
+ * @param options - The options.
+ * @param options.timeout - The timeout in milliseconds.
+ * @param options.message - The error message to throw if the condition is not
+ * met.
+ * @returns A promise that resolves when the condition is met. The promise
+ * resolves to the return value of the condition function.
+ */
+export declare function waitFor<Result>(fn: () => Promise<Result>, { timeout, message }?: WaitForOptions): Promise<Result & ({} | null)>;
+/**
+ * Wait for a JSON-RPC response.
+ *
+ * @param page - The page to wait for the response on.
+ * @param type - The type of response to wait for.
+ * @returns The JSON-RPC response.
+ */
+export declare function waitForResponse(page: Page, type: HandlerType.OnTransaction | HandlerType.OnRpcRequest | HandlerType.OnCronjob): Promise<{
+    result: import("@metamask/utils").Json;
+} | {
+    error: import("@metamask/utils").Json;
+}>;

package/dist/types/matchers.d.ts

@@ -0,0 +1,29 @@
+import { NotificationType } from '@metamask/rpc-methods';
+import { Component } from '@metamask/snaps-ui';
+import { EnumToUnion } from '@metamask/snaps-utils';
+import { Json } from '@metamask/utils';
+import type { MatcherFunction } from 'expect';
+/**
+ * Check if a JSON-RPC response matches the expected value. This matcher is
+ * intended to be used with the `expect` global.
+ *
+ * @param actual - The actual response.
+ * @param expected - The expected response.
+ * @returns The status and message.
+ */
+export declare const toRespondWith: MatcherFunction<[expected: Json]>;
+export declare const toRespondWithError: MatcherFunction<[expected: Json]>;
+/**
+ * Check if the snap sent a notification with the expected message. This matcher
+ * is intended to be used with the `expect` global.
+ *
+ * @param actual - The actual response.
+ * @param expected - The expected notification message.
+ * @param type - The expected notification type.
+ * @returns The status and message.
+ */
+export declare const toSendNotification: MatcherFunction<[
+    expected: string,
+    type?: EnumToUnion<NotificationType> | undefined
+]>;
+export declare const toRender: MatcherFunction<[expected: Component]>;

package/dist/types/options.d.ts

@@ -0,0 +1,92 @@
+import { Infer } from 'superstruct';
+declare const SnapsEnvironmentOptionsStruct: import("superstruct").Struct<{
+    keepAlive: boolean;
+    server: {
+        port: number;
+        root: string;
+        enabled: boolean;
+    };
+    browser: {
+        headless: boolean;
+    };
+    executionEnvironmentUrl?: string | undefined;
+    simulatorUrl?: string | undefined;
+}, {
+    executionEnvironmentUrl: import("superstruct").Struct<string | undefined, null>;
+    simulatorUrl: import("superstruct").Struct<string | undefined, null>;
+    keepAlive: import("superstruct").Struct<boolean, null>;
+    server: import("superstruct").Struct<{
+        port: number;
+        root: string;
+        enabled: boolean;
+    }, {
+        enabled: import("superstruct").Struct<boolean, null>;
+        port: import("superstruct").Struct<number, null>;
+        root: import("superstruct").Struct<string, null>;
+    }>;
+    browser: import("superstruct").Struct<{
+        headless: boolean;
+    }, {
+        headless: import("superstruct").Struct<boolean, null>;
+    }>;
+}>;
+/**
+ * The options for the environment. These can be specified in the Jest
+ * configuration under `testEnvironmentOptions`.
+ *
+ * @example
+ * ```json
+ * {
+ *   "testEnvironment": "@metamask/snaps-jest",
+ *   "testEnvironmentOptions": {
+ *     "executionEnvironmentUrl": "http://localhost:8080",
+ *     "server": {
+ *       "port": 8080,
+ *       /* ... *\/
+ *     }
+ *   }
+ * }
+ * ```
+ * @property executionEnvironmentUrl - The URL of the execution environment. If
+ * this is not provided, the execution environment will be served from the
+ * built-in HTTP server.
+ * @property simulatorUrl - The URL of the simulator. If this is not provided,
+ * the simulator will be served from the built-in HTTP server.
+ * @property keepAlive - Whether to keep the browser open after the tests have
+ * finished. This is useful for debugging. Defaults to `false`.
+ * @property server - The options for the built-in HTTP server.
+ * @property server.enabled - Whether to run the built-in HTTP server. Defaults
+ * to `true`.
+ * @property server.port - The port to use for the built-in HTTP server. If this
+ * is not provided, a random available port will be used.
+ * @property server.root - The root directory to serve from the built-in HTTP
+ * server. Defaults to the current working directory. This is assumed to be the
+ * directory containing the snap manifest and `dist` files. If this is a
+ * relative path, it will be resolved relative to the current working directory.
+ * @property browser - The options for the browser.
+ * @property browser.headless - Whether to run the browser in headless mode.
+ * Defaults to `true`.
+ */
+export declare type SnapsEnvironmentOptions = Infer<typeof SnapsEnvironmentOptionsStruct>;
+/**
+ * Get the environment options. This validates the options, and returns the
+ * default options if none are provided.
+ *
+ * @param testEnvironmentOptions - The test environment options as defined in
+ * the Jest configuration.
+ * @returns The environment options.
+ */
+export declare function getOptions(testEnvironmentOptions: Record<string, unknown>): {
+    keepAlive: boolean;
+    server: {
+        port: number;
+        root: string;
+        enabled: boolean;
+    };
+    browser: {
+        headless: boolean;
+    };
+    executionEnvironmentUrl?: string | undefined;
+    simulatorUrl?: string | undefined;
+};
+export {};

package/dist/types/setup.d.ts

@@ -0,0 +1 @@
+import './matchers';

package/dist/types/types.d.ts

@@ -0,0 +1,241 @@
+import { NotificationType } from '@metamask/rpc-methods';
+import { Component } from '@metamask/snaps-ui';
+import { EnumToUnion } from '@metamask/snaps-utils';
+import { JsonRpcId, JsonRpcParams } from '@metamask/utils';
+import { Infer } from 'superstruct';
+import { Mock, MockJsonRpcOptions, MockOptions, SnapOptionsStruct, SnapResponseStruct, TransactionOptionsStruct } from './internals';
+declare module 'expect' {
+    interface AsymmetricMatchers {
+        toRespondWith(response: unknown): void;
+        toRespondWithError(error: unknown): void;
+        toSendNotification(message: string, type?: EnumToUnion<NotificationType>): void;
+        toRender(component: Component): void;
+    }
+    interface Matchers<R> {
+        toRespondWith(response: unknown): R;
+        toRespondWithError(error: unknown): R;
+        toSendNotification(message: string, type?: EnumToUnion<NotificationType>): R;
+        toRender(component: Component): R;
+    }
+}
+/**
+ * Deeply partialize a type.
+ *
+ * @template Type - The type to partialize.
+ * @returns The deeply partialized type.
+ * @example
+ * ```ts
+ * type Foo = {
+ *   bar: {
+ *     baz: string;
+ *   };
+ *   qux: number;
+ * };
+ *
+ * type PartialFoo = DeepPartial<Foo>;
+ * // { bar?: { baz?: string; }; qux?: number; }
+ * ```
+ */
+export declare type DeepPartial<Type> = {
+    [Key in keyof Type]?: Type[Key] extends Record<string, unknown> ? DeepPartial<Type[Key]> : Type[Key];
+};
+export declare type RequestOptions = {
+    /**
+     * The JSON-RPC request ID.
+     */
+    id?: JsonRpcId;
+    /**
+     * The JSON-RPC method.
+     */
+    method: string;
+    /**
+     * The JSON-RPC params.
+     */
+    params?: JsonRpcParams;
+    /**
+     * The origin to send the request from.
+     */
+    origin?: string;
+};
+/**
+ * The `runCronjob` options. This is the same as {@link RequestOptions}, except
+ * that it does not have an `origin` property.
+ */
+export declare type CronjobOptions = Omit<RequestOptions, 'origin'>;
+/**
+ * The options to use for transaction requests.
+ *
+ * @property chainId - The CAIP-2 chain ID to send the transaction on. Defaults
+ * to `eip155:1`.
+ * @property origin - The origin to send the transaction from. Defaults to
+ * `metamask.io`.
+ * @property from - The address to send the transaction from. Defaults to a
+ * randomly generated address.
+ * @property to - The address to send the transaction to. Defaults to a randomly
+ * generated address.
+ * @property value - The value to send with the transaction. Defaults to `0`.
+ * @property data - The data to send with the transaction. Defaults to `0x`.
+ * @property gasLimit - The gas limit to use for the transaction. Defaults to
+ * `21_000`.
+ * @property maxFeePerGas - The maximum fee per gas to use for the transaction.
+ * Defaults to `1`.
+ * @property maxPriorityFeePerGas - The maximum priority fee per gas to use for
+ * the transaction. Defaults to `1`.
+ * @property nonce - The nonce to use for the transaction. Defaults to `0`.
+ */
+export declare type TransactionOptions = Infer<typeof TransactionOptionsStruct>;
+/**
+ * The options to use for requests to the snap.
+ *
+ * @property timeout - The timeout in milliseconds to use. Defaults to `1000`.
+ */
+export declare type SnapOptions = Infer<typeof SnapOptionsStruct>;
+/**
+ * A `snap_dialog` alert interface.
+ */
+export declare type SnapAlertInterface = {
+    /**
+     * The type of the interface. This is always `alert`.
+     */
+    type: 'alert';
+    /**
+     * The content to show in the alert.
+     */
+    content: Component;
+    /**
+     * Close the alert.
+     */
+    ok(): Promise<void>;
+};
+/**
+ * A `snap_dialog` confirmation interface.
+ */
+export declare type SnapConfirmationInterface = {
+    /**
+     * The type of the interface. This is always `confirmation`.
+     */
+    type: 'confirmation';
+    /**
+     * The content to show in the confirmation.
+     */
+    content: Component;
+    /**
+     * Close the confirmation.
+     */
+    ok(): Promise<void>;
+    /**
+     * Cancel the confirmation.
+     */
+    cancel(): Promise<void>;
+};
+/**
+ * A `snap_dialog` prompt interface.
+ */
+export declare type SnapPromptInterface = {
+    /**
+     * The type of the interface. This is always `prompt`.
+     */
+    type: 'prompt';
+    /**
+     * The content to show in the prompt.
+     */
+    content: Component;
+    /**
+     * Close the prompt.
+     *
+     * @param value - The value to close the prompt with.
+     */
+    ok(value?: string): Promise<void>;
+    /**
+     * Cancel the prompt.
+     */
+    cancel(): Promise<void>;
+};
+export declare type SnapInterface = SnapAlertInterface | SnapConfirmationInterface | SnapPromptInterface;
+export declare type SnapRequestObject = {
+    /**
+     * Get a user interface object from a snap. This will throw an error if the
+     * snap does not show a user interface within the timeout.
+     *
+     * @param options - The options to use.
+     * @param options.timeout - The timeout in milliseconds to use. Defaults to
+     * `1000`.
+     * @returns The user interface object.
+     */
+    getInterface(options?: SnapOptions): Promise<SnapInterface>;
+};
+/**
+ * A pending request object. This is a promise with extra
+ * {@link SnapRequestObject} fields.
+ */
+export declare type SnapRequest = Promise<SnapResponse> & SnapRequestObject;
+/**
+ * This is the main entry point to interact with the snap. It is returned by
+ * {@link installSnap}, and has methods to send requests to the snap.
+ *
+ * @example
+ * ```ts
+ * import { installSnap } from '@metamask/snaps-jest';
+ *
+ * const snap = await installSnap();
+ * const response = await snap.request({ method: 'hello' });
+ *
+ * expect(response).toRespondWith('Hello, world!');
+ * ```
+ */
+export declare type Snap = {
+    /**
+     * Send a JSON-RPC request to the snap.
+     *
+     * @param request - The request. This is similar to a JSON-RPC request, but
+     * has an extra `origin` field.
+     * @returns The response promise, with extra {@link SnapRequestObject} fields.
+     */
+    request(request: RequestOptions): SnapRequest;
+    /**
+     * Send a transaction to the snap.
+     *
+     * @param transaction - The transaction. This is similar to an Ethereum
+     * transaction object, but has an extra `origin` field. Any missing fields
+     * will be filled in with default values.
+     * @returns The response.
+     */
+    sendTransaction(transaction?: Partial<TransactionOptions>): Promise<SnapResponse>;
+    /**
+     * Run a cronjob in the snap. This is similar to {@link request}, but the
+     * request will be sent to the `onCronjob` method of the snap.
+     *
+     * @param cronjob - The cronjob request. This is similar to a JSON-RPC
+     * request, and is normally specified in the snap manifest, under the
+     * `endowment:cronjob` permission.
+     * @returns The response promise, with extra {@link SnapRequestObject} fields.
+     */
+    runCronjob(cronjob: CronjobOptions): SnapRequest;
+    /**
+     * Close the page running the snap. This is mainly useful for cleaning up
+     * the test environment, and calling it is not strictly necessary.
+     *
+     * @returns A promise that resolves when the page is closed.
+     */
+    close(): Promise<void>;
+    /**
+     * Enable network mocking for the snap.
+     *
+     * @param options - The options for the network mocking.
+     * @returns A {@link Mock} object, with an `unmock` function.
+     */
+    mock(options: DeepPartial<MockOptions>): Promise<Mock>;
+    /**
+     * Enable JSON-RPC provider mocking for the snap. This will mock any requests
+     * sent through the `ethereum` global, with the specified `method`.
+     *
+     * @param options - The options for the JSON-RPC mocking.
+     * @param options.method - The JSON-RPC method to mock, e.g.,
+     * `eth_blockNumber`.
+     * @param options.result - The JSON value to return.
+     * @returns A {@link Mock} object, with an `unmock` function.
+     */
+    mockJsonRpc(options: MockJsonRpcOptions): Promise<Mock>;
+};
+export declare type SnapResponse = Infer<typeof SnapResponseStruct>;
+export { NotificationType } from '@metamask/rpc-methods';

package/jest-preset.js

@@ -0,0 +1,18 @@
+/* eslint-disable jsdoc/valid-types */
+
+const { resolve } = require('path');
+
+/**
+ * @type {import('jest').Config}
+ */
+const config = {
+  testEnvironment: '@metamask/snaps-jest',
+
+  // End-to-end tests can take longer than usual to run, so we set the test
+  // timeout to 30 seconds by default.
+  testTimeout: 30000,
+
+  setupFilesAfterEnv: [resolve(__dirname, 'dist', 'cjs', 'setup.js')],
+};
+
+module.exports = config;