w3wallets 0.10.2 → 1.0.0-beta.1

package/README.md

@@ -26,10 +26,46 @@ npm install -D w3wallets
 #### 1. Download wallets
 
 ```sh
-npx w3wallets backpack polkadotJS
+npx w3wallets metamask backpack 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 bp 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, backpack, polkadotjs)
+  Short alias     Short form (mm, bp, 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 bp 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 +73,10 @@ Install the required wallets into Chromium using `withWallets`.
 
 ```ts
 // your-fixture.ts
-import { withWallets } from "w3wallets";
+import { withWallets, metamask, backpack, 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, backpack, polkadotJS);
 
 export { expect } from "@playwright/test";
 ```
@@ -64,12 +90,18 @@ 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 =
+    "test test test test test test test test test test test junk";
+
+  await metamask.onboard(mnemonic);
+  await page.goto("https://your-dapp.com");
 
-test("Can use wallet", async ({ page, backpack }) => {
-  const privateKey =
-    "4wDJd9Ds5ueTdS95ReAZGSBVkjMcNKbgZk47xcmqzpUJjCt7VoB2Cs7hqwXWRnopzXqE4mCP6BEDHCYrFttEcBw2";
+  await page.getByRole("button", { name: "Connect Wallet" }).click();
+  await metamask.approve();
 
-  await backpack.onboard("Eclipse", privateKey);
+  await expect(page.getByText("Connected")).toBeVisible();
 });
 ```

package/dist/index.d.mts

@@ -1,22 +1,87 @@
 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;
+}
+/**
+ * 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, backpack } from "w3wallets";
+ *
+ * const test = withWallets(base, metamask, backpack);
+ *
+ * test("can connect", async ({ metamask, backpack }) => {
+ *   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;
+    protected 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 {
@@ -24,15 +89,15 @@ declare class Backpack extends Wallet {
     private currentAccountId;
     private maxAccountId;
     gotoOnboardPage(): Promise<void>;
-    onboard(network: BackPackNetwork, privateKey: string): Promise<void>;
-    addAccount(network: BackPackNetwork, privateKey: string): 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: BackPackNetwork, rpc: string): Promise<void>;
+    setRPC(network: Network, rpc: string): Promise<void>;
     ignoreAndProceed(): Promise<void>;
     approve(): Promise<void>;
     deny(): Promise<void>;
@@ -40,18 +105,6 @@ declare class Backpack extends Wallet {
     private _importAccount;
 }
 
-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;
-}
-
 type NetworkSettings = {
     name: string;
     rpc: string;
@@ -63,30 +116,60 @@ declare class Metamask extends Wallet {
     private defaultPassword;
     gotoOnboardPage(): Promise<void>;
     /**
-     *
-     * @param mnemonic 12-word mnemonic seed phrase
+     * 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>;
-    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>;
+    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 usingNotificationPage;
-    private clickTopRightCornerToCloseAllTheMarketingBullshit;
+    private _getLabeledInput;
 }
 
-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>;
+/**
+ * Pre-built Backpack wallet configuration.
+ */
+declare const backpack: WalletConfig<"backpack", Backpack>;
+/**
+ * Pre-built MetaMask wallet configuration.
+ */
+declare const metamask: WalletConfig<"metamask", Metamask>;
+/**
+ * Pre-built Polkadot.js wallet configuration.
+ */
+declare const polkadotJS: WalletConfig<"polkadotJS", PolkadotJS>;
 
-export { withWallets };
+export { Backpack, type IWallet, Metamask, type Network, type NetworkSettings, PolkadotJS, type WalletConfig, backpack, createWallet, metamask, polkadotJS, withWallets };

package/dist/index.d.ts

@@ -1,22 +1,87 @@
 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;
+}
+/**
+ * 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, backpack } from "w3wallets";
+ *
+ * const test = withWallets(base, metamask, backpack);
+ *
+ * test("can connect", async ({ metamask, backpack }) => {
+ *   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;
+    protected 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 {
@@ -24,15 +89,15 @@ declare class Backpack extends Wallet {
     private currentAccountId;
     private maxAccountId;
     gotoOnboardPage(): Promise<void>;
-    onboard(network: BackPackNetwork, privateKey: string): Promise<void>;
-    addAccount(network: BackPackNetwork, privateKey: string): 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: BackPackNetwork, rpc: string): Promise<void>;
+    setRPC(network: Network, rpc: string): Promise<void>;
     ignoreAndProceed(): Promise<void>;
     approve(): Promise<void>;
     deny(): Promise<void>;
@@ -40,18 +105,6 @@ declare class Backpack extends Wallet {
     private _importAccount;
 }
 
-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;
-}
-
 type NetworkSettings = {
     name: string;
     rpc: string;
@@ -63,30 +116,60 @@ declare class Metamask extends Wallet {
     private defaultPassword;
     gotoOnboardPage(): Promise<void>;
     /**
-     *
-     * @param mnemonic 12-word mnemonic seed phrase
+     * 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>;
-    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>;
+    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 usingNotificationPage;
-    private clickTopRightCornerToCloseAllTheMarketingBullshit;
+    private _getLabeledInput;
 }
 
-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>;
+/**
+ * Pre-built Backpack wallet configuration.
+ */
+declare const backpack: WalletConfig<"backpack", Backpack>;
+/**
+ * Pre-built MetaMask wallet configuration.
+ */
+declare const metamask: WalletConfig<"metamask", Metamask>;
+/**
+ * Pre-built Polkadot.js wallet configuration.
+ */
+declare const polkadotJS: WalletConfig<"polkadotJS", PolkadotJS>;
 
-export { withWallets };
+export { Backpack, type IWallet, Metamask, type Network, type NetworkSettings, PolkadotJS, type WalletConfig, backpack, createWallet, metamask, polkadotJS, withWallets };