@metamask/snaps-simulation/dist/helpers.d.mts

A simulation framework for MetaMask Snaps, enabling headless testing of Snaps in a controlled environment

import type { CaipChainId } from "@metamask/utils";
import type { SimulationOptions } from "./options.mjs";
import type { InstalledSnap } from "./simulation.mjs";
import type { CronjobOptions, JsonRpcMockOptions, KeyringOptions, NameLookupOptions, RequestOptions, SignatureOptions, SnapRequest, SnapResponseWithInterface, SnapResponseWithoutInterface, TransactionOptions } from "./types.mjs";
/**
 * 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
 * import { installSnap } from '@metamask/snaps-jest';
 *
 * const snap = await installSnap();
 * const response = await snap.request({ method: 'hello' });
 *
 * expect(response).toRespondWith('Hello, world!');
 */
export type SnapHelpers = {
    /**
     * 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.
     */
    onTransaction(transaction?: Partial<TransactionOptions>): Promise<SnapResponseWithInterface>;
    /**
     * 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.
     * @deprecated Use {@link onTransaction} instead.
     */
    sendTransaction(transaction?: Partial<TransactionOptions>): Promise<SnapResponseWithInterface>;
    /**
     * Send a signature request to the snap.
     *
     * @param signature - The signature request object. Contains the params from
     * the various signature methods, but has an extra `origin` and `signatureMethod` field.
     * Any missing fields will be filled in with default values.
     * @returns The response.
     */
    onSignature(signature?: Partial<SignatureOptions>): Promise<SnapResponseWithInterface>;
    /**
     * 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.
     */
    onCronjob(cronjob?: Partial<CronjobOptions>): SnapRequest;
    /**
     * 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.
     * @deprecated Use {@link onCronjob} instead.
     */
    runCronjob(cronjob: CronjobOptions): SnapRequest;
    /**
     * Run a background event in the snap. This is similar to {@link request}, but the
     * request will be sent to the `onCronjob` method of the snap.
     *
     * @param backgroundEvent - The background event request. This is similar to a JSON-RPC
     * request, and is normally specified in the `request` param of the `snap_scheduleBackgroundEvent` method.
     * @returns The response promise, with extra {@link SnapRequestObject} fields.
     */
    onBackgroundEvent(backgroundEvent: CronjobOptions): SnapRequest;
    /**
     * Get the response from the snap's `onHomePage` method.
     *
     * @returns The response.
     */
    onHomePage(): Promise<SnapResponseWithInterface>;
    /**
     * Get the response from the snap's `onSettingsPage` method.
     *
     * @returns The response.
     */
    onSettingsPage(): Promise<SnapResponseWithInterface>;
    /**
     * Send a keyring request to the Snap.
     *
     * @param keyringRequest - Keyring request.
     * @returns The response.
     */
    onKeyringRequest(keyringRequest: KeyringOptions): SnapRequest;
    /**
     * Get the response from the Snap's `onInstall` handler.
     *
     * @returns The response.
     */
    onInstall(request?: Pick<RequestOptions, 'origin'>): SnapRequest;
    /**
     * Get the response from the Snap's `onUpdate` handler.
     *
     * @returns The response.
     */
    onUpdate(request?: Pick<RequestOptions, 'origin'>): SnapRequest;
    /**
     * Get the response from the Snap's `onStart` handler.
     *
     * @returns The response.
     */
    onStart(request?: Pick<RequestOptions, 'origin'>): SnapRequest;
    /**
     * Get the response from the Snap's `onNameLookup` handler.
     *
     * @returns The response.
     */
    onNameLookup(request: NameLookupOptions): Promise<SnapResponseWithoutInterface>;
    /**
     * Send a JSON-RPC protocol request to the Snap.
     *
     * @param scope - A CAIP-2 scope.
     * @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.
     */
    onProtocolRequest(scope: CaipChainId, request: RequestOptions): Promise<SnapResponseWithoutInterface>;
    /**
     * Send a JSON-RPC client request to the Snap.
     *
     * @param request - The JSON-RPC request.
     * @returns The response promise, with extra {@link SnapRequestObject} fields.
     */
    onClientRequest(request: Omit<RequestOptions, 'origin'>): SnapRequest;
    /**
     * Mock a JSON-RPC request. This will cause the snap to respond with the
     * specified response when a request with the specified method is sent.
     *
     * @param mock - The mock options.
     * @param mock.method - The JSON-RPC request method.
     * @param mock.result - The JSON-RPC response, which will be returned when a
     * request with the specified method is sent.
     * @example
     * import { installSnap } from '@metamask/snaps-jest';
     *
     * // In the test
     * const snap = await installSnap();
     * snap.mockJsonRpc({ method: 'eth_accounts', result: ['0x1234'] });
     *
     * // In the Snap
     * const response =
     *   await ethereum.request({ method: 'eth_accounts' }); // ['0x1234']
     */
    mockJsonRpc(mock: JsonRpcMockOptions): {
        /**
         * Remove the mock.
         */
        unmock(): void;
    };
    /**
     * 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>;
};
/**
 * Get the helper functions for the Snap.
 *
 * @param snap - The installed Snap.
 * @param snap.snapId - The ID of the Snap.
 * @param snap.store - The Redux store.
 * @param snap.executionService - The execution service.
 * @param snap.runSaga - The `runSaga` function.
 * @param snap.controllerMessenger - The controller messenger.
 * @param snap.options - The simulation options.
 * @returns The Snap helpers.
 */
export declare function getHelpers({ snapId, store, executionService, runSaga, controllerMessenger, options, }: InstalledSnap & {
    options: SimulationOptions;
}): SnapHelpers;
//# sourceMappingURL=helpers.d.mts.map