Release 1.0.0 (#55)

* Refactor wallet structure

* Refactor wallet exports and improve configuration structure

* Add test-dapp package with initial configuration and dependencies

* Remove test-contracts package and update test-dapp configuration for Foundry integration

* Update test-dapp configuration and components

* Add ERC-20 token functionality to test-dapp

* Refactor test-dapp to integrate ERC-721 NFT functionality and streamline ERC-20 components

* Add SignMessageSection component to test-dapp for signing messages functionality

* add infra

* Сonditionally display ERC-20 and ERC-721 sections based on environment

* Enhance w3wallets CLI with short aliases and detailed help options

* Enhance withWallets function to derive Chrome extension IDs from manifest.json and improve error handling for service worker initialization

* add metamask functionality

* Fix codestyle

* Update w3wallets package version to 1.0.0-beta.1

* Restore pjs test

* remove backpack

* remove test-app

* fix CI

* Update peer dependency for @playwright/test to version 1.57.0

* Add recursive submodule checkout in Playwright CI workflow

* Refactor start script for test-dapp to improve deployment process

* Enhance start script for test-dapp to build and run Next.js production server; add additional Chrome flags in withWallets for improved performance

* Do not remova pages in fixture

* Update Metamask onboarding page URL and increase button visibility timeout

* Refactor Metamask onboarding process to improve mnemonic input handling and code readability

* Implement configurable action timeout for wallet interactions and update example environment variables

* Refactor Metamask interactions to remove hardcoded timeouts, utilizing default timeout from Wallet class configuration

* Replace Hardhat references with Anvil

* Add erc-20 tests

* fix

* fix format

* Update w3wallets version to 1.0.0-beta.3 in package.json

* One worker on CI

* fix ci

* increase workers

* Squashed commit of the following:

commit 21d9cc03d1e04421da297070025e4aaf12f75174
Author: Max Andreev <maxick20@gmail.com>
Date:   Sun Feb 1 22:23:01 2026 +0500

    update caching

commit d95a5bd4478319e3fc4f28c5c96577d9269d3c5f
Author: Max Andreev <maxick20@gmail.com>
Date:   Sun Feb 1 15:32:07 2026 +0500

    Fix cached wallet restoration for MV3 extensions

    Persist chrome.storage.session data to chrome.storage.local during cache
    build using a helper page to bypass LavaMoat scuttling. Set storageKind
    to "data" so MetaMask reads all state from local storage on restart.
    Add homeUrl to WalletConfig for navigating to extension home in cached
    mode, and update test to handle unlock + "wallet ready" interstitial.

    Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

commit e1da2b33d061c6508aa2b94e8b7bfc1d5b0ae372
Author: Max Andreev <maxick20@gmail.com>
Date:   Sun Feb 1 14:52:56 2026 +0500

    Add example setup, cached test, and gitignore entry

    Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

commit cf365e4736c28d54135b4d20411d203b26f697a2
Author: Max Andreev <maxick20@gmail.com>
Date:   Sun Feb 1 14:41:36 2026 +0500

    Update withWallets to support cached wallet configs

    Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

commit 23c9bbab29f6b298e785dfb74b3ded5233e1804a
Author: Max Andreev <maxick20@gmail.com>
Date:   Sun Feb 1 14:35:33 2026 +0500

    Add cache build logic and CLI command

    Implements buildCacheForSetup and buildAllCaches in src/cache/buildCache.ts,
    adds src/scripts/cache.ts as compiled CLI entry point, and delegates
    `npx w3wallets cache` from download.js to the compiled script.

    Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

commit 9edfdf3b6f6e0853c349f4abe713d69120d17ff0
Author: Max Andreev <maxick20@gmail.com>
Date:   Sun Feb 1 14:26:03 2026 +0500

    Add cache types, constants and defineSetup

    Introduce the cache module foundation: SetupFn/CachedWalletConfig types,
    CACHE_DIR constant, defineSetup helper, and isCachedConfig type guard.

* add cahce script

* add expect timeout

* update playwright

* update lock file

Author: Maksandre

.github/workflows/playwright.yml

@@ -18,7 +18,7 @@ jobs:
     name: "Playwright Tests"
     runs-on: ubuntu-latest
     container:
-      image: mcr.microsoft.com/playwright:v1.57.0-noble
+      image: mcr.microsoft.com/playwright:v1.58.1-noble
     env:
       NEXT_PUBLIC_WC_PROJECT_ID: ${{ secrets.NEXT_PUBLIC_WC_PROJECT_ID }}
     steps:
@@ -55,8 +55,16 @@ jobs:
       - name: 🖨 Copy test envs
         run: cp packages/w3wallets/.env.example packages/w3wallets/.env
 
+      - name: 🔨 Build w3wallets
+        run: yarn build
+        working-directory: packages/w3wallets
+
+      - name: 🗄️ Build wallet cache
+        run: xvfb-run --auto-servernum --server-args='-screen 0 1280x800x24' npx w3wallets cache tests/wallets-cache/
+        working-directory: packages/w3wallets
+
       - name: 🧪 Run tests
-        run: xvfb-run --auto-servernum --server-args='-screen 0 1280x800x24' yarn test
+        run: xvfb-run --auto-servernum --server-args='-screen 0 1280x800x24' yarn test:ci
 
       - name: Upload test artifacts
         uses: actions/upload-artifact@v4

package.json

@@ -10,7 +10,8 @@
     "deploy": "yarn workspace @w3wallets/test-dapp deploy",
     "build": "yarn workspace w3wallets build",
     "download-wallets": "yarn workspace w3wallets download-wallets",
-    "test": "yarn workspace w3wallets test"
+    "test": "yarn workspace w3wallets test",
+    "test:ci": "yarn workspace w3wallets test:ci"
   },
   "packageManager": "yarn@4.6.0",
   "dependencies": {

packages/w3wallets/.env.example

@@ -3,4 +3,5 @@ ETHEREUM_PRIVATE_KEY1=0x903518e191f3843d017f0f9611cfdd27c655565917887faf2762549e
 ETHEREUM_MNEMONIC2=typical flock crash unique wage turtle become trim legend diet dance kitchen
 ETHEREUM_PRIVATE_KEY2=0xbf80a3a6906d48c828b1f3a71ee529092375557f3ab4d3088f1e9495cdb7b624
 SUBSTRATE_SEED=focus inspire onion claw ski jaguar kidney screen bike kiss icon aerobic
-W3WALLETS_ACTION_TIMEOUT=60000
+W3WALLETS_ACTION_TIMEOUT=60000
+W3WALLETS_EXPECT_TIMEOUT=60000

packages/w3wallets/README.md

@@ -105,6 +105,65 @@ test("Can connect MetaMask to dApp", async ({ page, metamask }) => {
 });
 ```
 
+## Caching
+
+Wallet onboarding can be slow. Caching lets you run the setup once and reuse the browser profile across tests.
+
+#### 1. Create a setup file
+
+Create a `*.cache.ts` file in a `wallets-cache/` directory (default):
+
+```ts
+// wallets-cache/default.cache.ts
+import { prepareWallet, metamask } from "w3wallets";
+
+export default prepareWallet(metamask, async (wallet, page) => {
+  await wallet.onboard("your seed phrase ...", "YourPassword123!");
+});
+```
+
+#### 2. Build the cache
+
+```sh
+npx w3wallets cache
+```
+
+<details>
+<summary>CLI Options</summary>
+
+```
+USAGE:
+  npx w3wallets cache [OPTIONS] [directory]
+
+OPTIONS:
+  -f, --force   Force rebuild even if cache exists
+  --headed      Run browser in headed mode
+  directory     Directory containing *.cache.{ts,js} files (default: ./wallets-cache/)
+```
+
+</details>
+
+The cached profiles are stored in `.w3wallets/cache/`. The `.w3wallets` directory should already be in `.gitignore`.
+
+#### 3. Use cached wallets in tests
+
+Import the setup and pass it to `withWallets`:
+
+```ts
+import { test as base, expect } from "@playwright/test";
+import { withWallets } from "w3wallets";
+import cachedMetamask from "./wallets-cache/default.cache";
+
+const test = withWallets(base, cachedMetamask);
+
+test("wallet is ready", async ({ metamask }) => {
+  await metamask.unlock("YourPassword123!");
+  // wallet is already onboarded
+});
+```
+
+> **Note:** All wallets in a test must be either all cached or all non-cached.
+
 ## Configuration
 
 Configure library behavior via environment variables:

packages/w3wallets/package.json

@@ -1,7 +1,7 @@
 {
   "name": "w3wallets",
   "description": "browser wallets for playwright",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "homepage": "https://github.com/Maksandre/w3wallets",
@@ -31,7 +31,7 @@
   "bin": "./src/scripts/download.js",
   "scripts": {
     "download-wallets": "npx w3wallets pjs mm",
-    "test": "npx playwright test --project=local --workers=2",
+    "test": "npx playwright test --project=local",
     "test:ci": "npx playwright test --project=ci",
     "build": "tsup",
     "clean": "rm -rf dist",
@@ -46,7 +46,7 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.2",
     "@changesets/cli": "^2.27.11",
-    "@playwright/test": "1.57.0",
+    "@playwright/test": "1.58.1",
     "@types/node": "^22.10.5",
     "dotenv": "^16.4.7",
     "prettier": "^3.4.2",

packages/w3wallets/playwright.config.ts

@@ -11,9 +11,9 @@ export default defineConfig({
   /* Fail the build on CI if you accidentally left test.only in the source code. */
   forbidOnly: !!process.env.CI,
   /* Retry on CI only */
-  // retries: process.env.CI ? 2 : 0,
+  retries: process.env.CI ? 1 : 0,
   /* Opt out of parallel tests on CI. */
-  // workers: process.env.CI ? 1 : undefined,
+  workers: process.env.CI ? 2 : undefined,
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */
   reporter: "html",
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */