@avalix/chroma 0.0.16 → 1.0.0

package/src/context-playwright/index.ts

@@ -1,12 +1,14 @@
 import type {
   ChromaTestOptions,
   ConfiguredWallets,
-  ExtendedPage,
   WalletConfig,
   WalletFixtures,
-  Wallets,
+  WalletType,
+  WalletTypeMap,
   WalletWorkerFixtures,
 } from './types.js'
+import { cp, rm } from 'node:fs/promises'
+import { resolve as resolvePath } from 'node:path'
 import { test as base, chromium } from '@playwright/test'
 import { getMetaMaskExtensionPath } from '../wallets/metamask.js'
 import { getPolkadotJSExtensionPath } from '../wallets/polkadot-js.js'
@@ -14,7 +16,7 @@ import { getTalismanExtensionPath } from '../wallets/talisman.js'
 import { walletFactories } from './wallet-factory.js'
 
 // Helper function to get extension path for a wallet config
-export async function getExtensionPathForWallet(config: WalletConfig): Promise<string> {
+async function getExtensionPathForWallet(config: WalletConfig): Promise<string> {
   const { type } = config
 
   switch (type) {
@@ -41,10 +43,8 @@ export function createWalletTest<const T extends readonly WalletConfig[]>(
     ? options.wallets
     : [{ type: 'polkadot-js' }]
 
-  const isMultiWallet = walletConfigs.length > 1
-
   // Compute the expected wallets type
-  type ExpectedWallets = T extends readonly WalletConfig[] ? ConfiguredWallets<T> : Wallets
+  type ExpectedWallets = T extends readonly WalletConfig[] ? ConfiguredWallets<T> : WalletTypeMap
 
   /*
    * Playwright Fixtures - Coverage Exclusion
@@ -58,7 +58,7 @@ export function createWalletTest<const T extends readonly WalletConfig[]>(
   return base.extend<WalletFixtures<ExpectedWallets>, WalletWorkerFixtures>({
     // Worker-scoped: Browser context with extension(s) (persists across all tests in worker)
     // eslint-disable-next-line no-empty-pattern
-    walletContext: [async ({}, use) => {
+    walletContext: [async ({}, use, workerInfo) => {
       // Get all extension paths
       const extensionPaths = await Promise.all(
         walletConfigs.map(config => getExtensionPathForWallet(config)),
@@ -67,7 +67,29 @@ export function createWalletTest<const T extends readonly WalletConfig[]>(
       // Join paths with comma for Chrome args
       const extensionPathsString = extensionPaths.join(',')
 
-      const context = await chromium.launchPersistentContext('', {
+      // Resolve userDataDir (string, function, or default empty)
+      const userDataDirOption = options.userDataDir
+      const userDataDir = typeof userDataDirOption === 'function'
+        ? await userDataDirOption({ workerIndex: workerInfo.workerIndex })
+        : userDataDirOption ?? ''
+
+      // Optional clone: reset target then copy from source. Skipped when
+      // userDataDir is empty (clone into a temp dir would defeat its purpose).
+      if (options.cloneUserDataDirFrom && userDataDir) {
+        // Guard against rm wiping the source: resolve both to absolute paths
+        // and refuse if they point at the same location.
+        const sourceAbs = resolvePath(options.cloneUserDataDirFrom)
+        const targetAbs = resolvePath(userDataDir)
+        if (sourceAbs === targetAbs) {
+          throw new Error(
+            `cloneUserDataDirFrom and userDataDir must be different paths; both resolved to "${sourceAbs}"`,
+          )
+        }
+        await rm(userDataDir, { recursive: true, force: true })
+        await cp(options.cloneUserDataDirFrom, userDataDir, { recursive: true })
+      }
+
+      const context = await chromium.launchPersistentContext(userDataDir, {
         headless,
         channel: 'chromium',
         args: [
@@ -83,44 +105,36 @@ export function createWalletTest<const T extends readonly WalletConfig[]>(
 
     // Worker-scoped: Map of wallet type to extension ID
     walletExtensionIds: [async ({ walletContext }, use) => {
-      const extensionIds = new Map<string, string>()
-
-      // Wait for all service workers to load
-      const serviceWorkers = walletContext.serviceWorkers()
-      if (serviceWorkers.length === 0) {
-        // Wait for at least one service worker
-        await walletContext.waitForEvent('serviceworker')
-      }
-
-      // Give some time for all extensions to load
-      if (isMultiWallet) {
-        await new Promise(resolve => setTimeout(resolve, 1000))
+      const extensionIds = new Map<WalletType, string>()
+
+      // Wait until one service worker per configured wallet has registered.
+      // Bounded by 10s so a stuck worker fails fast instead of hanging the suite.
+      const expected = walletConfigs.length
+      const deadline = Date.now() + 10_000
+      while (walletContext.serviceWorkers().length < expected) {
+        if (Date.now() > deadline) {
+          break
+        }
+        await Promise.race([
+          walletContext.waitForEvent('serviceworker', { timeout: 2_000 }).catch(() => {}),
+          new Promise(resolve => setTimeout(resolve, 200)),
+        ])
       }
 
-      // Get all service workers (one per extension)
+      // Map service workers to wallet types (order matches walletConfigs order)
       const allServiceWorkers = walletContext.serviceWorkers()
-
-      // Map service workers to wallet types
-      // Note: The order should match the walletConfigs order
       for (let i = 0; i < walletConfigs.length && i < allServiceWorkers.length; i++) {
         const extensionId = allServiceWorkers[i].url().split('/')[2]
-        const walletType = walletConfigs[i].type
-        extensionIds.set(walletType, extensionId)
+        extensionIds.set(walletConfigs[i].type, extensionId)
       }
 
       await use(extensionIds)
     }, { scope: 'worker' }],
 
-    // Main page with extension context (uses worker-scoped context)
-    page: async ({ walletContext, walletExtensionIds }, use) => {
+    // Main page (uses worker-scoped context)
+    page: async ({ walletContext }, use) => {
       const page = walletContext.pages()[0] || await walletContext.newPage()
-
-      // Store context and extension IDs on page
-      const extendedPage = page as ExtendedPage
-      extendedPage.__extensionContext = walletContext
-      extendedPage.__walletExtensionIds = walletExtensionIds
-
-      await use(extendedPage)
+      await use(page)
       // Note: Don't close the page or context here since they're worker-scoped
     },
 
@@ -130,7 +144,7 @@ export function createWalletTest<const T extends readonly WalletConfig[]>(
 
       // Create wallet instance for each configured wallet
       for (const [walletType, extensionId] of walletExtensionIds) {
-        const factory = walletFactories[walletType as keyof typeof walletFactories]
+        const factory = walletFactories[walletType]
         if (factory) {
           walletMap[walletType as keyof ExpectedWallets] = factory(extensionId, walletContext) as ExpectedWallets[keyof ExpectedWallets]
         }

package/src/context-playwright/types.ts

@@ -3,12 +3,8 @@ import type {
   MetaMaskWalletInstance,
   PolkadotJsWalletInstance,
   TalismanWalletInstance,
-  WalletInstance,
 } from './wallet-factory.js'
 
-// Re-export wallet instance types
-export type { MetaMaskWalletInstance, PolkadotJsWalletInstance, TalismanWalletInstance, WalletInstance }
-
 // Wallet types - single source of truth
 export type WalletType = 'polkadot-js' | 'talisman' | 'metamask'
 
@@ -22,7 +18,6 @@ export interface WalletAccount {
 // Configuration for a single wallet
 export interface WalletConfig {
   type: WalletType
-  downloadUrl?: string
 }
 
 // Map wallet type to its instance
@@ -32,20 +27,11 @@ export interface WalletTypeMap {
   'metamask': MetaMaskWalletInstance
 }
 
-// Wallets collection - all wallet types
-export type Wallets = WalletTypeMap
-
 // Helper type to build a wallets object based on configured wallet types
 export type ConfiguredWallets<T extends readonly WalletConfig[]> = {
   [K in T[number]['type']]: WalletTypeMap[K]
 }
 
-// Extended page with wallet context
-export type ExtendedPage = Page & {
-  __extensionContext: BrowserContext
-  __walletExtensionIds: Map<string, string>
-}
-
 // Complete test configuration - supports single and multi-wallet
 export interface ChromaTestOptions<T extends readonly WalletConfig[] = WalletConfig[]> {
   // Wallet configuration (single or multiple)
@@ -53,16 +39,32 @@ export interface ChromaTestOptions<T extends readonly WalletConfig[] = WalletCon
   // Common options
   headless?: boolean
   slowMo?: number
+  /**
+   * Persistent profile dir for the browser context.
+   * - Empty/undefined (default): temp dir is used; state is lost each run.
+   * - String: shared profile path. Requires `workers: 1` if used by multiple workers.
+   * - Function: receives the worker index, returns the path. Use for parallel
+   *   isolation (e.g. `({ workerIndex }) => `.cache/wallet-w${workerIndex}``).
+   */
+  userDataDir?: string | ((info: { workerIndex: number }) => string | Promise<string>)
+  /**
+   * If set, the source dir is copied into `userDataDir` before launch (target is
+   * removed first). Use with the Playwright setup-project pattern: a setup
+   * project writes to the source dir, then test projects clone it per worker so
+   * each parallel worker boots from the same prepared state.
+   * No-op if `userDataDir` resolves to an empty string.
+   */
+  cloneUserDataDirFrom?: string
 }
 
 // Test fixtures (test-scoped: recreated per test)
-export interface WalletFixtures<W = Wallets> {
-  page: ExtendedPage
+export interface WalletFixtures<W = WalletTypeMap> {
+  page: Page
   wallets: W
 }
 
 // Worker fixtures (worker-scoped: persisted across tests)
 export interface WalletWorkerFixtures {
   walletContext: BrowserContext
-  walletExtensionIds: Map<string, string>
+  walletExtensionIds: Map<WalletType, string>
 }

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

@@ -1,6 +1,7 @@
 import type { BrowserContext, Page } from '@playwright/test'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import {
+  createMetaMaskWallet,
   createPolkadotJsWallet,
   createTalismanWallet,
   walletFactories,
@@ -22,6 +23,13 @@ vi.mock('../wallets/talisman.js', () => ({
   rejectTalismanTx: vi.fn(),
 }))
 
+vi.mock('../wallets/metamask.js', () => ({
+  importSeedPhrase: vi.fn(),
+  unlockMetaMask: vi.fn(),
+  approveMetaMask: vi.fn(),
+  rejectMetaMask: vi.fn(),
+}))
+
 // Create mock browser context
 function createMockContext(): BrowserContext {
   const mockPage = {
@@ -51,6 +59,11 @@ describe('wallet-factory', () => {
       expect(walletFactories.talisman).toBeDefined()
       expect(typeof walletFactories.talisman).toBe('function')
     })
+
+    it('should have metamask factory', () => {
+      expect(walletFactories.metamask).toBeDefined()
+      expect(typeof walletFactories.metamask).toBe('function')
+    })
   })
 
   describe('createPolkadotJsWallet', () => {
@@ -103,4 +116,29 @@ describe('wallet-factory', () => {
       expect(typeof wallet.rejectTx).toBe('function')
     })
   })
+
+  describe('createMetaMaskWallet', () => {
+    const extensionId = 'test-extension-id'
+    let mockContext: BrowserContext
+
+    beforeEach(() => {
+      mockContext = createMockContext()
+    })
+
+    it('should create wallet with correct type and extensionId', () => {
+      const wallet = createMetaMaskWallet(extensionId, mockContext)
+
+      expect(wallet.type).toBe('metamask')
+      expect(wallet.extensionId).toBe(extensionId)
+    })
+
+    it('should have all required methods', () => {
+      const wallet = createMetaMaskWallet(extensionId, mockContext)
+
+      expect(typeof wallet.importSeedPhrase).toBe('function')
+      expect(typeof wallet.unlock).toBe('function')
+      expect(typeof wallet.approve).toBe('function')
+      expect(typeof wallet.reject).toBe('function')
+    })
+  })
 })

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

@@ -1,8 +1,7 @@
-import type { BrowserContext, Page } from '@playwright/test'
+import type { BrowserContext } from '@playwright/test'
 import type { WalletAccount } from './types.js'
 import {
-  authorizeMetaMask,
-  confirmMetaMask,
+  approveMetaMask,
   importSeedPhrase as importMetaMaskSeedPhrase,
   rejectMetaMask,
   unlockMetaMask,
@@ -21,16 +20,6 @@ import {
   rejectTalismanTx,
 } from '../wallets/talisman.js'
 
-// Helper to create extended page with wallet context
-/* c8 ignore start */
-function createExtendedPage(page: Page, context: BrowserContext, extensionId: string) {
-  const extPage = page as Page & { __extensionContext: BrowserContext, __extensionId: string }
-  extPage.__extensionContext = context
-  extPage.__extensionId = extensionId
-  return extPage
-}
-/* c8 ignore stop */
-
 /*
  * Factory function for Polkadot-JS wallet
  * Coverage excluded: methods interact with Chrome extension APIs via browser context.
@@ -40,26 +29,10 @@ export function createPolkadotJsWallet(extensionId: string, context: BrowserCont
   return {
     extensionId,
     type: 'polkadot-js' as const,
-    importMnemonic: async (options: WalletAccount) => {
-      const page = context.pages()[0] || await context.newPage()
-      const extPage = createExtendedPage(page, context, extensionId)
-      await importPolkadotJSAccount(extPage, options)
-    },
-    authorize: async () => {
-      const page = context.pages()[0] || await context.newPage()
-      const extPage = createExtendedPage(page, context, extensionId)
-      await authorizePolkadotJS(extPage)
-    },
-    approveTx: async (options: { password?: string } = {}) => {
-      const page = context.pages()[0] || await context.newPage()
-      const extPage = createExtendedPage(page, context, extensionId)
-      await approvePolkadotJSTx(extPage, options)
-    },
-    rejectTx: async () => {
-      const page = context.pages()[0] || await context.newPage()
-      const extPage = createExtendedPage(page, context, extensionId)
-      await rejectPolkadotJSTx(extPage)
-    },
+    importMnemonic: (options: WalletAccount) => importPolkadotJSAccount(context, extensionId, options),
+    authorize: () => authorizePolkadotJS(context, extensionId),
+    approveTx: (options: { password?: string } = {}) => approvePolkadotJSTx(context, extensionId, options),
+    rejectTx: () => rejectPolkadotJSTx(context, extensionId),
   }
 }
 /* c8 ignore stop */
@@ -75,38 +48,24 @@ export function createTalismanWallet(extensionId: string, context: BrowserContex
   return {
     extensionId,
     type: 'talisman' as const,
-    importPolkadotMnemonic: async (options: WalletAccount) => {
-      const page = context.pages()[0] || await context.newPage()
-      const extPage = createExtendedPage(page, context, extensionId)
+    importPolkadotMnemonic: (options: WalletAccount) => {
       importedAccountName = options.name || 'Test Account'
-      await importPolkadotMnemonic(extPage, options)
+      return importPolkadotMnemonic(context, extensionId, options)
     },
-    importEthPrivateKey: async (options: { privateKey: string, name?: string, password?: string }) => {
-      const page = context.pages()[0] || await context.newPage()
-      const extPage = createExtendedPage(page, context, extensionId)
+    importEthPrivateKey: (options: { privateKey: string, name?: string, password?: string }) => {
       importedAccountName = options.name || 'Test Account'
-      await importEthPrivateKey(extPage, {
+      return importEthPrivateKey(context, extensionId, {
         seed: options.privateKey,
         name: options.name,
         password: options.password,
       })
     },
-    authorize: async (options: { accountName?: string } = {}) => {
-      const page = context.pages()[0] || await context.newPage()
-      const extPage = createExtendedPage(page, context, extensionId)
+    authorize: (options: { accountName?: string } = {}) => {
       const accountName = options.accountName || importedAccountName
-      await authorizeTalisman(extPage, { accountName })
-    },
-    approveTx: async () => {
-      const page = context.pages()[0] || await context.newPage()
-      const extPage = createExtendedPage(page, context, extensionId)
-      await approveTalismanTx(extPage)
-    },
-    rejectTx: async () => {
-      const page = context.pages()[0] || await context.newPage()
-      const extPage = createExtendedPage(page, context, extensionId)
-      await rejectTalismanTx(extPage)
+      return authorizeTalisman(context, extensionId, { accountName })
     },
+    approveTx: () => approveTalismanTx(context, extensionId),
+    rejectTx: () => rejectTalismanTx(context, extensionId),
   }
 }
 /* c8 ignore stop */
@@ -120,31 +79,10 @@ export function createMetaMaskWallet(extensionId: string, context: BrowserContex
   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)
-    },
+    importSeedPhrase: (options: { seedPhrase: string }) => importMetaMaskSeedPhrase(context, extensionId, options),
+    unlock: () => unlockMetaMask(context, extensionId),
+    approve: () => approveMetaMask(context, extensionId),
+    reject: () => rejectMetaMask(context, extensionId),
   }
 }
 /* c8 ignore stop */
@@ -160,4 +98,3 @@ export const walletFactories = {
 export type PolkadotJsWalletInstance = ReturnType<typeof createPolkadotJsWallet>
 export type TalismanWalletInstance = ReturnType<typeof createTalismanWallet>
 export type MetaMaskWalletInstance = ReturnType<typeof createMetaMaskWallet>
-export type WalletInstance = PolkadotJsWalletInstance | TalismanWalletInstance | MetaMaskWalletInstance

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

@@ -28,7 +28,7 @@ describe('downloadAndExtractExtension (integration tests)', () => {
   })
 
   afterEach(async () => {
-    if (tempDir && fs.existsSync(tempDir)) {
+    if (tempDir) {
       await fs.promises.rm(tempDir, { recursive: true, force: true })
     }
   })

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

@@ -29,7 +29,7 @@ vi.mock('node:stream/promises', () => ({
 }))
 
 // Mock fs module
-// - `fs.existsSync`, `fs.readdirSync`, `fs.promises.*` are accessed via the default import
+// - `fs.promises.*` is 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')
@@ -37,8 +37,6 @@ vi.mock('node:fs', async () => {
     ...actual,
     default: {
       ...actual,
-      existsSync: vi.fn(),
-      readdirSync: vi.fn(),
       promises: {
         mkdir: vi.fn().mockResolvedValue(undefined),
         rm: vi.fn().mockResolvedValue(undefined),
@@ -73,9 +71,8 @@ describe('downloadAndExtractExtension (unit tests)', () => {
 
   describe('when extension already exists', () => {
     it('should skip download and return existing path', async () => {
-      const mockedFs = vi.mocked(fs)
-      mockedFs.existsSync.mockReturnValue(true)
-      mockedFs.readdirSync.mockReturnValue(['manifest.json'] as any)
+      const mockedReaddir = vi.mocked(fs.promises.readdir) as unknown as Mock
+      mockedReaddir.mockResolvedValueOnce(['manifest.json'])
 
       const result = await downloadAndExtractExtension(mockOptions)
 
@@ -90,9 +87,8 @@ describe('downloadAndExtractExtension (unit tests)', () => {
 
   describe('when extension does not exist', () => {
     beforeEach(() => {
-      const mockedFs = vi.mocked(fs)
-      mockedFs.existsSync.mockReturnValue(false)
-      mockedFs.readdirSync.mockReturnValue([])
+      const mockedReaddir = vi.mocked(fs.promises.readdir) as unknown as Mock
+      mockedReaddir.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }))
     })
 
     it('should throw error when download fails with bad status', async () => {
@@ -132,14 +128,6 @@ describe('downloadAndExtractExtension (unit tests)', () => {
         statusText: 'Internal Server Error',
       })
 
-      mockedFs.existsSync.mockImplementation((p: fs.PathLike) => {
-        const pathStr = p.toString()
-        if (pathStr.endsWith('test-extension') && !pathStr.includes('.zip')) {
-          return false
-        }
-        return true
-      })
-
       await expect(downloadAndExtractExtension(mockOptions)).rejects.toThrow()
 
       expect(mockedFs.promises.rm).toHaveBeenCalled()
@@ -148,10 +136,6 @@ describe('downloadAndExtractExtension (unit tests)', () => {
 
   describe('successful download and extraction', () => {
     beforeEach(() => {
-      const mockedFs = vi.mocked(fs)
-      mockedFs.existsSync.mockReturnValue(false)
-      mockedFs.readdirSync.mockReturnValue([])
-
       mockFetch.mockResolvedValue({
         ok: true,
         status: 200,
@@ -160,10 +144,9 @@ describe('downloadAndExtractExtension (unit tests)', () => {
     })
 
     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 mockReaddir = vi.mocked(fs.promises.readdir) as unknown as Mock
+      mockReaddir.mockResolvedValueOnce([]) // existence check
+      mockReaddir.mockResolvedValueOnce(['manifest.json', 'popup.html']) // post-extraction
 
       const result = await downloadAndExtractExtension({
         ...mockOptions,
@@ -182,8 +165,8 @@ describe('downloadAndExtractExtension (unit tests)', () => {
       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'])
+      mockReaddir.mockResolvedValueOnce([]) // existence check
+      mockReaddir.mockResolvedValueOnce(['extension-folder']) // post-extraction
       mockStat.mockResolvedValue({ isDirectory: () => true })
 
       const result = await downloadAndExtractExtension({
@@ -209,7 +192,8 @@ describe('downloadAndExtractExtension (unit tests)', () => {
       const mockReaddir = mockedFs.promises.readdir as unknown as Mock
       const mockStat = mockedFs.promises.stat as unknown as Mock
 
-      mockReaddir.mockResolvedValue(['only-file.dat'])
+      mockReaddir.mockResolvedValueOnce([]) // existence check
+      mockReaddir.mockResolvedValueOnce(['only-file.dat']) // post-extraction
       mockStat.mockResolvedValue({ isDirectory: () => false })
 
       const result = await downloadAndExtractExtension({
@@ -229,9 +213,8 @@ describe('downloadAndExtractExtension (unit tests)', () => {
 
   describe('targetDir option', () => {
     it('should use custom targetDir when provided', async () => {
-      const mockedFs = vi.mocked(fs)
-      mockedFs.existsSync.mockReturnValue(true)
-      mockedFs.readdirSync.mockReturnValue(['manifest.json'] as any)
+      const mockReaddir = vi.mocked(fs.promises.readdir) as unknown as Mock
+      mockReaddir.mockResolvedValueOnce(['manifest.json'])
 
       const customOptions: DownloadExtensionOptions = {
         ...mockOptions,
@@ -244,9 +227,8 @@ describe('downloadAndExtractExtension (unit tests)', () => {
     })
 
     it('should use default .chroma directory when targetDir not provided', async () => {
-      const mockedFs = vi.mocked(fs)
-      mockedFs.existsSync.mockReturnValue(true)
-      mockedFs.readdirSync.mockReturnValue(['manifest.json'] as any)
+      const mockReaddir = vi.mocked(fs.promises.readdir) as unknown as Mock
+      mockReaddir.mockResolvedValueOnce(['manifest.json'])
 
       const result = await downloadAndExtractExtension(mockOptions)
 

package/src/utils/download-extension.ts

@@ -4,6 +4,10 @@ import process from 'node:process'
 import { pipeline } from 'node:stream/promises'
 import AdmZip from 'adm-zip'
 
+async function safeReaddir(dir: string): Promise<string[]> {
+  return fs.promises.readdir(dir).catch(() => [] as string[])
+}
+
 export interface DownloadExtensionOptions {
   downloadUrl: string
   extensionName: string
@@ -52,7 +56,7 @@ export async function downloadAndExtractExtension(options: DownloadExtensionOpti
   await fs.promises.mkdir(extensionsDir, { recursive: true })
 
   // Check if extension is already downloaded and extracted
-  if (fs.existsSync(extensionDir) && fs.readdirSync(extensionDir).length > 0) {
+  if ((await safeReaddir(extensionDir)).length > 0) {
     console.log(`✅ ${extensionName} already exists at:`, extensionDir)
     return extensionDir
   }
@@ -86,12 +90,12 @@ export async function downloadAndExtractExtension(options: DownloadExtensionOpti
     return extensionDir
   }
   catch (error) {
-    // Clean up on error
-    for (const dir of [zipPath, extensionDir, tempExtractDir]) {
-      if (fs.existsSync(dir)) {
-        await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => {})
-      }
-    }
+    // Clean up on error (force: true silently ignores missing paths)
+    await Promise.all(
+      [zipPath, extensionDir, tempExtractDir].map(dir =>
+        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/utils/find-extension-popup.ts

@@ -0,0 +1,39 @@
+import type { BrowserContext, Page } from '@playwright/test'
+
+export interface FindExtensionPopupOptions {
+  maxAttempts?: number
+  retryDelay?: number
+  viewport?: { width: number, height: number }
+}
+
+/**
+ * Poll the BrowserContext for a page whose URL points at the given Chrome
+ * extension. Returns once the page is reachable and DOM-loaded.
+ */
+/* c8 ignore start */
+export async function findExtensionPopup(
+  context: BrowserContext,
+  extensionId: string,
+  options: FindExtensionPopupOptions = {},
+): Promise<Page> {
+  const { maxAttempts = 10, retryDelay = 500, viewport } = options
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    for (const p of context.pages()) {
+      if (p.url().includes(`chrome-extension://${extensionId}/`)) {
+        if (viewport) {
+          await p.setViewportSize(viewport)
+        }
+        await p.waitForLoadState('domcontentloaded')
+        return p
+      }
+    }
+
+    if (attempt < maxAttempts - 1) {
+      await new Promise(resolve => setTimeout(resolve, retryDelay))
+    }
+  }
+
+  throw new Error(`Extension popup not found for ID: ${extensionId}`)
+}
+/* c8 ignore stop */

package/src/utils/test-defaults.ts

@@ -0,0 +1,7 @@
+/**
+ * Default password used by chroma to bootstrap wallets in tests.
+ *
+ * Wallet methods accept an explicit `password` option that overrides this
+ * value, so callers that already supply their own password are unaffected.
+ */
+export const DEFAULT_TEST_PASSWORD = 'h3llop0lkadot!'