@walletwright/core 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @walletwright/core
 
+## 0.5.0
+
+### Minor Changes
+
+- 8eeeb62: Make the fixtures work on Playwright's defaults, report every wallet call as a step, and make the public surface promise only what the engine does.
+
+  **The fixtures pick headless per wallet.** `createWalletFixtures` passed Playwright's `headless` straight through, and Playwright defaults it to `true`, so a MetaMask, Solflare, or Slush suite written from the getting-started guide threw at launch until the config set `headless: false`. The fixtures now launch headless only where the wallet declares support (Phantom, Rabby) and open a real window for the rest, so no `headless` setting is needed. `launchWallet` keeps its strict behaviour and still refuses headless for those wallets by name.
+
+  **Wallet calls are Playwright steps.** Each call (`wallet.connectToDapp`, `wallet.accounts.add`, …) is reported as a boxed `test.step` under its own name in the report and trace, and a failing call now shows a code frame at the spec line that made it rather than at the engine. The launch shows up as `launch <Wallet>`.
+
+  **`launchWallet` supports `await using`.** `LaunchedWallet` implements `Symbol.asyncDispose`, so `await using launched = await launchWallet(setup)` closes the browser and removes the throwaway profile on scope exit, even when the code throws.
+
+  **The CLI reads the setup file the docs show.** `walletwright cache --setup <file>` builds every `WalletSetup` the module exports, named or default, one after another, instead of requiring a default export. `--wallet` narrows it to one wallet's setups. A setup-shaped export that fails validation is reported by name; the list of valid wallets now comes from the registry.
+
+  **MetaMask's Solana connect no longer flakes.** MetaMask could render the connect page before it had enabled the Solana network, leaving Connect disabled for good, so `connectToDapp()` timed out in roughly one run in three. The request is still pending when that happens, so MetaMask's `approve` now reloads a connect page whose Connect stays disabled, and the page renders again with the network in place.
+
+  **Breaking:**
+
+  - `WalletSetup.version` is refused for Phantom, Rabby, Solflare, and Slush. They run their Chrome Web Store build, which cannot be pinned; `version` was silently ignored for the download while still forking the profile cache.
+  - `wallet.network.switch` is removed. No wallet implemented it, so it could only throw; switching is dapp-initiated through `wallet_addEthereumChain` and `wallet.approve()`.
+  - `WalletDefinition` replaces `prepareExtension`, `reachUnlockScreen`, and `unlock` with declarative `source` and `unlockScreen` fields, and `WalletActionContext` gains `unlock()`. This only affects code that reads the definitions in `wallets`; a setup can only name a built-in wallet.
+
+  `walletKinds` and the `NetworkConfig` type are now exported.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -39,7 +39,8 @@ export const metamask: WalletSetup = {
 ## 2. Build the cache (once)
 
 ```sh
-walletwright cache --setup ./wallet-setup.ts
+walletwright cache --setup ./wallet-setup.ts                    # every WalletSetup it exports
+walletwright cache --setup ./wallet-setup.ts --wallet metamask  # just one
 # or: walletwright cache --wallet metamask --seed "YOUR_SEED_HERE" --password "YOUR_PASSWORD_HERE"
 ```
 
@@ -75,12 +76,15 @@ test("connect and sign", async ({ page, wallet }) => {
 
 The `wallet` fixture:
 
-| Method                  | Description                                                                       |
-| ----------------------- | --------------------------------------------------------------------------------- |
-| `connectToDapp()`       | Approve a pending connection popup. Resolves quietly if the wallet auto-approved. |
-| `confirmSignature()`    | Approve a pending signature popup.                                                |
-| `approve({ optional })` | Approve any pending popup, whether connect, sign, or a transaction.               |
-| `extensionId`           | The loaded extension id.                                                          |
+| Method                  | Description                                                                                |
+| ----------------------- | ------------------------------------------------------------------------------------------ |
+| `connectToDapp()`       | Approve a pending connection popup. Pass `{ optional: true }` for an already-trusted site. |
+| `confirmSignature()`    | Approve a pending signature popup.                                                         |
+| `approve({ optional })` | Approve any pending popup, whether connect, sign, or a transaction.                        |
+| `extensionId`           | The loaded extension id.                                                                   |
+
+Each call shows up as its own step in the Playwright report and trace (`wallet.confirmSignature`),
+and a failing call points at the line in your spec that made it.
 
 The same two calls drive every chain. A Phantom test can connect and sign on
 `window.phantom.ethereum` and then on `window.phantom.solana`; a Slush test does the same on Sui. See
@@ -91,19 +95,19 @@ The same two calls drive every chain. A Phantom test can connect and sign on
 ```ts
 import { launchWallet } from "@walletwright/core";
 
-const { close, context, wallet } = await launchWallet(metamask);
-const page = await context.newPage();
-// drive the page and the wallet here
-await close();
+await using launched = await launchWallet(metamask);
+const page = await launched.context.newPage();
+// drive the page and launched.wallet here; the browser closes when the scope exits
 ```
 
 ## Requirements and notes
 
-- **Headless works for Phantom and Rabby**, whose approval windows surface as pages that way.
-  MetaMask, Solflare and Slush need a real window, so default those suites to headed and give CI a
-  virtual display: `xvfb-run --auto-servernum pnpm exec playwright test`.
+- **Headless works for Phantom and Rabby**, whose approval windows surface as pages that way. The
+  fixtures open a real window for MetaMask, Solflare and Slush whatever `headless` says, so give CI
+  a virtual display: `xvfb-run --auto-servernum pnpm exec playwright test`.
 - MetaMask is pinned to a known-good version (override it with `WalletSetup.version`). Phantom,
-  Rabby, Solflare, and Slush always use the current Web Store build.
+  Rabby, Solflare, and Slush use the Web Store build current at their first download, which cannot
+  be pinned, so they refuse a `version`.
 - The cache lives in `.walletwright/` (override it with `WalletSetup.cacheDir`). Add that directory to
   `.gitignore`.