w3wallets 0.10.2 → 1.0.0-beta.10

package/dist/index.d.ts

@@ -1,43 +1,159 @@
 import * as playwright_test from 'playwright/test';
 import { Page, test, BrowserContext } from '@playwright/test';
 
-/**
- * Represents the supported network types for the BackPack application.
- */
-type BackPackNetwork = "Solana" | "Eclipse" | "Ethereum" | "Polygon" | "Base" | "Arbitrum" | "Optimism";
-
-type WalletName = "backpack" | "polkadotJS" | "metamask";
-type NoDuplicates<T extends readonly unknown[], Acc extends readonly unknown[] = []> = T extends [infer Head, ...infer Tail] ? Head extends Acc[number] ? never : [Head, ...NoDuplicates<Tail, [...Acc, Head]>] : T;
 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;
+    /** Path to the extension's home page (e.g. "home.html"), used for cached wallets */
+    homeUrl?: 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 {
-    page: Page;
-    protected extensionId: string;
+    readonly page: Page;
+    readonly extensionId: string;
     constructor(page: Page, extensionId: string);
     abstract gotoOnboardPage(): Promise<void>;
+    abstract approve(): Promise<void>;
+    abstract deny(): Promise<void>;
+}
+
+interface NetworkSettings {
+    name: string;
+    rpc: string;
+    chainId: number;
+    currencySymbol: string;
 }
 
-declare class Backpack extends Wallet {
+declare class Metamask extends Wallet {
     private defaultPassword;
-    private currentAccountId;
-    private maxAccountId;
     gotoOnboardPage(): Promise<void>;
-    onboard(network: BackPackNetwork, privateKey: string): Promise<void>;
-    addAccount(network: BackPackNetwork, privateKey: string): Promise<void>;
     /**
-     * Switch account
-     * @param id The first added account has id 1, the second – 2, and so on
+     * 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>;
+    /**
+     * Dismiss MetaMask promotional popups (e.g., "Transaction Shield")
+     * that may overlay the confirmation UI.
+     */
+    dismissPopups(): Promise<void>;
+    private waitForPopupHidden;
+    /**
+     * After unlock, MetaMask may show onboarding screens, queued
+     * notifications, or go straight to the wallet UI. Race all possible
+     * states in a single wait to avoid sequential timeout penalties.
+     */
+    private stabilizePostUnlock;
+    /**
+     * Dismiss all queued MetaMask notifications (e.g., Solana/Tron account
+     * removal). These use the templated confirmation flow at #/confirmation/...
+     * If multiple are queued, "Reject all" appears; if only one, just
+     * confirmation-cancel-button is available.
      */
-    switchAccount(id: number): Promise<void>;
-    unlock(): Promise<void>;
-    setRPC(network: BackPackNetwork, rpc: string): Promise<void>;
-    ignoreAndProceed(): Promise<void>;
+    private dismissQueuedNotifications;
+    /**
+     * Wait for a target button while handling the Transaction Shield popup.
+     * Always navigates to sidepanel.html fresh so MetaMask's
+     * ConfirmationHandler can route to the pending approval.
+     */
+    private waitAndClickButton;
     approve(): Promise<void>;
     deny(): Promise<void>;
-    private _clickOnAccount;
-    private _importAccount;
+    /**
+     * Lock the MetaMask wallet
+     */
+    lock(): Promise<void>;
+    /**
+     * Unlock MetaMask with password.
+     * After unlocking, stabilizes the wallet UI by handling post-unlock
+     * screens (metametrics, onboarding completion) and dismissing queued
+     * notifications. Ends on home.html with the wallet UI ready.
+     */
+    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 {
@@ -52,41 +168,43 @@ declare class PolkadotJS extends Wallet {
     private _getLabeledInput;
 }
 
-type NetworkSettings = {
-    name: string;
-    rpc: string;
-    chainId: number;
-    currencySymbol: string;
-};
+/**
+ * Pre-built MetaMask wallet configuration.
+ */
+declare const metamask: WalletConfig<"metamask", Metamask>;
+/**
+ * Pre-built Polkadot.js wallet configuration.
+ */
+declare const polkadotJS: WalletConfig<"polkadotJS", PolkadotJS>;
 
-declare class Metamask extends Wallet {
-    private defaultPassword;
-    gotoOnboardPage(): Promise<void>;
+/**
+ * Configuration for w3wallets library.
+ * Values can be overridden via environment variables.
+ */
+declare const config: {
     /**
-     *
-     * @param mnemonic 12-word mnemonic seed phrase
+     * Timeout for actions like click, fill, waitFor, goto.
+     * Set via W3WALLETS_ACTION_TIMEOUT env variable.
+     * @default 30000 (30 seconds)
      */
-    onboard(mnemonic: string, password?: string): Promise<void>;
-    switchAccount(accountName: {
-        name: string;
-    }): Promise<void>;
-    importAccount(privateKey: string): Promise<void>;
-    addAccount(accountName?: string): Promise<void>;
-    getAccountName(): Promise<string>;
-    connectToNetwork(networkName: string, networkType?: "Popular" | "Custom"): Promise<void>;
-    addCustomNetwork(settings: NetworkSettings): Promise<void>;
-    enableTestNetworks(): Promise<void>;
-    approve(): Promise<void>;
-    deny(): Promise<void>;
-    private usingNotificationPage;
-    private clickTopRightCornerToCloseAllTheMarketingBullshit;
+    readonly actionTimeout: number | undefined;
+    /**
+     * Timeout for expect assertions like toBeVisible, toContainText.
+     * Set via W3WALLETS_EXPECT_TIMEOUT env variable.
+     * @default undefined (uses Playwright's default of 5000ms)
+     */
+    readonly expectTimeout: number | undefined;
+};
+
+declare function debug(message: string): void;
+
+type SetupFn<TWallet extends IWallet> = (wallet: TWallet, page: Page) => Promise<void>;
+interface CachedWalletConfig<TName extends string = string, TWallet extends IWallet = IWallet> extends WalletConfig<TName, TWallet> {
+    setupFn: SetupFn<TWallet>;
+    __cached: true;
 }
+declare function isCachedConfig(config: WalletConfig): config is CachedWalletConfig;
 
-declare function withWallets<T extends readonly WalletName[]>(test: typeof test, ...config: NoDuplicates<T>): playwright_test.TestType<playwright_test.PlaywrightTestArgs & playwright_test.PlaywrightTestOptions & {
-    context: BrowserContext;
-    backpack: Backpack;
-    polkadotJS: PolkadotJS;
-    metamask: Metamask;
-}, playwright_test.PlaywrightWorkerArgs & playwright_test.PlaywrightWorkerOptions>;
+declare function prepareWallet<TName extends string, TWallet extends IWallet>(walletConfig: WalletConfig<TName, TWallet>, setupFn: SetupFn<TWallet>): CachedWalletConfig<TName, TWallet>;
 
-export { withWallets };
+export { type CachedWalletConfig, type IWallet, Metamask, type Network, type NetworkSettings, PolkadotJS, type SetupFn, type WalletConfig, config, createWallet, debug, isCachedConfig, metamask, polkadotJS, prepareWallet, withWallets };