@avalix/chroma 0.0.6 → 0.0.8

package/README.md

@@ -2,7 +2,7 @@
 
 End-to-end testing library for Polkadot wallet interactions using Playwright.
 
-> **Current Status**: This library currently supports **Polkadot JS Extension** only. Support for other wallets like Talisman is planned for future releases.
+> **⚠️ Active Development**: This library is currently under active development. The API may change and breaking changes can occur between versions. Please pin your version and review changelogs carefully when updating.
 
 ## Installation
 
@@ -12,6 +12,18 @@ npm install @avalix/chroma @playwright/test
 
 **Note**: `@playwright/test` is a peer dependency and must be installed separately to avoid conflicts.
 
+### Download Extensions
+
+Before running your tests, you need to download the wallet extensions:
+
+```bash
+npx @avalix/chroma download-extensions
+```
+
+This will download the wallet extensions (Polkadot JS and Talisman) to `./.chroma` directory in your project root.
+
+**Important**: You must run this command before running Playwright tests. If the extension is not found, tests will fail with a helpful error message.
+
 ## Quick Start
 
 ### Basic Usage
@@ -19,9 +31,11 @@ npm install @avalix/chroma @playwright/test
 ```typescript
 import { expect, test } from '@avalix/chroma'
 
-test('should connect wallet and sign transaction', async ({ page, importAccount, authorize, approveTx }) => {
+test('should connect wallet and sign transaction', async ({ page, wallets }) => {
+  const polkadotJs = wallets['polkadot-js']
+
   // Import a test account
-  await importAccount({
+  await polkadotJs.importMnemonic({
     seed: 'bottom drive obey lake curtain smoke basket hold race lonely fit walk',
     name: 'Test Account',
     password: 'securePassword123'
@@ -32,11 +46,11 @@ test('should connect wallet and sign transaction', async ({ page, importAccount,
 
   // Connect wallet
   await page.click('button:has-text("Connect Wallet")')
-  await authorize()
+  await polkadotJs.authorize()
 
   // Perform transaction
   await page.click('button:has-text("Send Transaction")')
-  await approveTx({ password: 'securePassword123' })
+  await polkadotJs.approveTx({ password: 'securePassword123' })
 
   // Verify transaction success
   await expect(page.locator('.transaction-success')).toBeVisible()
@@ -48,33 +62,71 @@ test('should connect wallet and sign transaction', async ({ page, importAccount,
 ```typescript
 import { createWalletTest, expect } from '@avalix/chroma'
 
-// Create test with custom configuration
 const customTest = createWalletTest({
-  walletType: 'polkadot-js',
-  walletConfig: {
-    customPath: './my-custom-extension'
-  },
+  wallets: [{ type: 'polkadot-js' }],
   headless: false,
   slowMo: 100
 })
 
