w3wallets 1.0.0-beta.1 → 1.0.0-beta.11

package/README.md

@@ -15,24 +15,23 @@ 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 metamask backpack polkadotjs
+npx w3wallets metamask polkadotjs
 ```
 
 Short aliases are also supported:
 
 ```sh
-npx w3wallets mm bp pjs
+npx w3wallets mm pjs
 ```
 
 The unzipped files are stored in the `.w3wallets/<wallet-name>` directory. Add `.w3wallets` to `.gitignore`.
@@ -45,8 +44,8 @@ USAGE:
   npx w3wallets [OPTIONS] <targets...>
 
 TARGETS:
-  Alias name      Known wallet alias (metamask, backpack, polkadotjs)
-  Short alias     Short form (mm, bp, pjs)
+  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
 
@@ -59,7 +58,7 @@ OPTIONS:
 
 EXAMPLES:
   npx w3wallets metamask                    # Download MetaMask
-  npx w3wallets mm bp pjs                   # Download all wallets (short)
+  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
@@ -73,10 +72,10 @@ Install the required wallets into Chromium using `withWallets`.
 
 ```ts
 // your-fixture.ts
-import { withWallets, metamask, backpack, polkadotJS } from "w3wallets";
+import { withWallets, metamask, polkadotJS } from "w3wallets";
 import { test as base } from "@playwright/test";
 
-export const test = withWallets(base, metamask, backpack, polkadotJS);
+export const test = withWallets(base, metamask, polkadotJS);
 
 export { expect } from "@playwright/test";
 ```
@@ -94,7 +93,7 @@ import { test, expect } from "./your-fixture";
 
 test("Can connect MetaMask to dApp", async ({ page, metamask }) => {
   const mnemonic =
-    "test test test test test test test test test test test junk";
+    "set your seed phrase test test test test test test test junk";
 
   await metamask.onboard(mnemonic);
   await page.goto("https://your-dapp.com");
@@ -105,3 +104,79 @@ test("Can connect MetaMask to dApp", async ({ page, metamask }) => {
   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";
+
+const test = withWallets(base, cachedMetamask);
+
+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

@@ -23,6 +23,8 @@ interface WalletConfig<TName extends string = string, TWallet extends IWallet =
      * 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.
@@ -62,11 +64,11 @@ type Network = "Solana" | "Eclipse" | "Ethereum" | "Polygon" | "Base" | "Arbitru
  *
  * @example
  * ```ts
- * import { withWallets, metamask, backpack } from "w3wallets";
+ * import { withWallets, metamask, polkadotJS } from "w3wallets";
  *
- * const test = withWallets(base, metamask, backpack);
+ * const test = withWallets(base, metamask, polkadotJS);
  *
