w3wallets 0.10.2 → 1.0.0-beta.10

package/README.md

@@ -15,21 +15,56 @@ npm install -D w3wallets
 
 ## Getting Started
 
-`MetaMask`, `Backpack`, and `Polkadot{.js}` wallets are currently supported.
+`MetaMask` and `Polkadot{.js}` wallets are currently supported.
 
 <p align="center">
   <img src="https://images.ctfassets.net/clixtyxoaeas/1ezuBGezqfIeifWdVtwU4c/d970d4cdf13b163efddddd5709164d2e/MetaMask-icon-Fox.svg" alt="Metamask Logo" width="60"/>
-  <img src="https://raw.githubusercontent.com/coral-xyz/backpack/refs/heads/master/assets/backpack.png" alt="Backpack Logo" width="60"/>
   <img src="https://polkadot.js.org/logo.svg" alt="Polkadot JS Logo" width="60"/>
 </p>
 
 #### 1. Download wallets
 
 ```sh
-npx w3wallets backpack polkadotJS
+npx w3wallets metamask polkadotjs
 ```
 
-The unzipped files should be stored in the `.w3wallets/<wallet-name>` directory. Add them to `.gitignore`.
+Short aliases are also supported:
+
+```sh
+npx w3wallets mm pjs
+```
+
+The unzipped files are stored in the `.w3wallets/<wallet-name>` directory. Add `.w3wallets` to `.gitignore`.
+
+<details>
+<summary>CLI Options</summary>
+
+```
+USAGE:
+  npx w3wallets [OPTIONS] <targets...>
+
+TARGETS:
+  Alias name      Known wallet alias (metamask, polkadotjs)
+  Short alias     Short form (mm, pjs)
+  Extension ID    32-character Chrome extension ID
+  URL             Chrome Web Store URL
+
+OPTIONS:
+  -h, --help      Show help message
+  -l, --list      List available wallet aliases
+  -o, --output    Output directory (default: .w3wallets)
+  -f, --force     Force re-download even if already exists
+  --debug         Save raw .crx file for debugging
+
+EXAMPLES:
+  npx w3wallets metamask                    # Download MetaMask
+  npx w3wallets mm pjs                      # Download all wallets (short)
+  npx w3wallets --list                      # List available aliases
+  npx w3wallets -o ./extensions metamask    # Custom output directory
+  npx w3wallets --force mm                  # Force re-download
+```
+
+</details>
 
 #### 2. Wrap your fixture with `withWallets`
 
@@ -37,20 +72,10 @@ Install the required wallets into Chromium using `withWallets`.
 
 ```ts
 // your-fixture.ts
-import { withWallets } from "w3wallets";
+import { withWallets, metamask, polkadotJS } from "w3wallets";
 import { test as base } from "@playwright/test";
 
-export const test = withWallets(
-  base,
-  "backpack",
-  "polkadotJS",
-).extend<BaseFixture>({
-  magic: (_, use) => use(42),
-});
-
-type BaseFixture = {
-  magic: number;
-};
+export const test = withWallets(base, metamask, polkadotJS);
 
 export { expect } from "@playwright/test";
 ```
@@ -64,12 +89,94 @@ Most commonly, you will use the following methods:
 3. `deny`: for actions that reject or cancel operations
 
 ```ts
-import { test } from "./your-fixture";
+import { test, expect } from "./your-fixture";
+
+test("Can connect MetaMask to dApp", async ({ page, metamask }) => {
+  const mnemonic =
+    "set your seed phrase test test test test test test test junk";
+
+  await metamask.onboard(mnemonic);
+  await page.goto("https://your-dapp.com");
+
+  await page.getByRole("button", { name: "Connect Wallet" }).click();
+  await metamask.approve();
+
+  await expect(page.getByText("Connected")).toBeVisible();
+});
+```
+
+## Caching
+
+Wallet onboarding can be slow. Caching lets you run the setup once and reuse the browser profile across tests.
+
+#### 1. Create a setup file
+
+Create a `*.cache.ts` file in a `wallets-cache/` directory (default):
+
+```ts
+// wallets-cache/default.cache.ts
+import { prepareWallet, metamask } from "w3wallets";
+
+export default prepareWallet(metamask, async (wallet, page) => {
+  await wallet.onboard("your seed phrase ...", "YourPassword123!");
+});
+```
+
+#### 2. Build the cache
+
+```sh
+npx w3wallets cache
+```
+
+<details>
+<summary>CLI Options</summary>
+
+```
+USAGE:
+  npx w3wallets cache [OPTIONS] [directory]
+
+OPTIONS:
+  -f, --force   Force rebuild even if cache exists
+  --headed      Run browser in headed mode
+  directory     Directory containing *.cache.{ts,js} files (default: ./wallets-cache/)
+```
+
+</details>
+
+The cached profiles are stored in `.w3wallets/cache/`. The `.w3wallets` directory should already be in `.gitignore`.
+
+#### 3. Use cached wallets in tests
+
+Import the setup and pass it to `withWallets`:
+
+```ts
+import { test as base, expect } from "@playwright/test";
+import { withWallets } from "w3wallets";
+import cachedMetamask from "./wallets-cache/default.cache";
 
-test("Can use wallet", async ({ page, backpack }) => {
-  const privateKey =
-    "4wDJd9Ds5ueTdS95ReAZGSBVkjMcNKbgZk47xcmqzpUJjCt7VoB2Cs7hqwXWRnopzXqE4mCP6BEDHCYrFttEcBw2";
+const test = withWallets(base, cachedMetamask);
 
-  await backpack.onboard("Eclipse", privateKey);
+test("wallet is ready", async ({ metamask }) => {
+  await metamask.unlock("YourPassword123!");
+  // wallet is already onboarded
 });
 ```
+
+> **Note:** All wallets in a test must be either all cached or all non-cached.
+
+## Configuration
+
+Configure library behavior via environment variables:
+
+| Variable                   | Description                                                               | Default     |
+| -------------------------- | ------------------------------------------------------------------------- | ----------- |
+| `W3WALLETS_ACTION_TIMEOUT` | Timeout (ms) for all wallet actions (click, fill, navigation, assertions) | `undefined` |
+
+Example:
+
+```sh
+# In .env or CI environment
+W3WALLETS_ACTION_TIMEOUT=60000
+```
+
+This only affects w3wallets library code. Your own Playwright configuration remains independent.

package/dist/index.d.mts

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