Release 1.0.0

.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. */