@avalix/chroma 0.0.16 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @avalix/chroma
 
-End-to-end testing library for Polkadot wallet interactions using Playwright.
+End-to-end testing library for Polkadot, Ethereum, and Solana wallet interactions using Playwright.
 
 ## Documentation
 
@@ -54,10 +54,10 @@ test('connect wallet and sign transaction', async ({ page, wallets }) => {
 
   await page.goto('http://localhost:3000')
   await page.click('button:has-text("Connect Wallet")')
-  await metamask.authorize()
+  await metamask.approve()
 
   await page.click('button:has-text("Send Transaction")')
-  await metamask.confirm()
+  await metamask.approve()
 
   await expect(page.locator('.transaction-success')).toBeVisible()
 })
@@ -80,10 +80,110 @@ test('multi-wallet test', async ({ page, wallets }) => {
   await talisman.importEthPrivateKey({ privateKey: '0x...', name: 'Bob' })
 
   await page.goto('http://localhost:3000')
-  await metamask.authorize()
+  await metamask.approve()
 })
 ```
 
+### Setup Project Pattern
+
+By default the browser context uses a temporary profile, so wallet state (imported accounts, passwords) is lost between runs. To import a seed phrase **once** and reuse the prepared state across all your specs, combine the `userDataDir` and `cloneUserDataDirFrom` options with [Playwright's setup project pattern](https://playwright.dev/docs/test-global-setup-teardown).
+
+A setup project writes the prepared profile to a shared dir; spec projects then point a `userDataDir` at it (or clone it per worker for parallelism).
+
+#### 1. Setup project — seed once
+
+The setup test guards onboarding with a sentinel file so re-running `playwright test` doesn't try to onboard an already-prepared profile (the second run would deadlock on a UI that no longer matches the import flow). Delete `.cache/wallet-setup` to force a fresh seed.
+
+```typescript
+// metamask.setup.ts
+import fs from 'node:fs'
+import path from 'node:path'
+import { createWalletTest } from '@avalix/chroma'
+
+const SETUP_DIR = '.cache/wallet-setup'
+const SENTINEL = path.join(SETUP_DIR, '.chroma-onboarded')
+
+const setup = createWalletTest({
+  wallets: [{ type: 'metamask' }],
+  userDataDir: SETUP_DIR,
+})
+
+setup('seed metamask', async ({ wallets }) => {
+  if (fs.existsSync(SENTINEL))
+    return
+
+  await wallets.metamask.importSeedPhrase({
+    seedPhrase: 'test test test test test test test test test test test junk',
+  })
+  fs.writeFileSync(SENTINEL, '')
+})
+```
+
+#### 2. Shared spec fixtures
+
+Spec files import a shared `test` factory pointed at the prepared profile. Because MetaMask boots into a locked state on a previously-onboarded profile, each spec must call `wallets.metamask.unlock()` once (it's idempotent — when MetaMask is already unlocked the call is a no-op). On unlock, the MetaMask side panel is left open for the rest of the test session.
+
+```typescript
+// fixtures.ts — shared by your spec files
+import { createWalletTest } from '@avalix/chroma'
+
+export const test = createWalletTest({
+  wallets: [{ type: 'metamask' }],
+  userDataDir: '.cache/wallet-setup',
+})
+
+export { expect } from '@playwright/test'
+```
+
+```typescript
+// some.spec.ts
+import { test } from './fixtures'
+
+test('connect and sign', async ({ page, wallets }) => {
+  const metamask = wallets.metamask
+
+  await page.goto('http://localhost:3000')
+  await metamask.unlock()
+
+  await page.click('button:has-text("Connect Wallet")')
+  await metamask.approve()
+
+  await page.click('button:has-text("Sign Message")')
+  await metamask.approve()
+})
+```
+
+#### 3. Wire up the projects
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 1,
+  projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    {
+      name: 'metamask',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+    },
+  ],
+})
+```
+
+#### Parallel workers (advanced)
+
+Chrome locks `userDataDir`, so multiple workers can't share the same path concurrently. Use `cloneUserDataDirFrom` plus a per-worker `userDataDir` to give each worker its own copy of the prepared profile:
+
+```typescript
+export const test = createWalletTest({
+  wallets: [{ type: 'metamask' }],
+  userDataDir: ({ workerIndex }) => `.cache/wallet-w${workerIndex}`,
+  cloneUserDataDirFrom: '.cache/wallet-setup',
+})
+```
+
+Set `workers: undefined` (or higher) once you've validated parallel runs in your project — interaction between cloned profiles, MetaMask's locked-state recovery, and Playwright's side-panel detection is still being hardened.
+
 ## Features
 
 - **Easy Extension Setup** - Download wallet extensions with a single command

