@avalix/chroma 0.0.14 → 0.0.16

package/README.md

@@ -22,7 +22,7 @@ Before running your tests, you need to download the wallet extensions:
 npx chroma download-extensions
 ```
 
-This will download the wallet extensions (Polkadot JS and Talisman) to `./.chroma` directory in your project root.
+This will download the wallet extensions (e.g. MetaMask, Polkadot JS, Talisman) to `./.chroma` directory in your project root.
 
 **Tip**: Add this to your `package.json` scripts for convenience:
 
@@ -42,24 +42,22 @@ This will download the wallet extensions (Polkadot JS and Talisman) to `./.chrom
 import { createWalletTest, expect } from '@avalix/chroma'
 
 const test = createWalletTest({
-  wallets: [{ type: 'polkadot-js' }]
+  wallets: [{ type: 'metamask' }]
 })
 
 test('connect wallet and sign transaction', async ({ page, wallets }) => {
-  const polkadotJs = wallets['polkadot-js']
+  const metamask = wallets.metamask
 
-  await polkadotJs.importMnemonic({
-    seed: 'bottom drive obey lake curtain smoke basket hold race lonely fit walk',
-    name: 'Test Account',
-    password: 'securePassword123'
+  await metamask.importSeedPhrase({
+    seedPhrase: 'test test test test test test test test test test test junk'
   })
 
   await page.goto('http://localhost:3000')
   await page.click('button:has-text("Connect Wallet")')
-  await polkadotJs.authorize()
+  await metamask.authorize()
 
   await page.click('button:has-text("Send Transaction")')
-  await polkadotJs.approveTx({ password: 'securePassword123' })
+  await metamask.confirm()
 
   await expect(page.locator('.transaction-success')).toBeVisible()
 })
@@ -71,40 +69,21 @@ test('connect wallet and sign transaction', async ({ page, wallets }) => {
 import { createWalletTest } from '@avalix/chroma'
 
 const test = createWalletTest({
-  wallets: [{ type: 'polkadot-js' }, { type: 'talisman' }]
+  wallets: [{ type: 'metamask' }, { type: 'talisman' }]
 })
 
 test('multi-wallet test', async ({ page, wallets }) => {
-  const polkadotJs = wallets['polkadot-js']
+  const metamask = wallets.metamask
   const talisman = wallets.talisman
 
-  await polkadotJs.importMnemonic({ seed: '...', name: 'Alice' })
+  await metamask.importSeedPhrase({ seedPhrase: 'test test test test test test test test test test test junk' })
   await talisman.importEthPrivateKey({ privateKey: '0x...', name: 'Bob' })
 
   await page.goto('http://localhost:3000')
-  await polkadotJs.authorize()
+  await metamask.authorize()
 })
 ```
 
-## Supported Wallets & Chains
-
-### Supported Chains
-
-| Chain | Status |
-|-------|--------|
-| Polkadot | ✅ Supported |
-| Ethereum | ✅ Supported |
-| Solana | ⏳ Planned |
-
-### Supported Wallets
-
-| Wallet | Status | Version |
-|--------|--------|---------|
-| Polkadot JS Extension | ✅ Supported | v0.62.6 |
-| Talisman | ✅ Supported | v3.1.13 |
-| SubWallet | ⏳ Planned | - |
-| MetaMask | ⏳ Planned | - |
-
 ## Features
 
 - **Easy Extension Setup** - Download wallet extensions with a single command

package/dist/index.d.mts

@@ -9949,11 +9949,23 @@ declare function createTalismanWallet(extensionId: string, context: BrowserConte
   approveTx: () => Promise<void>;
   rejectTx: () => Promise<void>;
 };
+declare function createMetaMaskWallet(extensionId: string, context: BrowserContext): {
+  extensionId: string;
+  type: "metamask";
+  importSeedPhrase: (options: {
+    seedPhrase: string;
+  }) => Promise<void>;
+  unlock: () => Promise<void>;
+  authorize: () => Promise<void>;
+  reject: () => Promise<void>;
+  confirm: () => Promise<void>;
+};
 type PolkadotJsWalletInstance = ReturnType<typeof createPolkadotJsWallet>;
 type TalismanWalletInstance = ReturnType<typeof createTalismanWallet>;
+type MetaMaskWalletInstance = ReturnType<typeof createMetaMaskWallet>;
 //#endregion
 //#region src/context-playwright/types.d.ts
-type WalletType = 'polkadot-js' | 'talisman';
+type WalletType = 'polkadot-js' | 'talisman' | 'metamask';
 interface WalletAccount {
   seed: string;
   name?: string;
@@ -9966,6 +9978,7 @@ interface WalletConfig {
 interface WalletTypeMap {
   'polkadot-js': PolkadotJsWalletInstance;
   'talisman': TalismanWalletInstance;
+  'metamask': MetaMaskWalletInstance;
 }
 type Wallets = WalletTypeMap;
 type ConfiguredWallets<T extends readonly WalletConfig[]> = { [K in T[number]['type']]: WalletTypeMap[K] };

package/dist/index.mjs

@@ -3,6 +3,129 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 
+//#region src/wallets/metamask.ts
+const VERSION$2 = "13.17.0";
+const METAMASK_CONFIG = {
+	downloadUrl: `https://github.com/MetaMask/metamask-extension/releases/download/v${VERSION$2}/metamask-flask-chrome-${VERSION$2}-flask.0.zip`,
+	extensionName: `metamask-extension-${VERSION$2}`
+};
+async function getMetaMaskExtensionPath() {
+	const extensionsDir = path.resolve(process.cwd(), ".chroma");
+	const extensionDir = path.join(extensionsDir, METAMASK_CONFIG.extensionName);
+	if (!fs.existsSync(extensionDir) || fs.readdirSync(extensionDir).length === 0) throw new Error(`MetaMask extension not found at: ${extensionDir}\n\nPlease download the extension first by running:\n  npx @avalix/chroma download-extensions\n`);
+	return extensionDir;
+}
+/* c8 ignore start */
+async function findOnboardingPage$1(context, extensionId) {
+	const maxAttempts = 10;
+	const retryDelay = 500;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		const pages = context.pages();
+		for (const p of pages) if (p.url().includes(`chrome-extension://${extensionId}/`)) {
+			await p.waitForLoadState("domcontentloaded");
+			await p.getByText("I accept the risks").click();
+			return p;
+		}
+		if (attempt < maxAttempts - 1) await new Promise((resolve) => setTimeout(resolve, retryDelay));
+	}
+	throw new Error(`MetaMask extension page not found for ID: ${extensionId}`);
+}
+async function findExtensionPopup$2(context, extensionId) {
+	const maxAttempts = 10;
+	const retryDelay = 500;
+	const page0 = context.pages()[0];
+	if (!page0) throw new Error("No pages available to create CDP session");
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		const client = await context.newCDPSession(page0);
+		const { targetInfos } = await client.send("Target.getTargets");
+		const sidePanelTarget = targetInfos.find((t) => t.url.includes(`chrome-extension://${extensionId}/`) && t.url.includes("sidepanel"));
+		await client.detach();
+		if (sidePanelTarget) {
+			const sidePanelPage = await context.newPage();
+			await sidePanelPage.goto(sidePanelTarget.url);
+			await sidePanelPage.waitForLoadState("domcontentloaded");
+			return sidePanelPage;
+		}
+		if (attempt < maxAttempts - 1) await new Promise((resolve) => setTimeout(resolve, retryDelay));
+	}
+	throw new Error(`MetaMask side panel not found for ID: ${extensionId}`);
+}
+const METAMASK_PASSWORD = "h3llop0lkadot!";
+async function completeOnboarding$1(extensionPage, seedPhrase) {
+	await extensionPage.bringToFront();
+	await extensionPage.waitForLoadState("domcontentloaded");
+	await extensionPage.getByTestId("onboarding-import-wallet").click();
+	await extensionPage.getByTestId("onboarding-import-with-srp-button").click();
+	await extensionPage.getByTestId("srp-input-import__srp-note").pressSequentially(seedPhrase, { delay: 50 });
+	await extensionPage.getByTestId("import-srp-confirm").click();
+	await extensionPage.getByTestId("create-password-new-input").fill(METAMASK_PASSWORD);
+	await extensionPage.getByTestId("create-password-confirm-input").fill(METAMASK_PASSWORD);
+	await extensionPage.getByTestId("create-password-terms").click();
+	await extensionPage.getByTestId("create-password-submit").click();
+	await extensionPage.getByTestId("metametrics-checkbox").click();
+	await extensionPage.getByTestId("metametrics-i-agree").click();
+	await extensionPage.getByTestId("manage-default-settings").click();
+	await extensionPage.getByTestId("category-item-General").click();
+	await extensionPage.getByTestId("basic-functionality-toggle").locator(".toggle-button").click();
+	await extensionPage.getByText("I understand and want to continue").click();
+	await extensionPage.getByTestId("basic-configuration-modal-toggle-button").click();
+	await extensionPage.getByTestId("category-back-button").click();
+	await extensionPage.getByTestId("category-item-Assets").click();
+	await extensionPage.getByTestId("privacy-settings-settings").locator(".toggle-button").nth(0).click();
+	await extensionPage.getByTestId("privacy-settings-settings").locator(".toggle-button").nth(1).click();
+	await extensionPage.getByTestId("privacy-settings-settings").locator(".toggle-button").nth(2).click();
+	await extensionPage.getByTestId("privacy-settings-settings").locator(".toggle-button").nth(3).click();
+	await extensionPage.getByTestId("privacy-settings-settings").locator(".toggle-button").nth(4).click();
+	await extensionPage.getByTestId("category-back-button").click();
+	await extensionPage.getByTestId("privacy-settings-back-button").click();
+	await extensionPage.getByTestId("onboarding-complete-done").click();
+	await extensionPage.close();
+}
+async function authorizeMetaMask(page) {
+	const context = page.__extensionContext;
+	const extensionId = page.__extensionId;
+	const extensionPopup = await findExtensionPopup$2(context, extensionId);
+	await extensionPopup.getByTestId("confirm-btn").click();
+	await extensionPopup.close();
+}
+async function confirmMetaMask(page) {
+	const context = page.__extensionContext;
+	const extensionId = page.__extensionId;
+	const extensionPopup = await findExtensionPopup$2(context, extensionId);
+	await extensionPopup.getByTestId("confirm-footer-button").click();
+	await extensionPopup.close();
+}
+async function rejectMetaMask(page) {
+	const context = page.__extensionContext;
+	const extensionId = page.__extensionId;
+	const extensionPopup = await findExtensionPopup$2(context, extensionId);
+	await extensionPopup.getByTestId("confirm-footer-cancel").or(extensionPopup.getByTestId("page-container-footer-cancel")).or(extensionPopup.getByRole("button", { name: /Reject|Cancel/i })).first().click();
+	await extensionPopup.close();
+}
+async function unlockMetaMask(page) {
+	const context = page.__extensionContext;
+	const unlockUrl = `chrome-extension://${page.__extensionId}/home.html#/onboarding/unlock`;
+	const unlockPage = await context.newPage();
+	await unlockPage.goto(unlockUrl);
+	await unlockPage.waitForLoadState("domcontentloaded");
+	await unlockPage.getByTestId("unlock-password").fill(METAMASK_PASSWORD);
+	await unlockPage.getByTestId("unlock-submit").click();
+	await unlockPage.close();
+}
+async function importSeedPhrase(page, { seedPhrase }) {
+	const context = page.__extensionContext;
+	const extensionId = page.__extensionId;
+	const extensionPage = await findOnboardingPage$1(context, extensionId);
+	try {
+		await completeOnboarding$1(extensionPage, seedPhrase);
+	} catch (error) {
+		console.error("❌ Error during MetaMask Ethereum account import:", error);
+		throw error;
+	}
+}
+/* c8 ignore stop */
+
+//#endregion
 //#region src/wallets/polkadot-js.ts
 const VERSION$1 = "0.62.6";
 const POLKADOT_JS_CONFIG = {
@@ -79,7 +202,7 @@ async function rejectPolkadotJSTx(page) {
 
 //#endregion
 //#region src/wallets/talisman.ts
-const VERSION = "3.1.13";
+const VERSION = "3.2.0";
 const TALISMAN_CONFIG = {
 	downloadUrl: `https://github.com/avalix-labs/polkadot-wallets/raw/refs/heads/main/talisman/talisman-${VERSION}.zip`,
 	extensionName: `talisman-extension-${VERSION}`
@@ -272,9 +395,33 @@ function createTalismanWallet(extensionId, context) {
 	};
 }
 /* c8 ignore stop */
+/* c8 ignore start */
+function createMetaMaskWallet(extensionId, context) {
+	return {
+		extensionId,
+		type: "metamask",
+		importSeedPhrase: async (options) => {
+			await importSeedPhrase(createExtendedPage(context.pages()[0] || await context.newPage(), context, extensionId), { seedPhrase: options.seedPhrase });
+		},
+		unlock: async () => {
+			await unlockMetaMask(createExtendedPage(context.pages()[0] || await context.newPage(), context, extensionId));
+		},
+		authorize: async () => {
+			await authorizeMetaMask(createExtendedPage(context.pages()[0] || await context.newPage(), context, extensionId));
+		},
+		reject: async () => {
+			await rejectMetaMask(createExtendedPage(context.pages()[0] || await context.newPage(), context, extensionId));
+		},
+		confirm: async () => {
+			await confirmMetaMask(createExtendedPage(context.pages()[0] || await context.newPage(), context, extensionId));
+		}
+	};
+}
+/* c8 ignore stop */
 const walletFactories = {
 	"polkadot-js": createPolkadotJsWallet,
-	"talisman": createTalismanWallet
+	"talisman": createTalismanWallet,
+	"metamask": createMetaMaskWallet
 };
 
 //#endregion
@@ -284,6 +431,7 @@ async function getExtensionPathForWallet(config) {
 	switch (type) {
 		case "polkadot-js": return await getPolkadotJSExtensionPath();
 		case "talisman": return await getTalismanExtensionPath();
+		case "metamask": return await getMetaMaskExtensionPath();
 		default: throw new Error(`Unsupported wallet type: ${type}`);
 	}
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@avalix/chroma",
   "type": "module",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "End-to-end testing library for Polkadot wallet interactions",
   "author": "Avalix Labs",
   "license": "MIT",

package/scripts/download-extensions.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { downloadAndExtractExtension } from '../src/utils/download-extension.js'
+import { METAMASK_CONFIG } from '../src/wallets/metamask.js'
 import { POLKADOT_JS_CONFIG } from '../src/wallets/polkadot-js.js'
 import { TALISMAN_CONFIG } from '../src/wallets/talisman.js'
 
@@ -45,6 +46,12 @@ async function main() {
       extensionName: TALISMAN_CONFIG.extensionName,
     })
 
+    // Download MetaMask extension
+    await downloadAndExtractExtension({
+      downloadUrl: METAMASK_CONFIG.downloadUrl,
+      extensionName: METAMASK_CONFIG.extensionName,
+    })
+
     console.log('\n✅ All extensions downloaded successfully!')
     console.log('You can now run your Playwright tests.')
   }

package/src/context-playwright/index.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getMetaMaskExtensionPath } from '../wallets/metamask.js'
 import { getPolkadotJSExtensionPath } from '../wallets/polkadot-js.js'
 import { getTalismanExtensionPath } from '../wallets/talisman.js'
 import { createWalletTest, getExtensionPathForWallet } from './index.js'
@@ -29,11 +30,16 @@ vi.mock('../wallets/talisman.js', () => ({
   getTalismanExtensionPath: vi.fn().mockResolvedValue('/mock/path/talisman-extension'),
 }))
 
+vi.mock('../wallets/metamask.js', () => ({
+  getMetaMaskExtensionPath: vi.fn().mockResolvedValue('/mock/path/metamask-extension'),
+}))
+
 // Mock wallet factories
 vi.mock('./wallet-factory.js', () => ({
   walletFactories: {
     'polkadot-js': vi.fn().mockReturnValue({ type: 'polkadot-js' }),
     'talisman': vi.fn().mockReturnValue({ type: 'talisman' }),
+    'metamask': vi.fn().mockReturnValue({ type: 'metamask' }),
   },
 }))
 
@@ -139,6 +145,13 @@ describe('context-playwright/index', () => {
       expect(getTalismanExtensionPath).toHaveBeenCalled()
     })
 
+    it('should return metamask extension path', async () => {
+      const result = await getExtensionPathForWallet({ type: 'metamask' })
+
+      expect(result).toBe('/mock/path/metamask-extension')
+      expect(getMetaMaskExtensionPath).toHaveBeenCalled()
+    })
+
     it('should throw error for unsupported wallet type', async () => {
       await expect(
         getExtensionPathForWallet({ type: 'unsupported' as any }),

package/src/context-playwright/index.ts

@@ -8,6 +8,7 @@ import type {
   WalletWorkerFixtures,
 } from './types.js'
 import { test as base, chromium } from '@playwright/test'
+import { getMetaMaskExtensionPath } from '../wallets/metamask.js'
 import { getPolkadotJSExtensionPath } from '../wallets/polkadot-js.js'
 import { getTalismanExtensionPath } from '../wallets/talisman.js'
 import { walletFactories } from './wallet-factory.js'
@@ -21,6 +22,8 @@ export async function getExtensionPathForWallet(config: WalletConfig): Promise<s
       return await getPolkadotJSExtensionPath()
     case 'talisman':
       return await getTalismanExtensionPath()
+    case 'metamask':
+      return await getMetaMaskExtensionPath()
     default:
       throw new Error(`Unsupported wallet type: ${type}`)
   }

package/src/context-playwright/types.ts

@@ -1,15 +1,16 @@
 import type { BrowserContext, Page } from '@playwright/test'
 import type {
+  MetaMaskWalletInstance,
   PolkadotJsWalletInstance,
   TalismanWalletInstance,
   WalletInstance,
 } from './wallet-factory.js'
 
 // Re-export wallet instance types
-export type { PolkadotJsWalletInstance, TalismanWalletInstance, WalletInstance }
+export type { MetaMaskWalletInstance, PolkadotJsWalletInstance, TalismanWalletInstance, WalletInstance }
 
 // Wallet types - single source of truth
-export type WalletType = 'polkadot-js' | 'talisman'
+export type WalletType = 'polkadot-js' | 'talisman' | 'metamask'
 
 // Wallet account configuration
 export interface WalletAccount {
@@ -28,6 +29,7 @@ export interface WalletConfig {
 export interface WalletTypeMap {
   'polkadot-js': PolkadotJsWalletInstance
   'talisman': TalismanWalletInstance
+  'metamask': MetaMaskWalletInstance
 }
 
 // Wallets collection - all wallet types

package/src/context-playwright/wallet-factory.ts

@@ -1,5 +1,12 @@
 import type { BrowserContext, Page } from '@playwright/test'
 import type { WalletAccount } from './types.js'
+import {
+  authorizeMetaMask,
+  confirmMetaMask,
+  importSeedPhrase as importMetaMaskSeedPhrase,
+  rejectMetaMask,
+  unlockMetaMask,
+} from '../wallets/metamask.js'
 import {
   approvePolkadotJSTx,
   authorizePolkadotJS,
@@ -104,13 +111,53 @@ export function createTalismanWallet(extensionId: string, context: BrowserContex
 }
 /* c8 ignore stop */
 
+/*
+ * Factory function for MetaMask wallet
+ * Coverage excluded: methods interact with Chrome extension APIs via browser context.
+ */
+/* c8 ignore start */
+export function createMetaMaskWallet(extensionId: string, context: BrowserContext) {
+  return {
+    extensionId,
+    type: 'metamask' as const,
+    importSeedPhrase: async (options: { seedPhrase: string }) => {
+      const page = context.pages()[0] || await context.newPage()
+      const extPage = createExtendedPage(page, context, extensionId)
+      await importMetaMaskSeedPhrase(extPage, { seedPhrase: options.seedPhrase })
+    },
+    unlock: async () => {
+      const page = context.pages()[0] || await context.newPage()
+      const extPage = createExtendedPage(page, context, extensionId)
+      await unlockMetaMask(extPage)
+    },
+    authorize: async () => {
+      const page = context.pages()[0] || await context.newPage()
+      const extPage = createExtendedPage(page, context, extensionId)
+      await authorizeMetaMask(extPage)
+    },
+    reject: async () => {
+      const page = context.pages()[0] || await context.newPage()
+      const extPage = createExtendedPage(page, context, extensionId)
+      await rejectMetaMask(extPage)
+    },
+    confirm: async () => {
+      const page = context.pages()[0] || await context.newPage()
+      const extPage = createExtendedPage(page, context, extensionId)
+      await confirmMetaMask(extPage)
+    },
+  }
+}
+/* c8 ignore stop */
+
 // Wallet factories map - auto-inferred types
 export const walletFactories = {
   'polkadot-js': createPolkadotJsWallet,
   'talisman': createTalismanWallet,
+  'metamask': createMetaMaskWallet,
 }
 
 // Auto-inferred types from factory functions
 export type PolkadotJsWalletInstance = ReturnType<typeof createPolkadotJsWallet>
 export type TalismanWalletInstance = ReturnType<typeof createTalismanWallet>
-export type WalletInstance = PolkadotJsWalletInstance | TalismanWalletInstance
+export type MetaMaskWalletInstance = ReturnType<typeof createMetaMaskWallet>
+export type WalletInstance = PolkadotJsWalletInstance | TalismanWalletInstance | MetaMaskWalletInstance

package/src/utils/download-extension.integration.test.ts

@@ -3,6 +3,9 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { METAMASK_CONFIG } from '../wallets/metamask.js'
+import { POLKADOT_JS_CONFIG } from '../wallets/polkadot-js.js'
+import { TALISMAN_CONFIG } from '../wallets/talisman.js'
 import { downloadAndExtractExtension } from './download-extension.js'
 
 /**
@@ -10,8 +13,9 @@ import { downloadAndExtractExtension } from './download-extension.js'
  * Tests actual download and extraction with real extension files
  *
  * Important test cases:
- * - Nested zip extraction (Talisman has a zip inside a zip)
+ * - Single wrapper directory extraction (Talisman zips into a subdirectory)
  * - Standard zip extraction (Polkadot-JS)
+ * - Standard zip extraction (MetaMask)
  * - Skip download if already exists
  * - Error handling for invalid URLs
  */
@@ -29,36 +33,40 @@ describe('downloadAndExtractExtension (integration tests)', () => {
     }
   })
 
-  it('should handle nested zip extraction (Talisman)', async () => {
-    // Talisman extension has a nested zip structure
-    const VERSION = '3.1.13'
-    const options: DownloadExtensionOptions = {
-      downloadUrl: `https://github.com/avalix-labs/polkadot-wallets/raw/refs/heads/main/talisman/talisman-${VERSION}.zip`,
-      extensionName: `talisman-extension-${VERSION}`,
+  it('should handle single wrapper directory extraction (Talisman)', async () => {
+    const result = await downloadAndExtractExtension({
+      ...TALISMAN_CONFIG,
       targetDir: tempDir,
-    }
-
-    const result = await downloadAndExtractExtension(options)
+    })
 
-    expect(result).toBe(path.join(tempDir, `talisman-extension-${VERSION}`))
+    expect(result).toBe(path.join(tempDir, TALISMAN_CONFIG.extensionName))
     expect(fs.existsSync(result)).toBe(true)
 
-    // Talisman should have manifest.json after nested extraction
+    // Talisman zips into a single subdirectory — should be unwrapped
     const files = await fs.promises.readdir(result)
     expect(files).toContain('manifest.json')
   }, 60000)
 
   it('should handle standard zip extraction (Polkadot-JS)', async () => {
-    const VERSION = '0.62.6'
-    const options: DownloadExtensionOptions = {
-      downloadUrl: `https://github.com/polkadot-js/extension/releases/download/v${VERSION}/master-chrome-build.zip`,
-      extensionName: `polkadot-extension-${VERSION}`,
+    const result = await downloadAndExtractExtension({
+      ...POLKADOT_JS_CONFIG,
       targetDir: tempDir,
-    }
+    })
 
-    const result = await downloadAndExtractExtension(options)
+    expect(result).toBe(path.join(tempDir, POLKADOT_JS_CONFIG.extensionName))
+    expect(fs.existsSync(result)).toBe(true)
+
+    const files = await fs.promises.readdir(result)
+    expect(files).toContain('manifest.json')
+  }, 60000)
+
+  it('should handle standard zip extraction (MetaMask)', async () => {
+    const result = await downloadAndExtractExtension({
+      ...METAMASK_CONFIG,
+      targetDir: tempDir,
+    })
 
-    expect(result).toBe(path.join(tempDir, `polkadot-extension-${VERSION}`))
+    expect(result).toBe(path.join(tempDir, METAMASK_CONFIG.extensionName))
     expect(fs.existsSync(result)).toBe(true)
 
     const files = await fs.promises.readdir(result)

package/src/utils/download-extension.test.ts

@@ -1,3 +1,4 @@
+import type { Mock } from 'vitest'
 import type { DownloadExtensionOptions } from './download-extension.js'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -12,11 +13,10 @@ import { downloadAndExtractExtension } from './download-extension.js'
 // Mock adm-zip
 const mockExtractAllTo = vi.fn()
 vi.mock('adm-zip', () => {
-  return {
-    default: vi.fn().mockImplementation(() => ({
-      extractAllTo: mockExtractAllTo,
-    })),
-  }
+  const MockAdmZip = vi.fn(function (this: any) {
+    this.extractAllTo = mockExtractAllTo
+  })
+  return { default: MockAdmZip }
 })
 
 // Mock fetch
@@ -29,6 +29,8 @@ vi.mock('node:stream/promises', () => ({
 }))
 
 // Mock fs module
+// - `fs.existsSync`, `fs.readdirSync`, `fs.promises.*` are accessed via the default import
+// - `createWriteStream` is accessed as a named import
 vi.mock('node:fs', async () => {
   const actual = await vi.importActual<typeof import('node:fs')>('node:fs')
   return {
@@ -43,15 +45,9 @@ vi.mock('node:fs', async () => {
         rename: vi.fn().mockResolvedValue(undefined),
         unlink: vi.fn().mockResolvedValue(undefined),
         readdir: vi.fn().mockResolvedValue([]),
+        stat: vi.fn().mockResolvedValue({ isDirectory: () => true }),
       },
-      createWriteStream: vi.fn().mockReturnValue({
-        on: vi.fn(),
-        write: vi.fn(),
-        end: vi.fn(),
-      }),
     },
-    existsSync: vi.fn(),
-    readdirSync: vi.fn(),
     createWriteStream: vi.fn().mockReturnValue({
       on: vi.fn(),
       write: vi.fn(),
@@ -119,6 +115,14 @@ describe('downloadAndExtractExtension (unit tests)', () => {
       )
     })
 
+    it('should stringify non-Error rejection in thrown message', async () => {
+      mockFetch.mockRejectedValue('plain string failure')
+
+      await expect(downloadAndExtractExtension(mockOptions)).rejects.toThrow(
+        'Failed to download/extract test-extension: plain string failure',
+      )
+    })
+
     it('should cleanup files on error', async () => {
       const mockedFs = vi.mocked(fs)
 
@@ -138,11 +142,91 @@ describe('downloadAndExtractExtension (unit tests)', () => {
 
       await expect(downloadAndExtractExtension(mockOptions)).rejects.toThrow()
 
-      expect(mockedFs.promises.unlink).toHaveBeenCalled()
       expect(mockedFs.promises.rm).toHaveBeenCalled()
     })
   })
 
+  describe('successful download and extraction', () => {
+    beforeEach(() => {
+      const mockedFs = vi.mocked(fs)
+      mockedFs.existsSync.mockReturnValue(false)
+      mockedFs.readdirSync.mockReturnValue([])
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        body: new ReadableStream(),
+      })
+    })
+
+    it('should extract and return correct path', async () => {
+      const mockedFs = vi.mocked(fs)
+      const mockReaddir = mockedFs.promises.readdir as unknown as Mock
+
+      mockReaddir.mockResolvedValue(['manifest.json', 'popup.html'])
+
+      const result = await downloadAndExtractExtension({
+        ...mockOptions,
+        targetDir: '/tmp/test',
+      })
+
+      expect(result).toBe(path.join('/tmp/test', 'test-extension'))
+
+      // AdmZip called once for extraction
+      const AdmZip = (await import('adm-zip')).default
+      expect(AdmZip).toHaveBeenCalledTimes(1)
+    })
+
+    it('should unwrap single wrapper directory', async () => {
+      const mockedFs = vi.mocked(fs)
+      const mockReaddir = mockedFs.promises.readdir as unknown as Mock
+      const mockStat = mockedFs.promises.stat as unknown as Mock
+
+      // readdir returns a single directory -> unwrap
+      mockReaddir.mockResolvedValue(['extension-folder'])
+      mockStat.mockResolvedValue({ isDirectory: () => true })
+
+      const result = await downloadAndExtractExtension({
+        ...mockOptions,
+        targetDir: '/tmp/test',
+      })
+
+      expect(result).toBe(path.join('/tmp/test', 'test-extension'))
+
+      // Should rename the subdirectory (unwrap) and clean up source
+      expect(mockedFs.promises.rename).toHaveBeenCalledWith(
+        expect.stringContaining('extension-folder'),
+        expect.stringContaining('test-extension'),
+      )
+      expect(mockedFs.promises.rm).toHaveBeenCalledWith(
+        expect.stringContaining('test-extension-temp'),
+        expect.objectContaining({ recursive: true, force: true }),
+      )
+    })
+
+    it('should not unwrap when single entry is a file', async () => {
+      const mockedFs = vi.mocked(fs)
+      const mockReaddir = mockedFs.promises.readdir as unknown as Mock
+      const mockStat = mockedFs.promises.stat as unknown as Mock
+
+      mockReaddir.mockResolvedValue(['only-file.dat'])
+      mockStat.mockResolvedValue({ isDirectory: () => false })
+
+      const result = await downloadAndExtractExtension({
+        ...mockOptions,
+        targetDir: '/tmp/test',
+      })
+
+      expect(result).toBe(path.join('/tmp/test', 'test-extension'))
+
+      // Should rename the temp dir directly (no unwrap)
+      expect(mockedFs.promises.rename).toHaveBeenCalledWith(
+        expect.stringContaining('test-extension-temp'),
+        expect.stringContaining('test-extension'),
+      )
+    })
+  })
+
   describe('targetDir option', () => {
     it('should use custom targetDir when provided', async () => {
       const mockedFs = vi.mocked(fs)

package/src/utils/download-extension.ts

@@ -15,6 +15,30 @@ function unzipFile(zipPath: string, destDir: string): void {
   zip.extractAllTo(destDir, true)
 }
 
+/**
+ * Move extracted contents to the final destination.
+ * If the source directory contains a single subdirectory, unwrap it
+ * (move the subdirectory contents up) so the extension files live
+ * directly inside `destDir`.
+ */
+async function moveExtractedToFinal(sourceDir: string, destDir: string): Promise<void> {
+  const entries = await fs.promises.readdir(sourceDir)
+
+  if (entries.length === 1) {
+    const singleEntry = path.join(sourceDir, entries[0])
+    const stat = await fs.promises.stat(singleEntry)
+    if (stat.isDirectory()) {
+      // Unwrap: move the single subdirectory to the final destination
+      await fs.promises.rename(singleEntry, destDir)
+      await fs.promises.rm(sourceDir, { recursive: true, force: true })
+      return
+    }
+  }
+
+  // No unwrapping needed, just rename the whole directory
+  await fs.promises.rename(sourceDir, destDir)
+}
+
 export async function downloadAndExtractExtension(options: DownloadExtensionOptions): Promise<string> {
   const { downloadUrl, extensionName, targetDir } = options
 
@@ -52,25 +76,8 @@ export async function downloadAndExtractExtension(options: DownloadExtensionOpti
     await fs.promises.mkdir(tempExtractDir, { recursive: true })
     unzipFile(zipPath, tempExtractDir)
 
-    // Check if it's a nested zip (contains another .zip file)
-    const files = await fs.promises.readdir(tempExtractDir)
-    const nestedZip = files.find(f => f.endsWith('.zip'))
-
-    if (nestedZip) {
-      console.log(`📦 Found nested zip: ${nestedZip}, extracting...`)
-      const nestedZipPath = path.join(tempExtractDir, nestedZip)
-
-      // Extract the nested zip to final location
-      await fs.promises.mkdir(extensionDir, { recursive: true })
-      unzipFile(nestedZipPath, extensionDir)
-
-      // Clean up temp directory
-      await fs.promises.rm(tempExtractDir, { recursive: true, force: true })
-    }
-    else {
-      // No nested zip, just rename temp to final
-      await fs.promises.rename(tempExtractDir, extensionDir)
-    }
+    // Move extracted contents to final destination (unwrapping single dir if needed)
+    await moveExtractedToFinal(tempExtractDir, extensionDir)
 
     // Clean up ZIP file
     await fs.promises.unlink(zipPath)
@@ -80,14 +87,10 @@ export async function downloadAndExtractExtension(options: DownloadExtensionOpti
   }
   catch (error) {
     // Clean up on error
-    if (fs.existsSync(zipPath)) {
-      await fs.promises.unlink(zipPath).catch(() => {})
-    }
-    if (fs.existsSync(extensionDir)) {
-      await fs.promises.rm(extensionDir, { recursive: true, force: true }).catch(() => {})
-    }
-    if (fs.existsSync(tempExtractDir)) {
-      await fs.promises.rm(tempExtractDir, { recursive: true, force: true }).catch(() => {})
+    for (const dir of [zipPath, extensionDir, tempExtractDir]) {
+      if (fs.existsSync(dir)) {
+        await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => {})
+      }
     }
 
     throw new Error(`Failed to download/extract ${extensionName}: ${error instanceof Error ? error.message : String(error)}`)

package/src/wallets/metamask.test.ts

@@ -0,0 +1,97 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  getMetaMaskExtensionPath,
+  METAMASK_CONFIG,
+} from './metamask.js'
+
+// Mock node:fs module
+vi.mock('node:fs', async () => {
+  const actual = await vi.importActual<typeof import('node:fs')>('node:fs')
+  return {
+    ...actual,
+    default: {
+      ...actual,
+      existsSync: vi.fn(),
+      readdirSync: vi.fn(),
+    },
+    existsSync: vi.fn(),
+    readdirSync: vi.fn(),
+  }
+})
+
+describe('metamask wallet', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('metamask_config', () => {
+    it('should have correct extension name format', () => {
+      expect(METAMASK_CONFIG.extensionName).toMatch(/^metamask-extension-\d+\.\d+\.\d+$/)
+    })
+
+    it('should have valid download URL', () => {
+      expect(METAMASK_CONFIG.downloadUrl).toContain('github.com')
+      expect(METAMASK_CONFIG.downloadUrl).toContain('metamask')
+      expect(METAMASK_CONFIG.downloadUrl.endsWith('.zip')).toBe(true)
+    })
+  })
+
+  describe('getMetaMaskExtensionPath', () => {
+    it('should return extension path when extension exists', async () => {
+      const mockedFs = vi.mocked(fs)
+      mockedFs.existsSync.mockReturnValue(true)
+      mockedFs.readdirSync.mockReturnValue(['manifest.json'] as any)
+
+      const result = await getMetaMaskExtensionPath()
+
+      expect(result).toContain('.chroma')
+      expect(result).toContain(METAMASK_CONFIG.extensionName)
+      expect(mockedFs.existsSync).toHaveBeenCalled()
+    })
+
+    it('should throw error when extension directory does not exist', async () => {
+      const mockedFs = vi.mocked(fs)
+      mockedFs.existsSync.mockReturnValue(false)
+
+      await expect(getMetaMaskExtensionPath()).rejects.toThrow(
+        'MetaMask extension not found',
+      )
+    })
+
+    it('should throw error when extension directory is empty', async () => {
+      const mockedFs = vi.mocked(fs)
+      mockedFs.existsSync.mockReturnValue(true)
+      mockedFs.readdirSync.mockReturnValue([])
+
+      await expect(getMetaMaskExtensionPath()).rejects.toThrow(
+        'MetaMask extension not found',
+      )
+    })
+
+    it('should include download instructions in error message', async () => {
+      const mockedFs = vi.mocked(fs)
+      mockedFs.existsSync.mockReturnValue(false)
+
+      await expect(getMetaMaskExtensionPath()).rejects.toThrow(
+        'npx @avalix/chroma download-extensions',
+      )
+    })
+
+    it('should use correct path structure', async () => {
+      const mockedFs = vi.mocked(fs)
+      mockedFs.existsSync.mockReturnValue(true)
+      mockedFs.readdirSync.mockReturnValue(['manifest.json'] as any)
+
+      const result = await getMetaMaskExtensionPath()
+
+      const expectedPath = path.join(process.cwd(), '.chroma', METAMASK_CONFIG.extensionName)
+      expect(result).toBe(expectedPath)
+    })
+  })
+})

package/src/wallets/metamask.ts

@@ -0,0 +1,245 @@
+import type { BrowserContext, Page } from '@playwright/test'
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+// MetaMask specific configuration
+// https://github.com/MetaMask/metamask-extension/releases
+const VERSION = '13.17.0'
+export const METAMASK_CONFIG = {
+  downloadUrl: `https://github.com/MetaMask/metamask-extension/releases/download/v${VERSION}/metamask-flask-chrome-${VERSION}-flask.0.zip`,
+  extensionName: `metamask-extension-${VERSION}`,
+} as const
+
+// Get MetaMask extension path
+export async function getMetaMaskExtensionPath(): Promise<string> {
+  const extensionsDir = path.resolve(process.cwd(), '.chroma')
+  const extensionDir = path.join(extensionsDir, METAMASK_CONFIG.extensionName)
+
+  // Check if extension exists
+  if (!fs.existsSync(extensionDir) || fs.readdirSync(extensionDir).length === 0) {
+    throw new Error(
+      `MetaMask extension not found at: ${extensionDir}\n\n`
+      + `Please download the extension first by running:\n`
+      + `  npx @avalix/chroma download-extensions\n`,
+    )
+  }
+
+  return extensionDir
+}
+
+/*
+ * Wallet interaction functions below are excluded from coverage because:
+ * - They require a real Chromium browser with extension support
+ * - They interact with Chrome extension popup pages
+ */
+/* c8 ignore start */
+
+// Helper function to find existing MetaMask extension page
+async function findOnboardingPage(
+  context: BrowserContext,
+  extensionId: string,
+): Promise<Page> {
+  const maxAttempts = 10
+  const retryDelay = 500
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const pages = context.pages()
+    for (const p of pages) {
+      if (p.url().includes(`chrome-extension://${extensionId}/`)) {
+        await p.waitForLoadState('domcontentloaded')
+        await p.getByText('I accept the risks').click()
+        return p
+      }
+    }
+
+    // If not found, wait a bit before retrying
+    if (attempt < maxAttempts - 1) {
+      await new Promise(resolve => setTimeout(resolve, retryDelay))
+    }
+  }
+
+  throw new Error(`MetaMask extension page not found for ID: ${extensionId}`)
+}
+
+// Helper function to find MetaMask side panel via CDP, open in new tab, and return the page
+async function findExtensionPopup(
+  context: BrowserContext,
+  extensionId: string,
+): Promise<Page> {
+  const maxAttempts = 10
+  const retryDelay = 500
+
+  const page0 = context.pages()[0]
+  if (!page0) {
+    throw new Error('No pages available to create CDP session')
+  }
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const client = await context.newCDPSession(page0)
+    const { targetInfos } = await client.send('Target.getTargets')
+    const sidePanelTarget = targetInfos.find(
+      (t: any) => t.url.includes(`chrome-extension://${extensionId}/`) && t.url.includes('sidepanel'),
+    )
+    await client.detach()
+
+    if (sidePanelTarget) {
+      // Open the side panel URL in a new tab to interact with it
+      const sidePanelPage = await context.newPage()
+      await sidePanelPage.goto(sidePanelTarget.url)
+      await sidePanelPage.waitForLoadState('domcontentloaded')
+      return sidePanelPage
+    }
+
+    // If not found, wait a bit before retrying
+    if (attempt < maxAttempts - 1) {
+      await new Promise(resolve => setTimeout(resolve, retryDelay))
+    }
+  }
+
+  throw new Error(`MetaMask side panel not found for ID: ${extensionId}`)
+}
+
+const METAMASK_PASSWORD = 'h3llop0lkadot!'
+
+// Helper function to complete MetaMask onboarding flow
+async function completeOnboarding(
+  extensionPage: Page,
+  seedPhrase: string,
+): Promise<void> {
+  // Bring the onboarding page to front
+  await extensionPage.bringToFront()
+  await extensionPage.waitForLoadState('domcontentloaded')
+
+  // Click "Import an existing wallet"
+  await extensionPage.getByTestId('onboarding-import-wallet').click()
+
+  // Click "Import with Secret Recovery Phrase"
+  await extensionPage.getByTestId('onboarding-import-with-srp-button').click()
+
+  // Enter seed phrase
+  // Must use pressSequentially because MetaMask listens for Space keypress to separate words
+  await extensionPage.getByTestId('srp-input-import__srp-note').pressSequentially(seedPhrase, { delay: 50 })
+
+  // Confirm seed phrase
+  await extensionPage.getByTestId('import-srp-confirm').click()
+
+  // Set password
+  await extensionPage.getByTestId('create-password-new-input').fill(METAMASK_PASSWORD)
+  await extensionPage.getByTestId('create-password-confirm-input').fill(METAMASK_PASSWORD)
+  await extensionPage.getByTestId('create-password-terms').click()
+  await extensionPage.getByTestId('create-password-submit').click()
+
+  // Agree to metrics
+  await extensionPage.getByTestId('metametrics-checkbox').click()
+  await extensionPage.getByTestId('metametrics-i-agree').click()
+
+  // Complete onboarding
+  await extensionPage.getByTestId('manage-default-settings').click()
+  await extensionPage.getByTestId('category-item-General').click()
+  await extensionPage.getByTestId('basic-functionality-toggle').locator('.toggle-button').click()
+  await extensionPage.getByText('I understand and want to continue').click()
+  await extensionPage.getByTestId('basic-configuration-modal-toggle-button').click()
+  await extensionPage.getByTestId('category-back-button').click()
+
+  await extensionPage.getByTestId('category-item-Assets').click()
+  await extensionPage.getByTestId('privacy-settings-settings').locator('.toggle-button').nth(0).click()
+  await extensionPage.getByTestId('privacy-settings-settings').locator('.toggle-button').nth(1).click()
+  await extensionPage.getByTestId('privacy-settings-settings').locator('.toggle-button').nth(2).click()
+  await extensionPage.getByTestId('privacy-settings-settings').locator('.toggle-button').nth(3).click()
+  await extensionPage.getByTestId('privacy-settings-settings').locator('.toggle-button').nth(4).click()
+  await extensionPage.getByTestId('category-back-button').click()
+  await extensionPage.getByTestId('privacy-settings-back-button').click()
+
+  await extensionPage.getByTestId('onboarding-complete-done').click()
+  await extensionPage.close()
+}
+
+// MetaMask specific authorization implementation
+// Handles the "connect" popup when a dapp requests wallet connection
+export async function authorizeMetaMask(
+  page: Page & { __extensionContext: BrowserContext, __extensionId: string },
+): Promise<void> {
+  const context = page.__extensionContext
+  const extensionId = page.__extensionId
+
+  const extensionPopup = await findExtensionPopup(context, extensionId)
+
+  // Click "Connect" to authorize the dapp
+  await extensionPopup.getByTestId('confirm-btn').click()
+  await extensionPopup.close()
+}
+
+// MetaMask specific confirm implementation
+// Handles the confirm popup (e.g. sign message, send transaction)
+export async function confirmMetaMask(
+  page: Page & { __extensionContext: BrowserContext, __extensionId: string },
+): Promise<void> {
+  const context = page.__extensionContext
+  const extensionId = page.__extensionId
+
+  const extensionPopup = await findExtensionPopup(context, extensionId)
+
+  // Click "Confirm"
+  await extensionPopup.getByTestId('confirm-footer-button').click()
+  await extensionPopup.close()
+}
+
+// MetaMask specific reject implementation
+// Handles the reject/cancel popup (e.g. reject transaction, switch chain)
+export async function rejectMetaMask(
+  page: Page & { __extensionContext: BrowserContext, __extensionId: string },
+): Promise<void> {
+  const context = page.__extensionContext
+  const extensionId = page.__extensionId
+
+  const extensionPopup = await findExtensionPopup(context, extensionId)
+
+  // Click "Reject" or "Cancel" - MetaMask uses confirm-footer-cancel for tx/sign reject
+  const rejectButton = extensionPopup.getByTestId('confirm-footer-cancel')
+    .or(extensionPopup.getByTestId('page-container-footer-cancel'))
+    .or(extensionPopup.getByRole('button', { name: /Reject|Cancel/i }))
+  await rejectButton.first().click()
+  await extensionPopup.close()
+}
+
+// Unlock MetaMask by navigating to unlock page and filling password
+export async function unlockMetaMask(
+  page: Page & { __extensionContext: BrowserContext, __extensionId: string },
+): Promise<void> {
+  const context = page.__extensionContext
+  const extensionId = page.__extensionId
+
+  const unlockUrl = `chrome-extension://${extensionId}/home.html#/onboarding/unlock`
+  const unlockPage = await context.newPage()
+  await unlockPage.goto(unlockUrl)
+  await unlockPage.waitForLoadState('domcontentloaded')
+
+  // Fill password and unlock
+  await unlockPage.getByTestId('unlock-password').fill(METAMASK_PASSWORD)
+  await unlockPage.getByTestId('unlock-submit').click()
+
+  // await unlockPage.getByTestId('onboarding-complete-done').click()
+  await unlockPage.close()
+}
+
+// MetaMask specific seed phrase import implementation
+export async function importSeedPhrase(
+  page: Page & { __extensionContext: BrowserContext, __extensionId: string },
+  { seedPhrase }: { seedPhrase: string },
+): Promise<void> {
+  const context = page.__extensionContext
+  const extensionId = page.__extensionId
+
+  const extensionPage = await findOnboardingPage(context, extensionId)
+
+  try {
+    await completeOnboarding(extensionPage, seedPhrase)
+  }
+  catch (error) {
+    console.error('❌ Error during MetaMask Ethereum account import:', error)
+    throw error
+  }
+}
+
+/* c8 ignore stop */

package/src/wallets/talisman.ts

@@ -6,7 +6,7 @@ import process from 'node:process'
 
 // Talisman specific configuration
 // https://github.com/avalix-labs/polkadot-wallets/tree/main/talisman
-const VERSION = '3.1.13'
+const VERSION = '3.2.0'
 export const TALISMAN_CONFIG = {
   downloadUrl: `https://github.com/avalix-labs/polkadot-wallets/raw/refs/heads/main/talisman/talisman-${VERSION}.zip`,
   extensionName: `talisman-extension-${VERSION}`,