@metamask/snaps-jest 4.0.0 → 5.0.0

package/dist/types/internals/simulation/methods/hooks/state.d.ts

@@ -0,0 +1,22 @@
+import type { RunSagaFunction } from '../../store';
+/**
+ * Get the implementation of the `getSnapState` hook.
+ *
+ * @param runSaga - The function to run a saga outside the usual Redux flow.
+ * @returns The implementation of the `getSnapState` hook.
+ */
+export declare function getGetSnapStateMethodImplementation(runSaga: RunSagaFunction): (_snapId: string, encrypted?: boolean | undefined) => any;
+/**
+ * Get the implementation of the `updateSnapState` hook.
+ *
+ * @param runSaga - The function to run a saga outside the usual Redux flow.
+ * @returns The implementation of the `updateSnapState` hook.
+ */
+export declare function getUpdateSnapStateMethodImplementation(runSaga: RunSagaFunction): (_snapId: string, newState: string, encrypted?: boolean | undefined) => void;
+/**
+ * Get the implementation of the `clearSnapState` hook.
+ *
+ * @param runSaga - The function to run a saga outside the usual Redux flow.
+ * @returns The implementation of the `clearSnapState` hook.
+ */
+export declare function getClearSnapStateMethodImplementation(runSaga: RunSagaFunction): (_snapId: string, encrypted?: boolean | undefined) => Promise<void>;

package/dist/types/internals/simulation/methods/index.d.ts

@@ -0,0 +1 @@
+export * from './specifications';

package/dist/types/internals/simulation/methods/specifications.d.ts

@@ -0,0 +1,56 @@
+import type { GenericPermissionController } from '@metamask/permission-controller';
+import type { SnapId } from '@metamask/snaps-sdk';
+import type { RootControllerMessenger } from '../controllers';
+import type { SimulationOptions } from '../options';
+import type { RunSagaFunction } from '../store';
+export declare type PermissionSpecificationsHooks = {
+    /**
+     * A hook that returns the user's secret recovery phrase.
+     *
+     * @returns The user's secret recovery phrase.
+     */
+    getMnemonic: () => Promise<Uint8Array>;
+};
+export declare type GetPermissionSpecificationsOptions = {
+    controllerMessenger: RootControllerMessenger;
+    hooks: PermissionSpecificationsHooks;
+    runSaga: RunSagaFunction;
+    options: SimulationOptions;
+};
+/**
+ * Get a function which resolves with the specified result.
+ *
+ * @param result - The result to return.
+ * @returns The function implementation.
+ */
+export declare function resolve(result: unknown): () => unknown;
+/**
+ * Get a function which resolves with the specified result.
+ *
+ * @param result - The result to return. If not specified, the function will
+ * resolve with `undefined`.
+ * @returns The function implementation.
+ */
+export declare function asyncResolve(result?: unknown): () => Promise<unknown>;
+/**
+ * Get the permission specifications for the Snap.
+ *
+ * @param options - The options.
+ * @param options.controllerMessenger - The controller messenger.
+ * @param options.hooks - The hooks.
+ * @param options.runSaga - The function to run a saga outside the usual Redux
+ * flow.
+ * @param options.options - The simulation options.
+ * @returns The permission specifications for the Snap.
+ */
+export declare function getPermissionSpecifications({ controllerMessenger, hooks, runSaga, options, }: GetPermissionSpecificationsOptions): {
+    [x: string]: import("@metamask/permission-controller").PermissionSpecificationConstraint;
+};
+/**
+ * Get the endowments for the Snap.
+ *
+ * @param permissionController - The permission controller.
+ * @param snapId - The ID of the Snap.
+ * @returns The endowments for the Snap.
+ */
+export declare function getEndowments(permissionController: GenericPermissionController, snapId: SnapId): Promise<string[]>;

package/dist/types/internals/simulation/middleware/engine.d.ts