package/dist/index.d.mts

@@ -18,6 +18,7 @@ type JUnitReporterOptions = {
   outputFile?: string;
   stripANSIControlSequences?: boolean;
   includeProjectInTestName?: boolean;
+  includeRetries?: boolean;
 };
 type JsonReporterOptions = {
   outputFile?: string;
@@ -31,6 +32,7 @@ type HtmlReporterOptions = {
   title?: string;
   noSnippets?: boolean;
   noCopyPrompt?: boolean;
+  doNotInlineAssets?: boolean;
 };
 type ReporterDescription = Readonly<['blob'] | ['blob', BlobReporterOptions] | ['dot'] | ['line'] | ['list'] | ['list', ListReporterOptions] | ['github'] | ['junit'] | ['junit', JUnitReporterOptions] | ['json'] | ['json', JsonReporterOptions] | ['html'] | ['html', HtmlReporterOptions] | ['null'] | [string] | [string, any]>;
 type UseOptions<TestArgs, WorkerArgs> = Partial<WorkerArgs> & Partial<TestArgs>;
@@ -226,6 +228,12 @@ interface TestProject<TestArgs = {}, WorkerArgs = {}> {
        * for details.
        */
       pathTemplate?: string;
+      /**
+       * Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to
+       * adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by
+       * including an explicit `/children` property.
+       */
+      children?: "contain" | "equal" | "deep-equal";
     };
     /**
      * Configuration for the
@@ -711,6 +719,10 @@ interface FullProject<TestArgs = {}, WorkerArgs = {}> {
    * See [testProject.grepInvert](https://playwright.dev/docs/api/class-testproject#test-project-grep-invert).
    */
   grepInvert: null | RegExp | Array<RegExp>;
+  /**
+   * See [testProject.ignoreSnapshots](https://playwright.dev/docs/api/class-testproject#test-project-ignore-snapshots).
+   */
+  ignoreSnapshots: boolean;
   /**
    * See [testProject.metadata](https://playwright.dev/docs/api/class-testproject#test-project-metadata).
    */
@@ -1101,6 +1113,12 @@ interface TestConfig<TestArgs = {}, WorkerArgs = {}> {
        * for details.
        */
       pathTemplate?: string;
+      /**
+       * Controls how children of the snapshot root are matched against the actual accessibility tree. This is equivalent to
+       * adding a `/children` property at the top of every aria snapshot template. Individual snapshots can override this by
+       * including an explicit `/children` property.
+       */
+      children?: "contain" | "equal" | "deep-equal";
     };
     /**
      * Configuration for the
@@ -6708,6 +6726,7 @@ interface PlaywrightWorkerOptions {
    * - `'retain-on-failure'`: Record trace for each test. When test run passes, remove the recorded trace.
    * - `'retain-on-first-failure'`: Record trace for the first run of each test, but not for retries. When test run
    *   passes, remove the recorded trace.
+   * - `'retain-on-failure-and-retries'`: Record trace for each test run. Retains all traces when an attempt fails.
    *
    * For more control, pass an object that specifies `mode` and trace features to enable.
    *
@@ -6745,6 +6764,10 @@ interface PlaywrightWorkerOptions {
    * down to fit into 800x800. If `viewport` is not configured explicitly the video size defaults to 800x450. Actual
    * picture of each page will be scaled down if necessary to fit the specified size.
    *
+   * To annotate actions in the video, pass `show` with `action` and/or `test` sub-options. The `action` option controls
+   * visual highlights on interacted elements with an optional `delay` in milliseconds (defaults to `500`). The `test`
+   * option controls which test information is displayed as a status overlay.
+   *
    * **Usage**
    *
    * ```js
@@ -6763,10 +6786,22 @@ interface PlaywrightWorkerOptions {
   video: VideoMode | /** deprecated */'retry-with-video' | {
     mode: VideoMode;
     size?: ViewportSize;
+    show?: {
+      actions?: {
+        duration?: number;
+        position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right';
+        fontSize?: number;
+      };
+      test?: {
+        level?: 'file' | 'title' | 'step';
+        position?: 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right';
+        fontSize?: number;
+      };
+    };
   };
 }
 type ScreenshotMode = 'off' | 'on' | 'only-on-failure' | 'on-first-failure';
