w3wallets/dist/index.d.mts

browser wallets for playwright

import * as playwright_test from 'playwright/test';
import { Page, test, BrowserContext } from '@playwright/test';

interface IWallet {
    readonly page: Page;
    gotoOnboardPage(): Promise<void>;
    approve(): Promise<void>;
    deny(): Promise<void>;
}
/**
 * Configuration object for a wallet.
 */
interface WalletConfig<TName extends string = string, TWallet extends IWallet = IWallet> {
    /** Unique wallet identifier, used as fixture name */
    name: TName;
    /** Directory name under .w3wallets/ where extension is stored */
    extensionDir: string;
    /** Wallet class constructor */
    WalletClass: new (page: Page, extensionId: string) => TWallet;
    /**
     * Chrome extension ID. If not provided, it will be derived from
     * the manifest.json `key` field. Required for custom extensions
     * that don't have a `key` field in their manifest.
     */
    extensionId?: string;
}
/**
 * Creates a wallet configuration object.
 *
 * @example
 * ```ts
 * const myWallet = createWallet({
 *   name: "myWallet",
 *   extensionDir: "my-wallet",
 *   WalletClass: MyWalletClass,
 * });
 * ```
 */
declare function createWallet<TName extends string, TWallet extends IWallet>(config: WalletConfig<TName, TWallet>): WalletConfig<TName, TWallet>;
/**
 * Extracts fixture name from a wallet config.
 */
type WalletConfigName<T> = T extends WalletConfig<infer N, IWallet> ? N : never;
/**
 * Extracts wallet class instance type from a wallet config.
 */
type WalletConfigInstance<T> = T extends WalletConfig<string, infer W> ? W : never;
/**
 * Builds fixture types from an array of wallet configs.
 */
type WalletFixturesFromConfigs<T extends readonly WalletConfig[]> = {
    [K in T[number] as WalletConfigName<K>]: WalletConfigInstance<K>;
};
/**
 * Supported blockchain networks.
 * Common networks are listed for autocomplete, but any string is accepted.
 */
type Network = "Solana" | "Eclipse" | "Ethereum" | "Polygon" | "Base" | "Arbitrum" | "Optimism" | (string & {});

/**
 * Extends Playwright test with wallet fixtures.
 *
 * @example
 * ```ts
 * import { withWallets, metamask, polkadotJS } from "w3wallets";
 *
 * const test = withWallets(base, metamask, polkadotJS);
 *
 * test("can connect", async ({ metamask, polkadotJS }) => {
 *   await metamask.onboard(mnemonic);
 * });
 * ```
 */
declare function withWallets<const T extends readonly WalletConfig[]>(test: typeof test, ...wallets: T): playwright_test.TestType<playwright_test.PlaywrightTestArgs & playwright_test.PlaywrightTestOptions & WalletFixturesFromConfigs<T> & {
    context: BrowserContext;
}, playwright_test.PlaywrightWorkerArgs & playwright_test.PlaywrightWorkerOptions>;

declare abstract class Wallet implements IWallet {
    readonly page: Page;
    protected readonly extensionId: string;
    constructor(page: Page, extensionId: string);
    abstract gotoOnboardPage(): Promise<void>;
    abstract approve(): Promise<void>;
    abstract deny(): Promise<void>;
}

type NetworkSettings = {
    name: string;
    rpc: string;
    chainId: number;
    currencySymbol: string;
};

declare class Metamask extends Wallet {
    private defaultPassword;
    gotoOnboardPage(): Promise<void>;
    /**
     * Onboard MetaMask with a mnemonic phrase
     * @param mnemonic - 12 or 24 word recovery phrase
     * @param password - Optional password (defaults to TestPassword123!)
     */
    onboard(mnemonic: string, password?: string): Promise<void>;
    approve(): Promise<void>;
    deny(): Promise<void>;
    /**
     * Lock the MetaMask wallet
     */
    lock(): Promise<void>;
    /**
     * Unlock MetaMask with password
     */
    unlock(password?: string): Promise<void>;
    /**
     * Switch to an existing network in MetaMask
     * @param networkName - Name of the network to switch to (e.g., "Ethereum Mainnet", "Sepolia")
     */
    switchNetwork(networkName: string, networkType?: "Popular" | "Custom"): Promise<void>;
    switchAccount(accountName: string): Promise<void>;
    /**
     * Add a custom network to MetaMask
     */
    addNetwork(network: NetworkSettings): Promise<void>;
    addCustomNetwork(settings: NetworkSettings): Promise<void>;
    enableTestNetworks(): Promise<void>;
    importAccount(privateKey: string): Promise<void>;
    accountNameIs(accountName: string): Promise<void>;
}

declare class PolkadotJS extends Wallet {
    private defaultPassword;
    gotoOnboardPage(): Promise<void>;
    onboard(seed: string, password?: string, name?: string): Promise<void>;
    selectAllAccounts(): Promise<void>;
    selectAccount(accountId: string): Promise<void>;
    enterPassword(password?: string): Promise<void>;
    approve(): Promise<void>;
    deny(): Promise<void>;
    private _getLabeledInput;
}

/**
 * Pre-built MetaMask wallet configuration.
 */
declare const metamask: WalletConfig<"metamask", Metamask>;
/**
 * Pre-built Polkadot.js wallet configuration.
 */
declare const polkadotJS: WalletConfig<"polkadotJS", PolkadotJS>;

/**
 * Configuration for w3wallets library.
 * Values can be overridden via environment variables.
 */
declare const config: {
    /**
     * Timeout for actions like click, fill, waitFor, goto.
     * Set via W3WALLETS_ACTION_TIMEOUT env variable.
     * @default 30000 (30 seconds)
     */
    readonly actionTimeout: number | undefined;
};

export { type IWallet, Metamask, type Network, type NetworkSettings, PolkadotJS, type WalletConfig, config, createWallet, metamask, polkadotJS, withWallets };