@@ -0,0 +1,26 @@
+import type { JsonRpcMiddleware } from '@metamask/json-rpc-engine';
+import { JsonRpcEngine } from '@metamask/json-rpc-engine';
+import type { RestrictedMethodParameters } from '@metamask/permission-controller';
+import type { Json } from '@metamask/utils';
+import type { MiddlewareHooks } from '../simulation';
+import type { Store } from '../store';
+export declare type CreateJsonRpcEngineOptions = {
+    store: Store;
+    hooks: MiddlewareHooks;
+    permissionMiddleware: JsonRpcMiddleware<RestrictedMethodParameters, Json>;
+    endpoint?: string;
+};
+/**
+ * Create a JSON-RPC engine for use in a simulated environment. This engine
+ * should be used to handle all JSON-RPC requests. It is set up to handle
+ * requests that would normally be handled internally by the MetaMask client, as
+ * well as Snap-specific requests.
+ *
+ * @param options - The options to use when creating the engine.
+ * @param options.store - The Redux store to use.
+ * @param options.hooks - Any hooks used by the middleware handlers.
+ * @param options.permissionMiddleware - The permission middleware to use.
+ * @param options.endpoint - The JSON-RPC endpoint to use for Ethereum requests.
+ * @returns A JSON-RPC engine.
+ */
+export declare function createJsonRpcEngine({ store, hooks, permissionMiddleware, endpoint, }: CreateJsonRpcEngineOptions): JsonRpcEngine;

package/dist/types/internals/simulation/middleware/index.d.ts

@@ -0,0 +1 @@
+export * from './engine';

package/dist/types/internals/simulation/middleware/internal-methods/accounts.d.ts

@@ -0,0 +1,18 @@
+import type { JsonRpcEngineEndCallback, JsonRpcEngineNextCallback } from '@metamask/json-rpc-engine';
+import type { Json, JsonRpcRequest, PendingJsonRpcResponse } from '@metamask/utils';
+export declare type GetAccountsHandlerHooks = {
+    getMnemonic: () => Promise<Uint8Array>;
+};
+/**
+ * A mock handler for account related methods that always returns the first
+ * address for the selected secret recovery phrase.
+ *
+ * @param _request - Incoming JSON-RPC request. This is ignored for this
+ * specific handler.
+ * @param response - The outgoing JSON-RPC response, modified to return the
+ * result.
+ * @param _next - The `json-rpc-engine` middleware next handler.
+ * @param end - The `json-rpc-engine` middleware end handler.
+ * @param hooks - Any hooks required by this handler.
+ */
+export declare function getAccountsHandler(_request: JsonRpcRequest, response: PendingJsonRpcResponse<Json>, _next: JsonRpcEngineNextCallback, end: JsonRpcEngineEndCallback, hooks: GetAccountsHandlerHooks): Promise<void>;

package/dist/types/internals/simulation/middleware/internal-methods/index.d.ts

@@ -0,0 +1 @@
+export * from './middleware';

package/dist/types/internals/simulation/middleware/internal-methods/middleware.d.ts

@@ -0,0 +1,22 @@
+import type { JsonRpcMiddleware } from '@metamask/json-rpc-engine';
+import type { Json, JsonRpcParams } from '@metamask/utils';
+export declare type InternalMethodsMiddlewareHooks = {
+    /**
+     * A hook that returns the user's secret recovery phrase.
+     *
+     * @returns The user's secret recovery phrase.
+     */
+    getMnemonic: () => Promise<Uint8Array>;
+};
+/**
+ * Create a middleware for handling JSON-RPC methods normally handled internally
+ * by the MetaMask client.
+ *
+ * NOTE: This middleware provides all `hooks` to all handlers and should
+ * therefore NOT be used outside of the simulation environment. It is intended
+ * for testing purposes only.
+ *
+ * @param hooks - Any hooks used by the middleware handlers.
+ * @returns A middleware function.
+ */
+export declare function createInternalMethodsMiddleware(hooks: InternalMethodsMiddlewareHooks): JsonRpcMiddleware<JsonRpcParams, Json>;

package/dist/types/internals/simulation/middleware/internal-methods/provider-state.d.ts