-type TraceMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-all-retries' | 'retain-on-first-failure';
+type TraceMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-all-retries' | 'retain-on-first-failure' | 'retain-on-failure-and-retries';
 type VideoMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
 /**
  * Playwright Test provides many options to configure test environment,
@@ -7518,6 +7553,11 @@ type ExcludeProps<A, B> = { [K in Exclude<keyof A, keyof B>]: A[K] };
 type CustomProperties<T> = ExcludeProps<T, PlaywrightTestOptions & PlaywrightWorkerOptions & PlaywrightTestArgs & PlaywrightWorkerArgs>;
 type PlaywrightTestProject<TestArgs = {}, WorkerArgs = {}> = Project<PlaywrightTestOptions & CustomProperties<TestArgs>, PlaywrightWorkerOptions & CustomProperties<WorkerArgs>>;
 type PlaywrightTestConfig<TestArgs = {}, WorkerArgs = {}> = Config<PlaywrightTestOptions & CustomProperties<TestArgs>, PlaywrightWorkerOptions & CustomProperties<WorkerArgs>>;
+// Use the global URLPattern type if available (Node.js 22+, modern browsers),
+// otherwise fall back to `never` so it disappears from union types.
+type URLPattern = typeof globalThis extends {
+  URLPattern: infer T;
+} ? T : never;
 type AsymmetricMatcher = Record<string, any>;
 interface AsymmetricMatchers {
   /**
@@ -7703,7 +7743,11 @@ interface AsymmetricMatchers {
  */
 interface GenericAssertions<R> {
   /**
-   * Makes the assertion check for the opposite condition. For example, the following code passes:
+   * Makes the assertion check for the opposite condition.
+   *
+   * **Usage**
+   *
+   * For example, the following code passes:
    *
    * ```js
    * const value = 1;
@@ -7712,6 +7756,34 @@ interface GenericAssertions<R> {
    *
    */
   not: GenericAssertions<R>;
+  /**
+   * Use `resolves` to unwrap the value of a fulfilled promise so any other matcher can be chained. If the promise is
+   * rejected the assertion fails.
+   *
+   * For example, this code tests that the promise resolves and that the resulting value is `'lemon'`:
+   *
+   * ```js
+   * test('resolves to lemon', async () => {
+   *   await expect(Promise.resolve('lemon')).resolves.toBe('lemon');
+   * });
+   * ```
+   *
+   */
+  resolves: GenericAssertions<R>;
+  /**
+   * Use `.rejects` to unwrap the reason of a rejected promise so any other matcher can be chained. If the promise is
+   * fulfilled the assertion fails.
+   *
+   * For example, this code tests that the promise rejects with reason `'octopus'`:
+   *
+   * ```js
+   * test('rejects to octopus', async () => {
+   *   await expect(Promise.reject(new Error('octopus'))).rejects.toThrow('octopus');
+   * });
+   * ```
+   *
+   */
+  rejects: GenericAssertions<R>;
   /**
    * Compares value with
    * [`expected`](https://playwright.dev/docs/api/class-genericassertions#generic-assertions-to-be-option-expected) by
@@ -8339,8 +8411,11 @@ interface APIResponseAssertions {
    */
   toBeOK(): Promise<void>;
   /**
-   * Makes the assertion check for the opposite condition. For example, this code tests that the response status is not
-   * successful:
+   * Makes the assertion check for the opposite condition.
+   *
+   * **Usage**
+   *
+   * For example, this code tests that the response status is not successful:
    *
    * ```js
    * await expect(response).not.toBeOK();
@@ -9304,8 +9379,11 @@ interface LocatorAssertions {
     timeout?: number;
   }): Promise<void>;
   /**
-   * Makes the assertion check for the opposite condition. For example, this code tests that the Locator doesn't contain
-   * text `"error"`:
+   * Makes the assertion check for the opposite condition.
+   *
+   * **Usage**
+   *
+   * For example, this code tests that the Locator doesn't contain text `"error"`:
    *
    * ```js
    * await expect(locator).not.toContainText('error');
@@ -9389,6 +9467,9 @@ interface PageAssertions {
    * // Check for the page URL to contain 'doc', followed by an optional 's', followed by '/'
    * await expect(page).toHaveURL(/docs?\//);
    *
+   * // Check for the page URL to match the URL pattern
+   * await expect(page).toHaveURL(new URLPattern({ pathname: '/docs/*' }));
+   *
    * // Check for the predicate to be satisfied
    * // For example: verify query strings
    * await expect(page).toHaveURL(url => {
@@ -9404,7 +9485,7 @@ interface PageAssertions {
    * against the current browser URL.
    * @param options
    */
-  toHaveURL(url: string | RegExp | ((url: URL) => boolean), options?: {
+  toHaveURL(url: string | RegExp | URLPattern | ((url: URL) => boolean), options?: {
     /**
      * Whether to perform case-insensitive match.
      * [`ignoreCase`](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-url-option-ignore-case)
@@ -9418,8 +9499,11 @@ interface PageAssertions {
     timeout?: number;
   }): Promise<void>;
   /**
-   * Makes the assertion check for the opposite condition. For example, this code tests that the page URL doesn't
-   * contain `"error"`:
+   * Makes the assertion check for the opposite condition.
+   *
+   * **Usage**
+   *
+   * For example, this code tests that the page URL doesn't contain `"error"`:
    *
    * ```js
    * await expect(page).not.toHaveURL('error');
@@ -9956,9 +10040,8 @@ declare function createMetaMaskWallet(extensionId: string, context: BrowserConte
     seedPhrase: string;
   }) => Promise<void>;
   unlock: () => Promise<void>;
-  authorize: () => Promise<void>;
+  approve: () => Promise<void>;
   reject: () => Promise<void>;
-  confirm: () => Promise<void>;
 };
 type PolkadotJsWalletInstance = ReturnType<typeof createPolkadotJsWallet>;
 type TalismanWalletInstance = ReturnType<typeof createTalismanWallet>;
@@ -9973,31 +10056,43 @@ interface WalletAccount {
 }
 interface WalletConfig {
   type: WalletType;
-  downloadUrl?: string;
 }
 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] };
-type ExtendedPage = Page & {
-  __extensionContext: BrowserContext;
-  __walletExtensionIds: Map<string, string>;
-};
 interface ChromaTestOptions<T extends readonly WalletConfig[] = WalletConfig[]> {
   wallets?: T;
   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;
 }
-interface WalletFixtures<W = Wallets> {
-  page: ExtendedPage;
+interface WalletFixtures<W = WalletTypeMap> {
+  page: Page;
   wallets: W;
 }
 interface WalletWorkerFixtures {
   walletContext: BrowserContext;
-  walletExtensionIds: Map<string, string>;
+  walletExtensionIds: Map<WalletType, string>;
 }
 //#endregion
 //#region src/context-playwright/index.d.ts