-customTest('test with custom config', async ({ page, importAccount, authorize }) => {
-  // Your test code here
-  await importAccount({
+customTest('test with custom config', async ({ page, wallets }) => {
+  const polkadotJs = wallets['polkadot-js']
+
+  await polkadotJs.importMnemonic({
     seed: 'your seed phrase here...',
     name: 'My Test Account'
   })
-  // ... rest of your test
+  await page.goto('http://localhost:3000')
+  await polkadotJs.authorize()
+})
+```
+
+### Multiple Wallets
+
+```typescript
+import { createWalletTest, expect } from '@avalix/chroma'
+
+// Test with multiple wallet extensions
+const multiWalletTest = createWalletTest({
+  wallets: [
+    { type: 'polkadot-js' },
+    { type: 'talisman' }
+  ],
+  headless: false,
+  slowMo: 150
+})
+
+multiWalletTest('test with multiple wallets', async ({ page, wallets }) => {
+  const polkadotJs = wallets['polkadot-js']
+  const talisman = wallets.talisman
+
+  // Import to Polkadot JS
+  await polkadotJs.importMnemonic({
+    seed: 'bottom drive obey lake curtain smoke basket hold race lonely fit walk',
+    name: 'Alice'
+  })
+
+  // Import to Talisman using Ethereum private key
+  await talisman.importEthPrivateKey({
+    privateKey: '0x...',
+    name: 'Bob'
+  })
+
+  await page.goto('http://localhost:3000')
+
+  // Use specific wallet
+  await polkadotJs.authorize()
+  await polkadotJs.approveTx()
 })
 ```
 
 ## Features
 
-- 🔐 **Automatic Extension Setup**: Downloads and configures Polkadot JS extension automatically
+- 🔐 **Easy Extension Setup**: Simple command to download wallet extensions
 - 🧪 **Test Fixtures**: Ready-to-use Playwright fixtures for wallet operations
 - 📝 **Account Management**: Import accounts with seed phrases and custom names
 - ✅ **Transaction Approval**: Approve transactions with password authentication
 - 🔗 **dApp Authorization**: Connect wallet to decentralized applications
+- 🔀 **Multi-Wallet Support**: Test with multiple wallet extensions simultaneously
 - ⚙️ **Configurable**: Custom extension paths, headless mode, and slow motion settings
 
 ## API Reference
@@ -87,110 +139,152 @@ Pre-configured test function with Polkadot JS extension.
 ```typescript
 import { test } from '@avalix/chroma'
 
-test('my wallet test', async ({ page, importAccount, authorize, approveTx }) => {
-  // Test implementation
+test('my wallet test', async ({ page, wallets }) => {
+  const polkadotJs = wallets['polkadot-js']
+
+  await polkadotJs.importMnemonic({ seed: '...' })
+  await polkadotJs.authorize()
 })
 ```
 
 #### `createWalletTest(options?: ChromaTestOptions)`
-Create a custom test function with specific configuration.
+Create a custom test function with specific configuration. Supports single and multi-wallet modes.
 
 ```typescript
 import { createWalletTest } from '@avalix/chroma'
 
+// Single wallet (default)
+const test = createWalletTest()
+
+// Single wallet with custom config
 const customTest = createWalletTest({
-  walletType: 'polkadot-js', // Currently only 'polkadot-js' is supported
-  walletConfig: {
-    customPath: './custom-extension', // Optional: path to custom extension
-    downloadUrl: 'https://...' // Optional: custom download URL
-  },
-  headless: true, // Optional: run in headless mode
-  slowMo: 150 // Optional: slow motion delay in ms (default: 150)
+  wallets: [{ type: 'polkadot-js' }],
+  headless: false,
+  slowMo: 150
+})
+
+// Multiple wallets
+const multiTest = createWalletTest({
+  wallets: [
+    { type: 'polkadot-js' },
+    { type: 'talisman' }
+  ]
+})
+
+// Usage
+test('example', async ({ page, wallets }) => {
+  const polkadotJs = wallets['polkadot-js']
+
+  await polkadotJs.importMnemonic({ seed: '...' })
+  await polkadotJs.authorize()
+  await polkadotJs.approveTx()
 })
 ```
 
 ### Test Fixtures
 
-#### `importAccount(options: WalletAccount)`
-Import a wallet account using seed phrase.
+#### `page`
+Playwright page instance with wallet extension(s) loaded.
+
+#### `wallets`
+Typed object containing wallet instances for each configured wallet. Provides full TypeScript autocomplete.
 
 ```typescript
+// Base wallet instance (common methods)
+interface BaseWalletInstance {
+  extensionId: string
+  importMnemonic: (options: WalletAccount) => Promise<void>
+  authorize: (options?: { accountName?: string }) => Promise<void>
+  approveTx: (options?: { password?: string }) => Promise<void>
+}
+
+// Polkadot-JS wallet instance
+interface PolkadotJsWalletInstance extends BaseWalletInstance {
+  type: 'polkadot-js'
+}
+
+// Talisman wallet instance (with additional methods)
+interface TalismanWalletInstance extends BaseWalletInstance {
+  type: 'talisman'
+  importEthPrivateKey: (options: { privateKey: string, name?: string, password?: string }) => Promise<void>
+}
+
+// Note: Talisman currently does not support importMnemonic - use importEthPrivateKey instead
+
+// Wallets collection - each wallet has its specific type
+interface Wallets {
+  'polkadot-js': PolkadotJsWalletInstance
+  'talisman': TalismanWalletInstance
+}
+
 interface WalletAccount {
   seed: string
   name?: string // Default: 'Test Account'
   password?: string // Default: 'h3llop0lkadot!'
 }
-
-await importAccount({
-  seed: 'your twelve word seed phrase here...',
-  name: 'My Test Account',
-  password: 'securePassword123'
-})
 ```
 
-#### `authorize()`
-Authorize the dApp to connect with the wallet. Call this after triggering wallet connection from your dApp.
+**Usage:**
 
 ```typescript
-await authorize()
-```
+test('example', async ({ page, wallets }) => {
+  const polkadotJs = wallets['polkadot-js'] // Type: PolkadotJsWalletInstance
 
-#### `approveTx(options?)`
-Approve a transaction with the wallet password.
+  // Import mnemonic (available on all wallets)
+  await polkadotJs.importMnemonic({
+    seed: 'bottom drive obey lake curtain smoke basket hold race lonely fit walk',
+    name: 'Test Account',
+    password: 'securePassword123'
+  })
 
-```typescript
-await approveTx({ password: 'myPassword' })
+  await page.goto('http://localhost:3000')
+  await polkadotJs.authorize()
+  await polkadotJs.approveTx({ password: 'securePassword123' })
+})
 
-// Or use default password
-await approveTx()
-```
+// Talisman-specific features
+test('talisman example', async ({ page, wallets }) => {
+  const talisman = wallets.talisman // Type: TalismanWalletInstance
 
-### Utility Functions
+  // Talisman-specific method: import Ethereum private key
+  await talisman.importEthPrivateKey({
+    privateKey: '0x...',
+    name: 'My Account',
+    password: 'mypassword'
+  })
 
-#### `downloadAndExtractPolkadotExtension(targetDir?)`
-Download and extract Polkadot JS extension to specified directory.
+  // Common methods also available
+  await talisman.authorize({ accountName: 'My Account' })
+  await talisman.approveTx()
+})
+```
 
-```typescript
-import { downloadAndExtractPolkadotExtension } from '@avalix/chroma'
+## Configuration
 
-// Download to custom directory
-const extensionPath = await downloadAndExtractPolkadotExtension('./my-extensions')
+### Extension Download
+Run the download command to get the required wallet extensions:
 
-// Download to default directory (./.chroma)
-const extensionPath = await downloadAndExtractPolkadotExtension()
+```bash
+npx @avalix/chroma download-extensions
 ```
 
-### TypeScript Types
+Extensions will be downloaded to `./.chroma` directory in your project root. Add this directory to your `.gitignore`:
 
-```typescript
-import type {
-  ChromaTestOptions,
-  WalletAccount,
-  WalletConfig,
-  WalletFixtures,
-  WalletType
-} from '@avalix/chroma'
+```gitignore
+.chroma/
 ```
 
-## Configuration
-
-### Default Directory
-The Polkadot JS extension will be automatically downloaded to `./.chroma` directory in your project root. You can customize this by:
-
-1. Using `downloadAndExtractPolkadotExtension('./custom-path')`
-2. Using `createWalletTest()` with `walletConfig.customPath`
-
 ### Browser Settings
 - **Headless Mode**: Disabled by default for better debugging
 - **Slow Motion**: 150ms delay between actions (configurable)
-- **Extension Loading**: Automatically loads only the Polkadot JS extension
+- **Extension Loading**: Automatically loads configured wallet extensions
 
 ## Supported Wallets
 
 | Wallet | Status | Version |
 |--------|--------|---------|
 | Polkadot JS Extension | ✅ Supported | v0.61.7 |
-| Talisman | ⏳ Planned | - |
+| Talisman | ✅ Supported | v3.0.5 |
 | SubWallet | ⏳ Planned | - |
 
 ## Requirements
@@ -201,8 +295,9 @@ The Polkadot JS extension will be automatically downloaded to `./.chroma` direct
 ## Contributing
 
 This project is in active development. Currently focusing on:
-- Polkadot JS Extension support
+- Polkadot JS Extension and Talisman support
 - Core testing fixtures
+- Additional wallet integrations
 - Documentation improvements
 
 ## License

package/dist/index.d.ts

@@ -1,40 +1,64 @@
-import { BrowserContext, BrowserContext as BrowserContext$1, Page, Page as Page$1, expect, test as test$1 } from "@playwright/test";
+import { BrowserContext, Page, expect } from "@playwright/test";
+import * as playwright_test0 from "playwright/test";
 
-//#region src/context-playwright/index.d.ts
-type WalletType = "polkadot-js" | "talisman";
-interface WalletConfig {
-  downloadUrl?: string;
-  customPath?: string;
-}
+//#region src/context-playwright/types.d.ts
+type WalletType = 'polkadot-js' | 'talisman';
 interface WalletAccount {
   seed: string;
   name?: string;
   password?: string;
 }
-interface ChromaTestOptions {
-  walletType?: WalletType;
-  walletConfig?: WalletConfig;
-  headless?: boolean;
-  slowMo?: number;
-}
-interface ExtendedPage extends Page$1 {
-  __extensionContext: BrowserContext$1;
-  __extensionId: string;
+interface WalletConfig {
+  type: WalletType;
+  downloadUrl?: string;
 }
-interface WalletFixtures {
-  page: ExtendedPage;
-  walletType: WalletType;
-  walletConfig: WalletConfig;
-  importAccount: (options: WalletAccount) => Promise<void>;
-  authorize: () => Promise<void>;
+interface BaseWalletInstance {
+  extensionId: string;
+  importMnemonic: (options: WalletAccount) => Promise<void>;
+  authorize: (options?: {
+    accountName?: string;
+  }) => Promise<void>;
   approveTx: (options?: {
     password?: string;
   }) => Promise<void>;
 }
-declare function createWalletTest(options?: ChromaTestOptions): ReturnType<typeof test$1.extend<WalletFixtures>>;
-declare const test: ReturnType<typeof createWalletTest>;
+interface PolkadotJsWalletInstance extends BaseWalletInstance {
+  type: 'polkadot-js';
+}
+interface TalismanWalletInstance extends BaseWalletInstance {
+  type: 'talisman';
+  importEthPrivateKey: (options: {
+    privateKey: string;
+    name?: string;
+    password?: string;
+  }) => Promise<void>;
+}
+interface WalletTypeMap {
+  'polkadot-js': PolkadotJsWalletInstance;
+  'talisman': TalismanWalletInstance;
+}
+type Wallets = WalletTypeMap;
+type ConfiguredWallets<T extends readonly WalletConfig[]> = { [K in T[number]['type']]: WalletTypeMap[K] };
+type ExtendedPage = Page & {
+  __extensionContext: BrowserContext;
+  __walletExtensionIds: Map<string, string>;
+};
+interface ChromaTestOptions<T extends readonly WalletConfig[] = WalletConfig[]> {
+  wallets?: T;
+  headless?: boolean;
+  slowMo?: number;
+}
+interface WalletFixtures<W = Wallets> {
+  page: ExtendedPage;
+  wallets: W;
+}
+interface WalletWorkerFixtures {
+  walletContext: BrowserContext;
+  walletExtensionIds: Map<string, string>;
+}
 //#endregion
-//#region src/context-playwright/download-polkadot-js.d.ts
-declare function downloadAndExtractPolkadotExtension(targetDir?: string): Promise<string>;
+//#region src/context-playwright/index.d.ts
+declare function createWalletTest<const T extends readonly WalletConfig[]>(options?: ChromaTestOptions<T>): playwright_test0.TestType<playwright_test0.PlaywrightTestArgs & playwright_test0.PlaywrightTestOptions & WalletFixtures<T extends readonly WalletConfig[] ? ConfiguredWallets<T> : WalletTypeMap>, playwright_test0.PlaywrightWorkerArgs & playwright_test0.PlaywrightWorkerOptions & WalletWorkerFixtures>;
+declare const test: ReturnType<typeof createWalletTest>;
 //#endregion
-export { type BrowserContext, type ChromaTestOptions, type Page, type WalletAccount, type WalletConfig, type WalletFixtures, type WalletType, createWalletTest, downloadAndExtractPolkadotExtension, expect, test };
+export { createWalletTest, expect, test };