@@ -0,0 +1,14 @@
+import type { JsonRpcEngineEndCallback, JsonRpcEngineNextCallback } from '@metamask/json-rpc-engine';
+import type { Json, JsonRpcRequest, PendingJsonRpcResponse } from '@metamask/utils';
+/**
+ * A mock handler for metamask_getProviderState that always returns a specific
+ * hardcoded result.
+ *
+ * @param _request - Incoming JSON-RPC request. Ignored for this specific
+ * handler.
+ * @param response - The outgoing JSON-RPC response, modified to return the
+ * result.
+ * @param _next - The `json-rpc-engine` middleware next handler.
+ * @param end - The `json-rpc-engine` middleware end handler.
+ */
+export declare function getProviderStateHandler(_request: JsonRpcRequest, response: PendingJsonRpcResponse<Json>, _next: JsonRpcEngineNextCallback, end: JsonRpcEngineEndCallback): Promise<void>;

package/dist/types/internals/simulation/middleware/mock.d.ts

@@ -0,0 +1,10 @@
+import type { JsonRpcMiddleware } from '@metamask/json-rpc-engine';
+import type { Json, JsonRpcParams } from '@metamask/utils';
+import type { Store } from '../store';
+/**
+ * Create a middleware for handling JSON-RPC methods that have been mocked.
+ *
+ * @param store - The Redux store to use.
+ * @returns A middleware function.
+ */
+export declare function createMockMiddleware(store: Store): JsonRpcMiddleware<JsonRpcParams, Json>;

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

@@ -0,0 +1,37 @@
+import type { Infer } from 'superstruct';
+declare const SimulationOptionsStruct: import("superstruct").Struct<{
+    state?: Record<string, import("@metamask/utils").Json> | null | undefined;
+    locale?: string | undefined;
+    secretRecoveryPhrase?: string | undefined;
+    unencryptedState?: Record<string, import("@metamask/utils").Json> | null | undefined;
+}, {
+    secretRecoveryPhrase: import("superstruct").Struct<string | undefined, null>;
+    locale: import("superstruct").Struct<string | undefined, null>;
+    state: import("superstruct").Struct<Record<string, import("@metamask/utils").Json> | null | undefined, null>;
+    unencryptedState: import("superstruct").Struct<Record<string, import("@metamask/utils").Json> | null | undefined, null>;
+}>;
+/**
+ * Options for the simulation.
+ *
+ * @property secretRecoveryPhrase - The secret recovery phrase to use. This is
+ * used to derive addresses and private keys. Defaults to a test recovery
+ * phrase.
+ * @property locale - The locale to use. Defaults to `en`.
+ * @property state - The initial state of the Snap, if any. Defaults to `null`.
+ */
+export declare type SimulationUserOptions = Infer<typeof SimulationOptionsStruct>;
+/**
+ * Options for the simulation, with defaults filled in.
+ *
+ * See {@link SimulationUserOptions} for documentation.
+ */
+export declare type SimulationOptions = Required<SimulationUserOptions>;
+/**
+ * Get the options for the simulation.
+ *
+ * @param options - The user options. Any options not specified will be filled
+ * in with default values.
+ * @returns The simulation options.
+ */
+export declare function getOptions(options: SimulationUserOptions): SimulationOptions;
+export {};

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

