@marigoldlabs/web3-tester 0.1.1 → 0.4.1

package/package.json

@@ -1,10 +1,23 @@
 {
   "name": "@marigoldlabs/web3-tester",
-  "version": "0.1.1",
-  "private": false,
+  "version": "0.4.1",
   "type": "module",
   "description": "A Playwright, Anvil, and Viem based Web3 E2E harness with an injected programmable wallet provider.",
-  "license": "UNLICENSED",
+  "license": "MIT",
+  "keywords": [
+    "playwright",
+    "anvil",
+    "viem",
+    "metamask",
+    "walletconnect",
+    "web3",
+    "ethereum",
+    "e2e",
+    "testing",
+    "wallet",
+    "eip-1193",
+    "dapp"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AndyMarigoldLabs/web3-tester.git"
@@ -24,6 +37,22 @@
       "types": "./dist/anvil.d.ts",
       "import": "./dist/anvil.js"
     },
+    "./erc20": {
+      "types": "./dist/erc20.d.ts",
+      "import": "./dist/erc20.js"
+    },
+    "./matchers": {
+      "types": "./dist/matchers.d.ts",
+      "import": "./dist/matchers.js"
+    },
+    "./walletconnect": {
+      "types": "./dist/walletconnect.d.ts",
+      "import": "./dist/walletconnect.js"
+    },
+    "./transactions": {
+      "types": "./dist/transactions.d.ts",
+      "import": "./dist/transactions.js"
+    },
     "./fixtures": {
       "types": "./dist/fixtures.d.ts",
       "import": "./dist/fixtures.js"
@@ -43,30 +72,57 @@
     "./real-wallet": {
       "types": "./dist/real-wallet.d.ts",
       "import": "./dist/real-wallet.js"
-    }
+    },
+    "./real-wallet-fixtures": {
+      "types": "./dist/real-wallet-fixtures.d.ts",
+      "import": "./dist/real-wallet-fixtures.js"
+    },
+    "./metamask-extension": {
+      "types": "./dist/metamask-extension.d.ts",
+      "import": "./dist/metamask-extension.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20.0.0"
   },
   "files": [
     "dist",
-    "docs",
     "examples",
     "README.md",
+    "LICENSE",
     ".env.example"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "build:contracts": "node scripts/build-contracts.mjs",
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "prepare": "npm run build",
-    "test": "playwright test",
+    "test": "playwright test --project=library",
+    "test:fjord": "playwright test --project=fjord",
+    "test:all": "playwright test",
+    "smoke:real-wallet": "node scripts/real-wallet-smoke.mjs",
     "typecheck": "tsc --noEmit",
     "verify": "npm run typecheck && npm run build && npm test"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.56.0",
+    "@walletconnect/sign-client": ">=2.17 <3",
+    "@walletconnect/types": ">=2.17 <3",
+    "@walletconnect/utils": ">=2.17 <3",
     "viem": ">=2.39.3 <3"
   },
+  "peerDependenciesMeta": {
+    "@walletconnect/sign-client": { "optional": true },
+    "@walletconnect/types": { "optional": true },
+    "@walletconnect/utils": { "optional": true }
+  },
   "devDependencies": {
     "@playwright/test": "^1.56.1",
     "@types/node": "^24.10.1",
+    "@walletconnect/sign-client": "^2.23.9",
+    "@walletconnect/types": "^2.23.9",
+    "@walletconnect/utils": "^2.23.9",
     "typescript": "^5.9.3",
     "viem": "^2.52.0"
   }

package/docs/API.md

@@ -1,223 +0,0 @@
-# API Reference
-
-This package exposes two Playwright fixture families and one real-wallet adapter:
-
-- `fixtures`: local deterministic Anvil tests.
-- `live-fixtures`: live Sepolia tests that sign with a runtime-only private key.
-- `real-wallet`: persistent Chromium and MetaMask automation for fully in-UI Web3 tests.
-
-## Local Fixtures
-
-```ts
-import { expect, test } from '@marigoldlabs/web3-tester/fixtures';
-```
-
-Fixtures:
-
-| Fixture | Scope | Description |
-| --- | --- | --- |
-| `wallet` | test | `MockWalletController` injected into the page before app scripts run. |
-| `chain` | worker | `ChainController` connected to the worker's Anvil node. |
-| `anvil` | worker | Running `AnvilInstance`. |
-| `walletOptions` | option | Per-test overrides for wallet identity and behavior. |
-| `anvilOptions` | option | Worker-level Anvil runtime overrides. |
-
-Each `wallet` test snapshots chain state before test code runs and reverts after the test finishes.
-
-## Live Fixtures
-
-```ts
-import { expect, test } from '@marigoldlabs/web3-tester/live-fixtures';
-```
-
-Fixtures:
-
-| Fixture | Scope | Description |
-| --- | --- | --- |
-| `wallet` | test | `MockWalletController` backed by a real Sepolia private-key signer. |
-| `liveClient` | test | `PrivateKeyRpcClient` for Sepolia RPC and transaction submission. |
-
-Required environment:
-
-```bash
-FJORD_PRIVATE_KEY=<runtime-only-private-key>
-```
-
-Optional:
-
-```bash
-SEPOLIA_RPC_URL=https://...
-```
-
-## Real Wallet
-
-```ts
-import { launchRealWallet } from '@marigoldlabs/web3-tester/real-wallet';
-
-const session = await launchRealWallet({
-  extensionPath: process.env.FJORD_REAL_WALLET_EXTENSION_PATH as string,
-  profileDir: process.env.FJORD_REAL_WALLET_PROFILE_DIR as string,
-  expectedAddress: process.env.FJORD_REAL_WALLET_ADDRESS,
-  setup: process.env.FJORD_REAL_WALLET_PASSWORD
-    ? {
-        password: process.env.FJORD_REAL_WALLET_PASSWORD,
-        seedPhrase: process.env.FJORD_REAL_WALLET_SECRET_RECOVERY_PHRASE,
-      }
-    : undefined,
-});
-```
-
-`launchRealWallet` starts a persistent Chromium context with the configured unpacked MetaMask extension. `profileDir` can be either a dedicated Playwright user data directory or a Chrome profile directory such as `Default` or `Profile 1`; Chrome profile paths are mapped back to their user data root and launched with `--profile-directory`.
-
-Options:
-
-| Option | Description |
-| --- | --- |
-| `extensionPath` | Required path to the unpacked MetaMask extension. |
-| `profileDir` | Required persistent Chromium user data directory, or a Chrome profile directory. |
-| `baseURL` | Optional Playwright base URL for pages opened from the returned context. |
-| `expectedAddress` | Optional account address assertion after unlock/import. |
-| `extensionName` | Extension name used to resolve the extension ID. Defaults to `MetaMask`. |
-| `headless` | Chromium headless setting. Defaults to `false` because extensions require headed Chromium in normal use. |
-| `setup.password` | Password used to unlock MetaMask, or to import a seed phrase when onboarding is visible. |
-| `setup.seedPhrase` | Seed phrase used only if MetaMask opens on onboarding. |
-| `slowMo` | Optional Playwright slow-motion delay. |
-
-Returned session methods:
-
-| Method | Description |
-| --- | --- |
-| `connectToDapp(accounts?)` | Approves a dapp connection request in MetaMask. |
-| `confirmSignature()` | Confirms a pending signature request. |
-| `confirmTransaction(options?)` | Confirms a pending transaction request. |
-| `approveTokenPermission(options?)` | Approves a pending ERC-20 spending permission request. |
-| `rejectSignature()` | Rejects a pending signature request. |
-| `rejectTransaction()` | Rejects a pending transaction request. |
-| `getAccountAddress()` | Returns the selected MetaMask account. |
-| `close()` | Closes the persistent browser context. |
-
-## MockWalletController
-
-```ts
-const wallet = new MockWalletController(page, rpcClient, {
-  accounts: ['0x...'],
-  chainId: 31337,
-  autoApprove: true,
-  connected: true,
-});
-await wallet.injectMockProvider();
-```
-
-Properties:
-
-| Property | Type | Description |
-| --- | --- | --- |
-| `primaryAccount` | `Address` | First exposed account. |
-| `currentChainId` | `Hex` | Current EIP-1193 chain ID. |
-| `providerInfo` | `WalletProviderInfo` | Primary EIP-6963 provider metadata. |
-| `providerInfos` | `WalletProviderInfo[]` | All announced provider metadata. |
-
-Methods:
-
-| Method | Description |
-| --- | --- |
-| `injectMockProvider()` | Adds the RPC bridge and injects `window.ethereum`. |
-| `autoApprove(enabled)` | Toggles automatic approval for future signing methods. |
-| `simulateRejection(methods?, message?)` | Rejects the next matching request with code `4001`. |
-| `setAccounts(accounts)` | Updates accounts and emits `accountsChanged`. |
-| `disconnect()` | Emits `accountsChanged` and `disconnect`. |
-| `reconnect()` | Emits `connect` and `accountsChanged`. |
-| `switchNetwork(chainId)` | Updates chain ID and emits `chainChanged`. |
-
-Supported wallet methods include:
-
-- `eth_accounts`
-- `eth_requestAccounts`
-- `eth_chainId`
-- `net_version`
-- `wallet_getPermissions`
-- `wallet_requestPermissions`
-- `wallet_switchEthereumChain`
-- `wallet_addEthereumChain`
-- `wallet_watchAsset`
-- `metamask_getProviderState`
-- `eth_sendTransaction`
-- `personal_sign`
-- `eth_sign`
-- `eth_signTypedData`
-- `eth_signTypedData_v3`
-- `eth_signTypedData_v4`
-
-Unhandled methods are forwarded to the configured RPC client.
-
-## ChainController
-
-`ChainController` wraps a Viem Anvil test client.
-
-| Method | Description |
-| --- | --- |
-| `snapshot()` | Calls `evm_snapshot`. |
-| `revert(id)` | Calls `evm_revert`. |
-| `accounts()` | Returns Anvil default accounts. |
-| `request(request)` | Sends a raw JSON-RPC request. |
-| `impersonateAccount(address)` | Starts Anvil account impersonation. |
-| `stopImpersonatingAccount(address)` | Stops Anvil account impersonation. |
-| `setBalance(address, value)` | Sets an account balance. |
-| `fastForward(seconds)` | Increases time and mines one block. |
-| `mine(blocks)` | Mines blocks. |
-
-The underlying Viem test client is available as `chain.client` for advanced calls.
-
-## AnvilInstance
-
-```ts
-const anvil = await AnvilInstance.start({
-  runtime: 'docker',
-  port: 8546,
-  chainId: 31337,
-});
-
-await anvil.stop();
-```
-
-Options:
-
-| Option | Description |
-| --- | --- |
-| `runtime` | `binary` or `docker`. |
-| `executable` | Anvil binary path for `binary` runtime. |
-| `dockerImage` | Foundry Docker image. |
-| `host` | Host interface. |
-| `port` | Host RPC port. |
-| `chainId` | Local chain ID. |
-| `accounts` | Number of generated accounts. |
-| `balance` | ETH balance per generated account. |
-| `mnemonic` | Deterministic mnemonic. |
-| `blockTime` | Optional automatic mining interval. |
-| `forkUrl` | Optional fork RPC URL. |
-| `timeoutMs` | Startup timeout. |
-| `silent` | Suppress or stream Anvil logs. |
-
-## PrivateKeyRpcClient
-
-`PrivateKeyRpcClient` is for live-chain QA only.
-
-```ts
-const client = new PrivateKeyRpcClient({
-  privateKey: process.env.FJORD_PRIVATE_KEY as `0x${string}`,
-  rpcUrl: process.env.SEPOLIA_RPC_URL,
-});
-```
-
-It supports:
-
-- `personal_sign`
-- `eth_sign`
-- `eth_signTypedData_v4`
-- `eth_sendTransaction`
-- read-only RPC forwarding through Viem public client
-
-It records sent transaction hashes in:
-
-- `sentTransactions`
-- `sentTransactionRequests`

package/docs/ARCHITECTURE.md

@@ -1,81 +0,0 @@
-# Architecture
-
-Web3 Tester replaces extension automation with a programmable provider and deterministic chain control.
-
-## Local Test Flow
-
-1. Playwright creates a worker.
-2. The worker fixture starts Anvil on a unique port.
-3. The test fixture snapshots Anvil state with `evm_snapshot`.
-4. `MockWalletController` exposes a Playwright function bridge.
-5. `page.addInitScript` injects `window.ethereum` before dApp scripts load.
-6. The dApp sends EIP-1193 requests to `window.ethereum.request`.
-7. The injected provider forwards requests through the Playwright bridge.
-8. The Node-side controller approves, rejects, emits events, or forwards RPC to Anvil.
-9. The fixture reverts the chain with `evm_revert`.
-10. The worker fixture stops Anvil after worker completion.
-
-## Why This Avoids Synpress-Style Flakiness
-
-No browser extension is installed. There is no extension popup, no wallet UI selector, no browser-extension process boundary, and no cached wallet profile. Tests exercise the dApp's wallet integration contract directly.
-
-## Browser Injection
-
-The injected provider implements the wallet behavior expected by most dApps:
-
-- `window.ethereum`
-- `request`
-- `send`
-- `sendAsync`
-- `on`
-- `once`
-- `removeListener`
-- `removeAllListeners`
-- `_metamask.isUnlocked`
-- EIP-6963 `announceProvider`
-
-The injected script is installed with `page.addInitScript`, so it exists before the application bundle executes. It is also evaluated immediately for pages that have already loaded.
-
-## RPC Boundary
-
-Browser code cannot access Node objects directly. The harness uses:
-
-```ts
-page.exposeFunction('__invisibleWalletRpcBridge', async (request) => {
-  return controller.handleRpcRequest(request);
-});
-```
-
-The browser receives only a serialized success or error envelope. Provider-shaped errors are rehydrated in the browser with their original `code`, `message`, and optional `data`.
-
-## Chain Isolation
-
-Local tests isolate state with both process and chain controls:
-
-- One Anvil node per Playwright worker.
-- One chain snapshot per `wallet` test.
-- A revert after each `wallet` test.
-- Unique worker ports derived from `ANVIL_PORT + workerIndex`.
-
-This prevents nonce bleeding and lets Playwright run tests in parallel.
-
-## Live Sepolia Mode
-
-Live mode intentionally does not use Anvil snapshots. It uses a runtime-only private key through `PrivateKeyRpcClient` and sends real Sepolia transactions only when an explicit opt-in flag is set.
-
-Live mutation specs should always:
-
-- Check the required opt-in env var.
-- Use unique QA names.
-- Record transaction hashes.
-- Avoid committing any private key.
-- Continue to the next doc line after a product failure.
-
-## Package Boundaries
-
-Reusable package code lives in `src/`. Fjord-specific tests and reports live outside the package export surface:
-
-- Exported: `src/*`
-- Not exported: `tests/*`, `reports/*`, `tmp/*`, `tools/*`
-
-The `files` field in `package.json` keeps install output focused on `dist`, `docs`, `examples`, `README.md`, and `.env.example`.

package/docs/CONSUMING_FROM_FJORD.md

@@ -1,123 +0,0 @@
-# Consuming Web3 Tester From Fjord V4
-
-This guide covers adding the published package to Fjord v4 as a dependency.
-
-## Install
-
-```bash
-npm install --save-dev @marigoldlabs/web3-tester
-```
-
-For a pinned dependency, use an exact package version:
-
-```bash
-npm install --save-dev @marigoldlabs/web3-tester@<version>
-```
-
-## Playwright Config
-
-Use Fjord's existing Playwright config if it already exists. The important parts are:
-
-```ts
-import { defineConfig, devices } from '@playwright/test';
-
-export default defineConfig({
-  fullyParallel: true,
-  retries: process.env.CI ? 2 : 0,
-  use: {
-    baseURL: process.env.DAPP_URL ?? 'http://localhost:3000',
-    trace: 'on-first-retry',
-  },
-  projects: [
-    {
-      name: 'chromium',
-      use: { ...devices['Desktop Chrome'] },
-    },
-  ],
-});
-```
-
-## Local Deterministic Tests
-
-```ts
-import { expect, test } from '@marigoldlabs/web3-tester/fixtures';
-
-test('connects through the injected provider', async ({ page, wallet }) => {
-  await page.goto('/');
-
-  await page.getByRole('button', { name: /connect wallet/i }).click();
-  await page.getByText('Mock Wallet').click();
-
-  await expect(page.getByText(wallet.primaryAccount.slice(0, 6))).toBeVisible();
-});
-```
-
-## Test Options
-
-Customize provider identity for wallet selector coverage:
-
-```ts
-test.use({
-  walletOptions: {
-    providerInfo: { name: 'MetaMask', rdns: 'io.metamask' },
-    additionalProviders: [
-      { name: 'Rabby', rdns: 'io.rabby' },
-      { name: 'Rainbow', rdns: 'me.rainbow' },
-    ],
-  },
-});
-```
-
-Customize Anvil:
-
-```ts
-test.use({
-  anvilOptions: {
-    runtime: 'docker',
-    chainId: 31337,
-    forkUrl: process.env.ANVIL_FORK_URL,
-  },
-});
-```
-
-## Live Sepolia Tests
-
-```ts
-import { expect, test } from '@marigoldlabs/web3-tester/live-fixtures';
-
-test.skip(!process.env.FJORD_PRIVATE_KEY, 'FJORD_PRIVATE_KEY is required.');
-
-test('loads the Sepolia account', async ({ page, wallet }) => {
-  await page.goto('/');
-  await expect(page.getByText(wallet.primaryAccount.slice(0, 6))).toBeVisible();
-});
-```
-
-Run with:
-
-```powershell
-$env:FJORD_PRIVATE_KEY = '<runtime-only-key>'
-$env:SEPOLIA_RPC_URL = '<optional-rpc-url>'
-npm test
-```
-
-## Mutation Gates
-
-Use explicit flags for anything that spends funds or mutates backend state:
-
-```powershell
-$env:FJORD_RUN_TRANSACTIONS = 'true'
-$env:FJORD_MUTATE_STATE = 'true'
-$env:FJORD_PUBLISH_SALES = 'true'
-$env:FJORD_ADMIN_MUTATE = 'true'
-```
-
-Keep destructive or expensive tests behind separate flags so normal CI remains read-only.
-
-## CI Recommendations
-
-- Run deterministic Anvil tests on every PR.
-- Run live Sepolia read-only tests on a scheduled job or protected branch.
-- Run live mutation tests manually with approval.
-- Store `FJORD_PRIVATE_KEY` and `SEPOLIA_RPC_URL` only as CI secrets.
-- Pin the npm dependency to an exact version once Fjord depends on it.

package/docs/FJORD_LIVE_QA.md

@@ -1,87 +0,0 @@
-# Fjord V4 Live QA
-
-The Fjord QA specs in `tests/fjord*.spec.ts` are the working executable version of the manual QA document.
-
-Target:
-
-```text
-https://v4.fjordfoundry.com
-```
-
-Network:
-
-```text
-Sepolia
-```
-
-Any legacy "mainnet" wording in the manual QA doc is treated as Sepolia for this test harness.
-
-## Test Categories
-
-| Category | Specs | Default behavior |
-| --- | --- | --- |
-| Public read-only | `fjord-public`, `fjord`, public parts of other specs | Runs without private key where possible. |
-| Live wallet read-only | `fjord-live-sepolia`, `fjord-auth-edge`, `fjord-partials-live` | Requires `FJORD_PRIVATE_KEY`. |
-| Live transaction | `fjord-live-transaction` | Requires `FJORD_RUN_TRANSACTIONS=true`. |
-| Live mutations | `fjord-live-mutations` | Requires `FJORD_MUTATE_STATE=true`. |
-| Sale publishing | `fjord-live-mutations` publish branch | Requires `FJORD_PUBLISH_SALES=true`. |
-| Admin mutations | `fjord-admin-mutations` | Requires `FJORD_ADMIN_MUTATE=true`. |
-
-## Read-Only Run
-
-```powershell
-$env:FJORD_PRIVATE_KEY = '<runtime-only-key>'
-$env:DAPP_URL = 'https://v4.fjordfoundry.com'
-npm test -- --reporter=list tests/fjord-public.spec.ts tests/fjord-live-sepolia.spec.ts tests/fjord-auth-edge.spec.ts tests/fjord-partials-live.spec.ts
-```
-
-## Live Mutation Run
-
-```powershell
-$env:FJORD_PRIVATE_KEY = '<runtime-only-key>'
-$env:DAPP_URL = 'https://v4.fjordfoundry.com'
-$env:FJORD_MUTATE_STATE = 'true'
-$env:FJORD_QA_RUN_ID = 'YYYYMMDDXX'
-npm test -- --reporter=list tests/fjord-live-mutations.spec.ts
-```
-
-## Sale Publish Attempt
-
-```powershell
-$env:FJORD_PRIVATE_KEY = '<runtime-only-key>'
-$env:FJORD_MUTATE_STATE = 'true'
-$env:FJORD_PUBLISH_SALES = 'true'
-$env:FJORD_QA_RUN_ID = 'YYYYMMDDPX'
-npm test -- --reporter=list tests/fjord-live-mutations.spec.ts
-```
-
-## Admin Mutation Attempt
-
-```powershell
-$env:FJORD_PRIVATE_KEY = '<runtime-only-key>'
-$env:FJORD_ADMIN_MUTATE = 'true'
-npm test -- --reporter=list tests/fjord-admin-mutations.spec.ts
-```
-
-## Reporting Rules
-
-- Record `PASS`, `FAIL`, `PARTIAL`, `BLOCKED`, `NOT RUN`, or `N/A` for every doc line.
-- When a line fails, note the observable behavior and continue to the next line.
-- Do not collapse a doc mismatch into a product failure if the live UI has moved the control.
-- Never paste private keys into reports.
-- Include transaction hashes and deployed QA addresses when they help debugging.
-
-## Current Report Artifacts
-
-- `reports/fjord-full-line-by-line-qa-2026-05-14.md`
-- `reports/fjord-qa-results-2026-05-14.md`
-
-## Known Findings From The 2026-05-14 Run
-
-- ERC-20 deployment from the Fjord UI succeeded.
-- Token supply input minted raw units rather than the expected human-token amount.
-- Fixed-price sale draft creation reached review.
-- The review step did not show the documented full sale summary.
-- Publishing submitted an ERC-20 approval transaction but did not continue to pool creation.
-- Saved QA drafts were not listed in the resume dialog.
-- `/admin/cache` failed loading admin data with backend `401`.

package/docs/RELEASE_CHECKLIST.md

@@ -1,55 +0,0 @@
-# Release Checklist
-
-Use this before publishing a new version or pinning it inside Fjord v4.
-
-## Required
-
-- `npm run typecheck`
-- `npm run build`
-- `npm test`
-- `rg -n "FJORD_PRIVATE_KEY\\s*=\\s*0x[0-9a-fA-F]{64}|PRIVATE_KEY=.*[0-9a-fA-F]{64}" . -g "!node_modules/**" -g "!dist/**" -g "!.npm-cache/**"`
-- Confirm `.env` is ignored.
-- Confirm `dist/` is generated locally but not required in source review unless the team wants committed build output.
-
-## Dependency Consumer Check
-
-From a clean consumer repo:
-
-```bash
-npm install --save-dev @marigoldlabs/web3-tester@<version>
-```
-
-Then import:
-
-```ts
-import { expect, test } from '@marigoldlabs/web3-tester/fixtures';
-```
-
-Run one provider smoke test.
-
-## Live QA Check
-
-Run live tests only with runtime secrets:
-
-```powershell
-$env:FJORD_PRIVATE_KEY = '<runtime-only-key>'
-$env:DAPP_URL = 'https://v4.fjordfoundry.com'
-npm test -- --reporter=list tests/fjord-live-sepolia.spec.ts
-```
-
-Mutation runs require explicit flags and should not be part of default CI.
-
-## Push
-
-```bash
-git status --short
-git add .
-git commit -m "Document and package Web3 tester"
-git push -u origin main
-```
-
-## Publish
-
-```bash
-npm publish --access public
-```