- * test("can connect", async ({ metamask, backpack }) => {
+ * test("can connect", async ({ metamask, polkadotJS }) => {
  *   await metamask.onboard(mnemonic);
  * });
  * ```
@@ -77,40 +79,19 @@ declare function withWallets<const T extends readonly WalletConfig[]>(test: type
 
 declare abstract class Wallet implements IWallet {
     readonly page: Page;
-    protected readonly extensionId: string;
+    readonly extensionId: string;
     constructor(page: Page, extensionId: string);
     abstract gotoOnboardPage(): Promise<void>;
     abstract approve(): Promise<void>;
     abstract deny(): Promise<void>;
 }
 
-declare class Backpack extends Wallet {
-    private defaultPassword;
-    private currentAccountId;
-    private maxAccountId;
-    gotoOnboardPage(): Promise<void>;
-    onboard(network: Network, privateKey: string): Promise<void>;
-    addAccount(network: Network, privateKey: string): Promise<void>;
-    /**
-     * Switch account
-     * @param id The first added account has id 1, the second – 2, and so on
-     */
-    switchAccount(id: number): Promise<void>;
-    unlock(): Promise<void>;
-    setRPC(network: Network, rpc: string): Promise<void>;
-    ignoreAndProceed(): Promise<void>;
-    approve(): Promise<void>;
-    deny(): Promise<void>;
-    private _clickOnAccount;
-    private _importAccount;
-}
-
-type NetworkSettings = {
+interface NetworkSettings {
     name: string;
     rpc: string;
     chainId: number;
     currencySymbol: string;
-};
+}
 
 declare class Metamask extends Wallet {
     private defaultPassword;
@@ -121,6 +102,38 @@ declare class Metamask extends Wallet {
      * @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;
+    /**
+     * MetaMask's MV3 service worker can fail to come up on cold-start
+     * (especially in fresh-extension CI runs), showing an error screen
+     * with a "Restart MetaMask" button. Detect and click it so the
+     * normal post-unlock flow can proceed.
+     */
+    private recoverFromStartupError;
+    /**
+     * 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.
+     */
+    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>;
     /**
@@ -128,7 +141,10 @@ declare class Metamask extends Wallet {
      */
     lock(): Promise<void>;
     /**
-     * Unlock MetaMask with password
+     * 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>;
     /**
@@ -159,10 +175,6 @@ declare class PolkadotJS extends Wallet {
     private _getLabeledInput;
 }
 
-/**
- * Pre-built Backpack wallet configuration.
- */
-declare const backpack: WalletConfig<"backpack", Backpack>;
 /**
  * Pre-built MetaMask wallet configuration.
  */
@@ -172,4 +184,34 @@ declare const metamask: WalletConfig<"metamask", Metamask>;
  */
 declare const polkadotJS: WalletConfig<"polkadotJS", PolkadotJS>;
 
-export { Backpack, type IWallet, Metamask, type Network, type NetworkSettings, PolkadotJS, type WalletConfig, backpack, createWallet, metamask, polkadotJS, withWallets };
+/**
+ * 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;
+    /**
+     * 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 prepareWallet<TName extends string, TWallet extends IWallet>(walletConfig: WalletConfig<TName, TWallet>, setupFn: SetupFn<TWallet>): CachedWalletConfig<TName, TWallet>;
+
+export { type CachedWalletConfig, type IWallet, Metamask, type Network, type NetworkSettings, PolkadotJS, type SetupFn, type WalletConfig, config, createWallet, debug, isCachedConfig, metamask, polkadotJS, prepareWallet, withWallets };

package/dist/index.d.ts

@@ -23,6 +23,8 @@ interface WalletConfig<TName extends string = string, TWallet extends IWallet =
      * 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.
@@ -62,11 +64,11 @@ type Network = "Solana" | "Eclipse" | "Ethereum" | "Polygon" | "Base" | "Arbitru
  *
  * @example
  * ```ts
- * import { withWallets, metamask, backpack } from "w3wallets";
+ * import { withWallets, metamask, polkadotJS } from "w3wallets";
  *
- * const test = withWallets(base, metamask, backpack);
+ * const test = withWallets(base, metamask, polkadotJS);
  *
- * test("can connect", async ({ metamask, backpack }) => {
+ * test("can connect", async ({ metamask, polkadotJS }) => {
  *   await metamask.onboard(mnemonic);
  * });
  * ```
@@ -77,40 +79,19 @@ declare function withWallets<const T extends readonly WalletConfig[]>(test: type
 
 declare abstract class Wallet implements IWallet {
     readonly page: Page;
-    protected readonly extensionId: string;
+    readonly extensionId: string;
     constructor(page: Page, extensionId: string);
     abstract gotoOnboardPage(): Promise<void>;
     abstract approve(): Promise<void>;
     abstract deny(): Promise<void>;
 }
 
-declare class Backpack extends Wallet {
-    private defaultPassword;
-    private currentAccountId;
-    private maxAccountId;
-    gotoOnboardPage(): Promise<void>;
-    onboard(network: Network, privateKey: string): Promise<void>;
-    addAccount(network: Network, privateKey: string): Promise<void>;
-    /**
-     * Switch account
-     * @param id The first added account has id 1, the second – 2, and so on
-     */
-    switchAccount(id: number): Promise<void>;
-    unlock(): Promise<void>;
-    setRPC(network: Network, rpc: string): Promise<void>;
-    ignoreAndProceed(): Promise<void>;
-    approve(): Promise<void>;
-    deny(): Promise<void>;
-    private _clickOnAccount;
-    private _importAccount;
-}
-
-type NetworkSettings = {
+interface NetworkSettings {
     name: string;
     rpc: string;
     chainId: number;
     currencySymbol: string;
-};
+}
 
 declare class Metamask extends Wallet {
     private defaultPassword;
@@ -121,6 +102,38 @@ declare class Metamask extends Wallet {
      * @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;
+    /**
+     * MetaMask's MV3 service worker can fail to come up on cold-start
+     * (especially in fresh-extension CI runs), showing an error screen
+     * with a "Restart MetaMask" button. Detect and click it so the
+     * normal post-unlock flow can proceed.
+     */
+    private recoverFromStartupError;
+    /**
+     * 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.
+     */
+    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>;
     /**
@@ -128,7 +141,10 @@ declare class Metamask extends Wallet {
      */
     lock(): Promise<void>;
     /**
-     * Unlock MetaMask with password
+     * 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>;
     /**
@@ -159,10 +175,6 @@ declare class PolkadotJS extends Wallet {
     private _getLabeledInput;
 }
 
-/**
- * Pre-built Backpack wallet configuration.
- */
-declare const backpack: WalletConfig<"backpack", Backpack>;
 /**
  * Pre-built MetaMask wallet configuration.
  */
@@ -172,4 +184,34 @@ declare const metamask: WalletConfig<"metamask", Metamask>;
  */
 declare const polkadotJS: WalletConfig<"polkadotJS", PolkadotJS>;
 
-export { Backpack, type IWallet, Metamask, type Network, type NetworkSettings, PolkadotJS, type WalletConfig, backpack, createWallet, metamask, polkadotJS, withWallets };
+/**
+ * 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;
+    /**
+     * 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 prepareWallet<TName extends string, TWallet extends IWallet>(walletConfig: WalletConfig<TName, TWallet>, setupFn: SetupFn<TWallet>): CachedWalletConfig<TName, TWallet>;
+
+export { type CachedWalletConfig, type IWallet, Metamask, type Network, type NetworkSettings, PolkadotJS, type SetupFn, type WalletConfig, config, createWallet, debug, isCachedConfig, metamask, polkadotJS, prepareWallet, withWallets };