@@ -0,0 +1,98 @@
+import type { ActionConstraint, EventConstraint } from '@metamask/base-controller';
+import { ControllerMessenger } from '@metamask/base-controller';
+import type { AbstractExecutionService } from '@metamask/snaps-controllers';
+import type { SnapId, AuxiliaryFileEncoding, Component, InterfaceState } from '@metamask/snaps-sdk';
+import type { FetchedSnapFiles } from '@metamask/snaps-utils';
+import type { RootControllerMessenger } from './controllers';
+import type { SimulationOptions, SimulationUserOptions } from './options';
+import type { RunSagaFunction, Store } from './store';
+/**
+ * Options for the execution service, without the options that are shared
+ * between all execution services.
+ *
+ * @template Service - The type of the execution service, i.e., the class that
+ * creates the execution service.
+ */
+export declare type ExecutionServiceOptions<Service extends new (...args: any[]) => any> = Omit<ConstructorParameters<Service>[0], keyof ConstructorParameters<typeof AbstractExecutionService<unknown>>[0]>;
+/**
+ * The options for running a Snap in a simulated environment.
+ *
+ * @property executionService - The execution service to use.
+ * @property executionServiceOptions - The options to use when creating the
+ * execution service, if any. This should only include options specific to the
+ * provided execution service.
+ * @property options - The simulation options.
+ * @template Service - The type of the execution service.
+ */
+export declare type InstallSnapOptions<Service extends new (...args: any[]) => InstanceType<typeof AbstractExecutionService<unknown>>> = ExecutionServiceOptions<Service> extends Record<string, never> ? {
+    executionService: Service;
+    executionServiceOptions?: ExecutionServiceOptions<Service>;
+    options?: SimulationUserOptions;
+} : {
+    executionService: Service;
+    executionServiceOptions: ExecutionServiceOptions<Service>;
+    options?: SimulationUserOptions;
+};
+export declare type InstalledSnap = {
+    snapId: SnapId;
+    store: Store;
+    executionService: InstanceType<typeof AbstractExecutionService>;
+    controllerMessenger: ControllerMessenger<ActionConstraint, EventConstraint>;
+    runSaga: RunSagaFunction;
+};
+export declare type MiddlewareHooks = {
+    /**
+     * A hook that returns the user's secret recovery phrase.
+     *
+     * @returns The user's secret recovery phrase.
+     */
+    getMnemonic: () => Promise<Uint8Array>;
+    /**
+     * A hook that returns the Snap's auxiliary file for the given path.
+     *
+     * @param path - The path of the auxiliary file to get.
+     * @param encoding - The encoding to use when returning the file.
+     * @returns The Snap's auxiliary file for the given path.
+     */
+    getSnapFile: (path: string, encoding: AuxiliaryFileEncoding) => Promise<string | null>;
+    /**
+     * A hook that returns whether the client is locked or not.
+     *
+     * @returns A boolean flag signaling whether the client is locked.
+     */
+    getIsLocked: () => boolean;
+    createInterface: (content: Component) => Promise<string>;
+    updateInterface: (id: string, content: Component) => Promise<void>;
+    getInterfaceState: (id: string) => InterfaceState;
+};
+/**
+ * Install a Snap in a simulated environment. This will fetch the Snap files,
+ * create a Redux store, set up the controllers and JSON-RPC stack, register the
+ * Snap, and run the Snap code in the execution service.
+ *
+ * @param snapId - The ID of the Snap to install.
+ * @param options - The options to use when installing the Snap.
+ * @param options.executionService - The execution service to use.
+ * @param options.executionServiceOptions - The options to use when creating the
+ * execution service, if any. This should only include options specific to the
+ * provided execution service.
+ * @param options.options - The simulation options.
+ * @template Service - The type of the execution service.
+ */
+export declare function handleInstallSnap<Service extends new (...args: any[]) => InstanceType<typeof AbstractExecutionService>>(snapId: SnapId, { executionService, executionServiceOptions, options: rawOptions, }?: Partial<InstallSnapOptions<Service>>): Promise<InstalledSnap>;
+/**
+ * Get the hooks for the simulation.
+ *
+ * @param options - The simulation options.
+ * @param snapFiles - The Snap files.
+ * @param snapId - The Snap ID.
+ * @param controllerMessenger - The controller messenger.
+ * @returns The hooks for the simulation.
+ */
+export declare function getHooks(options: SimulationOptions, snapFiles: FetchedSnapFiles, snapId: SnapId, controllerMessenger: RootControllerMessenger): MiddlewareHooks;
+/**
+ * Register mocked action handlers.
+ *
+ * @param controllerMessenger - The controller messenger.
+ */
+export declare function registerActions(controllerMessenger: RootControllerMessenger): void;

package/dist/types/internals/simulation/store/index.d.ts

@@ -0,0 +1,4 @@
+export * from './notifications';
+export * from './state';
+export * from './store';
+export * from './ui';

package/dist/types/internals/simulation/store/mocks.d.ts

