@metamask/snaps-jest 4.0.1 → 6.0.0

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;
+};

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

@@ -61,6 +61,32 @@ export declare const TransactionOptionsStruct: import("superstruct").Struct<{
      */
     data: import("superstruct").Struct<`0x${string}`, null>;
 }>;
+export declare const SignatureOptionsStruct: import("superstruct").Struct<{
+    data: `0x${string}` | Record<string, any> | Record<string, any>[];
+    from: `0x${string}`;
+    origin: string;
+    signatureMethod: "eth_sign" | "personal_sign" | "eth_signTypedData" | "eth_signTypedData_v3" | "eth_signTypedData_v4";
+}, {
+    /**
+     * The origin making the signature request.
+     */
+    origin: import("superstruct").Struct<string, null>;
+    /**
+     * The address signing the signature request. Defaults to a randomly generated
+     * address.
+     */
+    from: import("superstruct").Struct<`0x${string}`, null>;
+    /**
+     * The data to send with the transaction. The data may be specified as a
+     * `string`, an object, or an array of objects. This covers the data types
+     * for the supported signature methods. Defaults to `0x`.
+     */
+    data: import("superstruct").Struct<`0x${string}` | Record<string, any> | Record<string, any>[], null>;
+    /**
+     * The signature method being used.
+     */
+    signatureMethod: import("superstruct").Struct<"eth_sign" | "personal_sign" | "eth_signTypedData" | "eth_signTypedData_v3" | "eth_signTypedData_v4", null>;
+}>;
 export declare const SnapOptionsStruct: import("superstruct").Struct<{
     timeout?: number | undefined;
 }, {
@@ -70,6 +96,13 @@ export declare const SnapOptionsStruct: import("superstruct").Struct<{
      */
     timeout: import("superstruct").Struct<number | undefined, null>;
 }>;
+export declare const JsonRpcMockOptionsStruct: import("superstruct").Struct<{
+    result: import("@metamask/snaps-sdk").Json;
+    method: string;
+}, {
+    method: import("superstruct").Struct<string, null>;
+    result: import("superstruct").Struct<import("@metamask/snaps-sdk").Json, unknown>;
+}>;
 export declare const InterfaceStruct: import("superstruct").Struct<{
     content?: import("@metamask/snaps-sdk").Panel | {
         value: string;
@@ -107,6 +140,36 @@ export declare const InterfaceStruct: import("superstruct").Struct<{
         type: import("@metamask/snaps-sdk").NodeType.Row;
         label: string;
         variant?: "default" | "warning" | "critical" | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Input;
+        name: string;
+        value?: string | undefined;
+        label?: string | undefined;
+        inputType?: "number" | "text" | "password" | undefined;
+        placeholder?: string | undefined;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Button;
+        name?: string | undefined;
+        variant?: "primary" | "secondary" | undefined;
+        buttonType?: "button" | "submit" | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Form;
+        name: string;
+        children: ({
+            type: import("@metamask/snaps-sdk").NodeType.Input;
+            name: string;
+            value?: string | undefined;
+            label?: string | undefined;
+            inputType?: "number" | "text" | "password" | undefined;
+            placeholder?: string | undefined;
+        } | {
+            value: string;
+            type: import("@metamask/snaps-sdk").NodeType.Button;
+            name?: string | undefined;
+            variant?: "primary" | "secondary" | undefined;
+            buttonType?: "button" | "submit" | undefined;
+        })[];
     } | undefined;
 }, {
     content: import("superstruct").Struct<import("@metamask/snaps-sdk").Panel | {
@@ -145,6 +208,36 @@ export declare const InterfaceStruct: import("superstruct").Struct<{
         type: import("@metamask/snaps-sdk").NodeType.Row;
         label: string;
         variant?: "default" | "warning" | "critical" | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Input;
+        name: string;
+        value?: string | undefined;
+        label?: string | undefined;
+        inputType?: "number" | "text" | "password" | undefined;
+        placeholder?: string | undefined;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Button;
+        name?: string | undefined;
+        variant?: "primary" | "secondary" | undefined;
+        buttonType?: "button" | "submit" | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Form;
+        name: string;
+        children: ({
+            type: import("@metamask/snaps-sdk").NodeType.Input;
+            name: string;
+            value?: string | undefined;
+            label?: string | undefined;
+            inputType?: "number" | "text" | "password" | undefined;
+            placeholder?: string | undefined;
+        } | {
+            value: string;
+            type: import("@metamask/snaps-sdk").NodeType.Button;
+            name?: string | undefined;
+            variant?: "primary" | "secondary" | undefined;
+            buttonType?: "button" | "submit" | undefined;
+        })[];
     } | undefined, null>;
 }>;
 export declare const SnapResponseStruct: import("superstruct").Struct<{
@@ -195,6 +288,36 @@ export declare const SnapResponseStruct: import("superstruct").Struct<{
         type: import("@metamask/snaps-sdk").NodeType.Row;
         label: string;
         variant?: "default" | "warning" | "critical" | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Input;
+        name: string;
+        value?: string | undefined;
+        label?: string | undefined;
+        inputType?: "number" | "text" | "password" | undefined;
+        placeholder?: string | undefined;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Button;
+        name?: string | undefined;
+        variant?: "primary" | "secondary" | undefined;
+        buttonType?: "button" | "submit" | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Form;
+        name: string;
+        children: ({
+            type: import("@metamask/snaps-sdk").NodeType.Input;
+            name: string;
+            value?: string | undefined;
+            label?: string | undefined;
+            inputType?: "number" | "text" | "password" | undefined;
+            placeholder?: string | undefined;
+        } | {
+            value: string;
+            type: import("@metamask/snaps-sdk").NodeType.Button;
+            name?: string | undefined;
+            variant?: "primary" | "secondary" | undefined;
+            buttonType?: "button" | "submit" | undefined;
+        })[];
     } | undefined;
 }, {
     id: import("superstruct").Struct<string, null>;
@@ -252,5 +375,35 @@ export declare const SnapResponseStruct: import("superstruct").Struct<{
         type: import("@metamask/snaps-sdk").NodeType.Row;
         label: string;
         variant?: "default" | "warning" | "critical" | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Input;
+        name: string;
+        value?: string | undefined;
+        label?: string | undefined;
+        inputType?: "number" | "text" | "password" | undefined;
+        placeholder?: string | undefined;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Button;
+        name?: string | undefined;
+        variant?: "primary" | "secondary" | undefined;
+        buttonType?: "button" | "submit" | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Form;
+        name: string;
+        children: ({
+            type: import("@metamask/snaps-sdk").NodeType.Input;
+            name: string;
+            value?: string | undefined;
+            label?: string | undefined;
+            inputType?: "number" | "text" | "password" | undefined;
+            placeholder?: string | undefined;
+        } | {
+            value: string;
+            type: import("@metamask/snaps-sdk").NodeType.Button;
+            name?: string | undefined;
+            variant?: "primary" | "secondary" | undefined;
+            buttonType?: "button" | "submit" | undefined;
+        })[];
     } | undefined, null>;
 }>;

package/dist/types/options.d.ts

@@ -1,41 +1,26 @@
 import type { Infer } from 'superstruct';
 declare const SnapsEnvironmentOptionsStruct: import("superstruct").Struct<{
-    keepAlive: boolean;
     server: {
         port: number;
-        root: string;
         enabled: boolean;
+        root: string;
     };
-    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;
+        root: string;
     }, {
         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": {
@@ -46,14 +31,6 @@ declare const SnapsEnvironmentOptionsStruct: import("superstruct").Struct<{
  *     }
  *   }
  * }
- * ```
- * @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`.
@@ -63,9 +40,6 @@ declare const SnapsEnvironmentOptionsStruct: import("superstruct").Struct<{
  * 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>;
 /**
@@ -77,16 +51,10 @@ export declare type SnapsEnvironmentOptions = Infer<typeof SnapsEnvironmentOptio
  * @returns The environment options.
  */
 export declare function getOptions(testEnvironmentOptions: Record<string, unknown>): {
-    keepAlive: boolean;
     server: {
         port: number;
-        root: string;
         enabled: boolean;
+        root: string;
     };
-    browser: {
-        headless: boolean;
-    };
-    executionEnvironmentUrl?: string | undefined;
-    simulatorUrl?: string | undefined;
 };
 export {};