@@ -0,0 +1,35 @@
+import type { Json } from '@metamask/utils';
+import type { PayloadAction } from '@reduxjs/toolkit';
+import type { ApplicationState } from './store';
+export declare type JsonRpcMock = {
+    method: string;
+    result: Json;
+};
+export declare type MocksState = {
+    jsonRpc: Record<string, Json>;
+};
+export declare const mocksSlice: import("@reduxjs/toolkit").Slice<MocksState, {
+    addJsonRpcMock: (state: import("immer/dist/internal").WritableDraft<MocksState>, action: PayloadAction<JsonRpcMock>) => void;
+    removeJsonRpcMock: (state: import("immer/dist/internal").WritableDraft<MocksState>, action: PayloadAction<string>) => void;
+}, "mocks">;
+export declare const addJsonRpcMock: import("@reduxjs/toolkit").ActionCreatorWithPayload<JsonRpcMock, "mocks/addJsonRpcMock">, removeJsonRpcMock: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "mocks/removeJsonRpcMock">;
+/**
+ * Get the JSON-RPC mocks from the state.
+ *
+ * @param state - The application state.
+ * @returns The JSON-RPC mocks.
+ */
+export declare const getJsonRpcMocks: (state: ApplicationState) => Record<string, Json>;
+/**
+ * Get the JSON-RPC mock for a given method from the state.
+ */
+export declare const getJsonRpcMock: ((state: {
+    mocks: MocksState;
+    notifications: import("./notifications").NotificationsState;
+    state: import("./state").State;
+    ui: import("./ui").UiState;
+}, method: string) => Json) & import("reselect").OutputSelectorFields<(args_0: Record<string, Json>, args_1: string) => Json, {
+    clearCache: () => void;
+}> & {
+    clearCache: () => void;
+};

package/dist/types/internals/simulation/store/notifications.d.ts

@@ -0,0 +1,44 @@
+import type { NotificationType } from '@metamask/snaps-sdk';
+import type { PayloadAction } from '@reduxjs/toolkit';
+/**
+ * A notification object.
+ *
+ * @property id - A unique ID for the notification.
+ * @property message - The notification message.
+ * @property type - The notification type.
+ */
+export declare type Notification = {
+    id: string;
+    message: string;
+    type: NotificationType;
+};
+/**
+ * The notifications state.
+ *
+ * @property notifications - An array of notifications.
+ */
+export declare type NotificationsState = {
+    notifications: Notification[];
+};
+export declare const notificationsSlice: import("@reduxjs/toolkit").Slice<NotificationsState, {
+    addNotification: (state: import("immer/dist/internal").WritableDraft<NotificationsState>, action: PayloadAction<Notification>) => void;
+    removeNotification: (state: import("immer/dist/internal").WritableDraft<NotificationsState>, action: PayloadAction<string>) => void;
+    clearNotifications: (state: import("immer/dist/internal").WritableDraft<NotificationsState>) => void;
+}, "notifications">;
+export declare const addNotification: import("@reduxjs/toolkit").ActionCreatorWithPayload<Notification, "notifications/addNotification">, removeNotification: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "notifications/removeNotification">, clearNotifications: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"notifications/clearNotifications">;
+/**
+ * Get the notifications from the state.
+ *
+ * @param state - The application state.
+ * @returns An array of notifications.
+ */
+export declare const getNotifications: ((state: {
+    mocks: import("./mocks").MocksState;
+    notifications: NotificationsState;
+    state: import("./state").State;
+    ui: import("./ui").UiState;
+}) => Notification[]) & import("reselect").OutputSelectorFields<(args_0: NotificationsState) => Notification[], {
+    clearCache: () => void;
+}> & {
+    clearCache: () => void;
+};

package/dist/types/internals/simulation/store/state.d.ts

@@ -0,0 +1,55 @@
+import type { PayloadAction } from '@reduxjs/toolkit';
+/**
+ * The Snap state object.
+ *
+ * @property encrypted - The encrypted state. Can be null if the Snap does not
+ * have an encrypted state.
+ * @property unencrypted - The unencrypted state. Can be null if the Snap does
+ * not have an unencrypted state.
+ */
+export declare type State = {
+    encrypted: string | null;
+    unencrypted: string | null;
+};
+/**
+ * The state slice, which stores the state of the Snap.
+ */
+export declare const stateSlice: import("@reduxjs/toolkit").Slice<State, {
+    setState: (state: import("immer/dist/internal").WritableDraft<State>, action: {
+        payload: {
+            state: string | null;
+            encrypted: boolean;
+        };
+        type: string;
+    }) => import("immer/dist/internal").WritableDraft<State>;
+    clearState: (state: import("immer/dist/internal").WritableDraft<State>, action: PayloadAction<{
+        encrypted: boolean;
+    }>) => import("immer/dist/internal").WritableDraft<State>;
+}, "state">;
+export declare const setState: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    state: string | null;
+    encrypted: boolean;
+}, "state/setState">, clearState: import("@reduxjs/toolkit").ActionCreatorWithPayload<{
+    encrypted: boolean;
+}, "state/clearState">;
+/**
+ * Get the state from the store.
+ *
+ * @param encrypted - Whether to get the encrypted or unencrypted state.
+ * @returns A selector that returns the state.
+ */
+export declare function getState(encrypted: boolean): ((state: {
+    mocks: import("./mocks").MocksState;
+    notifications: import("./notifications").NotificationsState;
+    state: State;
+    ui: import("./ui").UiState;
+}) => string | null) & import("reselect").OutputSelectorFields<(args_0: {
+    mocks: import("./mocks").MocksState;
+    notifications: import("./notifications").NotificationsState;
+    state: State;
+    ui: import("./ui").UiState;
+}) => string | null, {
+    clearCache: () => void;
+}> & {
+    clearCache: () => void;
+};

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

@@ -0,0 +1,22 @@
+import type { SimulationOptions } from '../options';
+/**
+ * Create a Redux store.
+ *
+ * @param password - The password to use for state encryption.
+ * @param options - The simulation options.
+ * @param options.state - The initial state for the Snap.
+ * @param options.unencryptedState - The initial unencrypted state for the Snap.
+ * @returns A Redux store with the default state.
+ */
+export declare function createStore(password: string, { state, unencryptedState }: SimulationOptions): {
+    store: import("@reduxjs/toolkit/dist/configureStore").ToolkitStore<{
+        mocks: import("./mocks").MocksState;
+        notifications: import("./notifications").NotificationsState;
+        state: import("./state").State;
+        ui: import("./ui").UiState;
+    }, import("redux").AnyAction, import("@reduxjs/toolkit").MiddlewareArray<[import("redux-saga").SagaMiddleware<object>]>>;
+    runSaga: <S extends import("redux-saga").Saga<any[]>>(saga: S, ...args: Parameters<S>) => import("redux-saga").Task<any>;
+};
+export declare type Store = ReturnType<typeof createStore>['store'];
+export declare type ApplicationState = ReturnType<Store['getState']>;
+export declare type RunSagaFunction = ReturnType<typeof createStore>['runSaga'];

package/dist/types/internals/simulation/store/ui.d.ts

@@ -0,0 +1,25 @@
+import type { DialogType } from '@metamask/snaps-sdk';
+import type { PayloadAction } from '@reduxjs/toolkit';
+export declare type Interface = {
+    type: DialogType;
+    id: string;
+};
+export declare type UiState = {
+    current?: Interface | null;
+};
+export declare const uiSlice: import("@reduxjs/toolkit").Slice<UiState, {
+    setInterface(state: import("immer/dist/internal").WritableDraft<UiState>, action: PayloadAction<Interface>): void;
+    closeInterface(state: import("immer/dist/internal").WritableDraft<UiState>): void;
+}, "ui">;
+export declare const resolveInterface: import("@reduxjs/toolkit").ActionCreatorWithNonInferrablePayload<string>;
+export declare const setInterface: import("@reduxjs/toolkit").ActionCreatorWithPayload<Interface, "ui/setInterface">, closeInterface: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"ui/closeInterface">;
+export declare const getCurrentInterface: ((state: {
+    mocks: import("./mocks").MocksState;
+    notifications: import("./notifications").NotificationsState;
+    state: import("./state").State;
+    ui: UiState;
+}) => Interface | null | undefined) & import("reselect").OutputSelectorFields<(args_0: UiState) => Interface | null | undefined, {
+    clearCache: () => void;
+}> & {
+    clearCache: () => void;
+};