dappress 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Lassaut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# Dappress
+
+**MetaMask automation for Cypress.**
+
+Dappress loads the MetaMask browser extension into the browser Cypress launches, imports a test wallet, and exposes `cy.*` commands that answer the requests a dapp sends to the wallet: connection, signatures, transactions, network changes.
+
+- **Current MetaMask.** The extension version is a configuration value. Each release is verified by a conformance suite, with one test per command.
+- **Cypress native.** No second browser, no proxy. Dappress drives MetaMask through Puppeteer, connected to the browser Cypress already runs. Typed commands for TypeScript projects.
+- **Resilient selectors.** Every selector comes from MetaMask's own end-to-end test suite and carries a fallback.
+
+## Requirements
+
+| Dependency | Version |
+|---|---|
+| Cypress | 13.6 or later |
+| Node.js | 20 or later |
+| Browser | Chrome for Testing, Chromium or Electron. Google Chrome 137 and later cannot load extensions. |
+
+## Installation
+
+```bash
+npm install --save-dev dappress
+```
+
+Register the plugin in the Cypress configuration:
+
+```ts
+// cypress.config.ts
+import { defineConfig } from 'cypress';
+import { configureDappress } from 'dappress';
+
+export default defineConfig({
+  e2e: {
+    baseUrl: 'http://localhost:3000',
+    testIsolation: false, // the wallet state is shared across tests
+    setupNodeEvents(on, config) {
+      return configureDappress(on, config);
+    },
+  },
+});
+```
+
+Load the commands in the support file:
+
+```ts
+// cypress/support/e2e.ts
+import 'dappress/support';
+```
+
+Describe the test wallet:
+
+```ts
+// cypress/wallet.setup.ts
+import type { WalletSetup } from 'dappress';
+
+const wallet: WalletSetup = {
+  // The network the dapp is moved onto when it connects
+  network: {
+    chainId: '0x88bb0',
+    chainName: 'Hoodi',
+    rpcUrls: ['https://ethereum-hoodi-rpc.publicnode.com'],
+    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+  },
+};
+
+export default wallet;
+```
+
+Keep the seed phrase out of the repository, in `cypress.env.json` (git-ignored):
+
+```json
+{
+  "DAPPRESS_SEED_PHRASE": "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"
+}
+```
+
+In CI, provide it as an encrypted secret of the repository, exposed to the job as an environment variable:
+
+```yaml
+# GitHub Actions
+env:
+  DAPPRESS_SEED_PHRASE: ${{ secrets.DAPPRESS_SEED_PHRASE }}
+```
+
+When neither is provided, Dappress uses the public Hardhat / Anvil development wallet.
+
+Add the command types to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["cypress", "dappress/support"]
+  }
+}
+```
+
+JavaScript projects use the same files with a `.js` extension and `module.exports`.
+
+Run the tests in a headed browser that supports extensions:
+
+```bash
+npx cypress run --browser chrome-for-testing --headed
+```
+
+## Usage
+
+```ts
+it('connects the wallet and signs in', () => {
+  cy.visit('/');
+  cy.contains('button', 'Connect wallet').click();
+  cy.connectToDapp();
+  cy.getAccountAddress().should('eq', '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266');
+
+  cy.contains('button', 'Sign in').click();
+  cy.confirmSignature();
+});
+```
+
+The wallet is imported once, before the first test of each spec. Each command waits for MetaMask to display the request, answers it, and waits for the request to be dismissed.
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `cy.connectToDapp()` | Accepts the connection request, then moves the dapp onto the network of the wallet setup |
+| `cy.rejectConnection()` | Rejects the connection request |
+| `cy.confirmSignature()` | Signs the message (`personal_sign`, `eth_signTypedData_*`) |
+| `cy.rejectSignature()` | Rejects the signature request |
+| `cy.confirmTransaction()` | Sends the transaction, including ERC-20 approvals |
+| `cy.rejectTransaction()` | Rejects the transaction |
+| `cy.approveNewNetwork()` | Adds the network requested by `wallet_addEthereumChain` |
+| `cy.rejectNewNetwork()` | Rejects the network |
+| `cy.approveSwitchNetwork()` | Grants the permission asked by `wallet_switchEthereumChain` for a network the dapp is not yet allowed on |
+| `cy.rejectSwitchNetwork()` | Denies that permission |
+| `cy.approveAddToken()` | Adds the token requested by `wallet_watchAsset` |
+| `cy.rejectAddToken()` | Rejects the token |
+| `cy.useNetwork(network?)` | Moves the dapp onto a network, adding it to MetaMask when needed. Defaults to the network of the wallet setup. |
+| `cy.getAccountAddress()` | Yields the address the dapp is connected with |
+| `cy.setupMetaMask()` | Imports the wallet, or unlocks it. Called automatically before each spec. |
+
+### Configuration
+
+Settings normally live in `cypress/wallet.setup.ts`. Secrets go in `cypress.env.json` or in environment variables, which take precedence. The full order, first one found wins:
+
+1. Environment variables, for secrets in CI.
+2. `cypress.env.json`, for secrets on a development machine, such as the seed phrase.
+3. `cypress/wallet.setup.ts`, for everything else.
+4. The third argument of `configureDappress(on, config, options)`.
+
+| Option | Environment variable | Default |
+|---|---|---|
+| `metamaskVersion` | `DAPPRESS_METAMASK_VERSION` | `13.50.0`. The build is downloaded from MetaMask's GitHub releases on first run and cached in `~/.cache/dappress`. |
+| `seedPhrase` | `DAPPRESS_SEED_PHRASE` | `test test test test test test test test test test test junk`, the Hardhat / Anvil development wallet. Its first account is `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`. |
+| `password` | `DAPPRESS_PASSWORD` | `Tester@1234`. It only protects the throwaway browser profile Cypress creates for each run. |
+| `network` | | None. The dapp stays on the network MetaMask starts on, Ethereum mainnet. |
+| `autoSetup` | | `true`. Dappress imports or unlocks the wallet before the first test of each spec. Set to `false` to call `cy.setupMetaMask()` yourself. |
+| `cache` | | `false`. The wallet is imported in every run, about fifteen seconds. With `true`, it is imported once, in a browser Dappress opens before the run, and the resulting profile is reused by later runs, which then start by unlocking the wallet. |
+| `timeout` | | `20000` ms. The time allowed for MetaMask to display a request before a command fails. |
+
+### Security
+
+Use a wallet dedicated to testing, funded on test networks only. The default seed phrase is public. The seed phrase and password remain on the Node.js side: they are never exposed to the browser nor written to the Cypress command log. The wallet setup file contains no secret and can be committed.
+
+With `cache: true`, the profile under `~/.cache/dappress/profiles` holds the wallet's vault, encrypted by MetaMask with the password. Treat that directory like the seed phrase: keep it on the machine, and do not store it in a CI cache that other people or workflows can restore.
+
+## Conformance suite
+
+The suite runs one test per command against [MetaMask's test dapp](https://metamask.github.io/test-dapp/), with a local [Anvil](https://getfoundry.sh) node for the funded transaction. It requires Chrome for Testing and Foundry.
+
+```bash
+npm run conformance               # default MetaMask version
+npm run conformance -- 13.51.0    # a specific release
+```
+
+Each run writes `reports/metamask-<version>.json`. The GitHub workflow runs the suite daily against the latest MetaMask release that has no report yet.
+
+### Updating to a new MetaMask release
+
+1. Run the suite. Each failure names a screenshot of the MetaMask screen at that moment.
+2. Locate the new selector in MetaMask's page objects: `github.com/MetaMask/metamask-extension/tree/v<version>/test/e2e/page-objects/pages`.
+3. Update `src/metamask.js`, run the suite against the new and the previous release, bump the default version in `src/config.js`, and commit the report.
+
+## Architecture
+
+Cypress executes tests inside the dapp's tab and has no access to the extension. For each command, Dappress connects Puppeteer to the browser Cypress launched, through the debugging URL Cypress provides, locates the MetaMask page displaying the request and interacts with it.
+
+MetaMask displays requests in its side panel when the panel is open, and in its popup window otherwise. Without the cache, the import of the wallet ends by opening the side panel, so requests appear there. With the cache, the wallet was imported in another browser, the panel is closed, and requests appear in the popup. Dappress handles both, and the conformance suite covers both.
+
+With `cache: true`, Dappress imports the wallet once before the run, in a browser of its own, and keeps the profile; MetaMask's storage is copied from it into the profile Cypress is about to launch, so each run starts from a wallet that has never seen the dapp.
+
+```
+src/index.js            configureDappress(): plugin entry point
+src/config.js           options and wallet setup file
+src/download.js         download and cache of MetaMask builds
+src/browser.js          Puppeteer connection to the Cypress browser
+src/profile.js          wallet profile built once and reused across runs
+src/metamask-pages.js   discovery of MetaMask's pages
+src/metamask.js         MetaMask screens: selectors and flows
+src/page-helpers.js     wait, click and fill primitives with fallback selectors
+src/actions.js          Cypress tasks behind the commands
+src/support.js          cy.* commands
+types/                  TypeScript declarations
+conformance/            conformance suite
+```
+
+Selectors are MetaMask's `data-testid` attributes, each with the button's English label as a fallback. MetaMask's pages run under LavaMoat, which rejects injected scripts; the helpers therefore rely only on what Puppeteer can do from outside the page.
+
+## Troubleshooting
+
+- **Cypress exits immediately with `MODULE_NOT_FOUND`.** The terminal sets `ELECTRON_RUN_AS_NODE=1`, as some IDEs do. Run `env -u ELECTRON_RUN_AS_NODE npx cypress run …`.
+- **"MetaMask showed no confirmation".** The dapp sent no request, or sent it on a network whose RPC endpoint is unreachable.
+
+## Status
+
+Verified with MetaMask 13.49.0 and 13.50.0, Cypress 16 and Chrome for Testing 154 on macOS, in headed mode. Headless execution and continuous integration are not validated yet.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "dappress",
+  "version": "0.1.0",
+  "description": "MetaMask automation for Cypress: load the real extension, import a test wallet, answer dapp requests with cy.* commands. Tracks the latest MetaMask release.",
+  "license": "MIT",
+  "author": "Benjamin Lassaut",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blassaut/dappress.git"
+  },
+  "homepage": "https://github.com/blassaut/dappress#readme",
+  "bugs": {
+    "url": "https://github.com/blassaut/dappress/issues"
+  },
+  "keywords": [
+    "cypress",
+    "metamask",
+    "web3",
+    "e2e",
+    "testing",
+    "wallet",
+    "dapp"
+  ],
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./support": {
+      "types": "./types/support.d.ts",
+      "default": "./src/support.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "support": [
+        "types/support.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "conformance": "node scripts/conformance.js",
+    "check-types": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "cypress": ">=13.6.0"
+  },
+  "dependencies": {
+    "extract-zip": "^2.0.1",
+    "puppeteer-core": "^24.43.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "cypress": "^16.1.1",
+    "typescript": "^5.6.0"
+  }
+}

package/src/actions.js

@@ -0,0 +1,50 @@
+// The Node side of every cy.* command, registered as Cypress tasks. Each
+// action gets a Puppeteer browser connected to the Cypress browser, finds the
+// MetaMask page it needs and drives it through src/metamask.js.
+
+const { withBrowser } = require('./browser');
+const metamask = require('./metamask');
+const { findExtensionId, getHomePage, getConfirmationPage } = require('./metamask-pages');
+
+function createTasks(options) {
+  // Found once: the browser is the same for the whole run
+  let extensionId;
+
+  async function metamaskId(browser) {
+    extensionId = extensionId || (await findExtensionId(browser));
+    return extensionId;
+  }
+
+  /** Onboard the wallet or unlock it, so the dapp can talk to it. Safe to call repeatedly. */
+  async function setupWallet(browser) {
+    const home = await getHomePage(browser, await metamaskId(browser));
+    const state = await metamask.walletState(home);
+    console.log(`[dappress] MetaMask is ${state}`);
+    if (state === 'onboarding') await metamask.onboard(home, options);
+    if (state === 'locked') await metamask.unlock(home, options);
+    if (state === 'unknown') throw new Error(`[dappress] Unexpected MetaMask screen at ${home.url()}`);
+    await home.close();
+    return state;
+  }
+
+  /** Approve the prompt a network change raised: "Add network" or the permission to switch. */
+  async function approveNetworkChange(browser) {
+    const page = await getConfirmationPage(browser, await metamaskId(browser), options.timeout);
+    await metamask.approveNetworkChange(page, options.timeout);
+  }
+
+  /** The task for a decision: find the confirmation, press its button. */
+  const decide = (decision) => async (browser) => {
+    const page = await getConfirmationPage(browser, await metamaskId(browser), options.timeout);
+    await metamask.decide(decision, page, options.timeout);
+  };
+
+  const actions = { setupWallet, approveNetworkChange };
+  for (const decision of Object.keys(metamask.decisions)) actions[decision] = decide(decision);
+
+  // cy.task() needs a value back: null when the action has nothing to say
+  const asTask = (action) => async (argument) => (await withBrowser((browser) => action(browser, argument))) ?? null;
+  return Object.fromEntries(Object.entries(actions).map(([name, action]) => [`dappress:${name}`, asTask(action)]));
+}
+
+module.exports = { createTasks };

package/src/browser.js

@@ -0,0 +1,42 @@
+// Connects Puppeteer to the browser Cypress launched, through the debugging
+// URL Cypress hands out in after:browser:launch (Cypress 13.6+).
+
+const puppeteer = require('puppeteer-core');
+
+let debuggerUrl;
+
+function captureDebuggerUrl(on) {
+  on('after:browser:launch', (browser, options) => {
+    debuggerUrl = options.webSocketDebuggerUrl;
+  });
+}
+
+/**
+ * Run `action` with a Puppeteer browser connected to Cypress's browser, then
+ * give the focus back to the Cypress tab and disconnect. The browser stays open.
+ */
+async function withBrowser(action) {
+  if (!debuggerUrl) {
+    throw new Error('[dappress] No browser to connect to. Is configureDappress() called in setupNodeEvents, with Cypress 13.6 or later?');
+  }
+  const browser = await puppeteer.connect({ browserWSEndpoint: debuggerUrl, defaultViewport: null });
+  try {
+    return await action(browser);
+  } catch (error) {
+    // The browser side only gets the message, so keep the full stack in the terminal
+    console.error(error.stack || error);
+    throw error;
+  } finally {
+    await focusCypressTab(browser).catch(() => {});
+    await browser.disconnect();
+  }
+}
+
+// MetaMask opens its own tabs and popups; Chrome throttles the Cypress tab
+// while it is in the background. The Cypress runner lives under /__/.
+async function focusCypressTab(browser) {
+  const target = browser.targets().find((candidate) => candidate.type() === 'page' && candidate.url().includes('/__/'));
+  if (target) await (await target.page()).bringToFront();
+}
+
+module.exports = { captureDebuggerUrl, withBrowser };

package/src/config.js

@@ -0,0 +1,61 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const DEFAULTS = {
+  metamaskVersion: '13.50.0',
+  // The Hardhat / Anvil development mnemonic. Account 0 is 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266.
+  seedPhrase: 'test test test test test test test test test test test junk',
+  password: 'Tester@1234',
+  // The network cy.connectToDapp() moves the dapp onto, as a wallet_addEthereumChain parameter; none by default
+  network: null,
+  // Run cy.setupMetaMask() automatically before the first test of each spec
+  autoSetup: true,
+  // Import the wallet once and reuse the profile across runs (keeps the vault under cacheDir)
+  cache: false,
+  // How long to wait for MetaMask to show a confirmation after a dapp request (ms)
+  timeout: 20000,
+  cacheDir: path.join(os.homedir(), '.cache', 'dappress'),
+};
+
+// A .ts file loads when the Cypress config is itself in TypeScript
+const WALLET_SETUP_FILES = ['cypress/wallet.setup.ts', 'cypress/wallet.setup.js'];
+
+/**
+ * The plugin options, in order of precedence: environment variables, the
+ * Cypress `env` block (cypress.env.json), the wallet setup file
+ * (cypress/wallet.setup.ts or .js), the options given to configureDappress(),
+ * then the defaults above.
+ */
+function resolveOptions(userOptions = {}, cypressConfig = {}) {
+  const env = cypressConfig.env || {};
+  const fromEnv = {
+    metamaskVersion: process.env.DAPPRESS_METAMASK_VERSION || env.DAPPRESS_METAMASK_VERSION,
+    seedPhrase: process.env.DAPPRESS_SEED_PHRASE || env.DAPPRESS_SEED_PHRASE,
+    password: process.env.DAPPRESS_PASSWORD || env.DAPPRESS_PASSWORD,
+  };
+
+  const options = { ...DEFAULTS, ...userOptions, ...loadWalletSetup(cypressConfig.projectRoot) };
+  for (const [key, value] of Object.entries(fromEnv)) {
+    if (value) options[key] = value;
+  }
+  return options;
+}
+
+/** The project's wallet setup file: { seedPhrase?, network? }. */
+function loadWalletSetup(projectRoot = process.cwd()) {
+  const file = WALLET_SETUP_FILES.map((name) => path.join(projectRoot, name)).find((candidate) => fs.existsSync(candidate));
+  if (!file) return {};
+  const loaded = require(file);
+  const setup = loaded.default || loaded; // `export default` or `module.exports`
+  const unknown = Object.keys(setup).filter((key) => !['seedPhrase', 'network'].includes(key));
+  if (unknown.length) throw new Error(`[dappress] Unknown keys in ${path.basename(file)}: ${unknown.join(', ')}`);
+  return setup;
+}
+
+/** The subset of options that is safe to expose to the browser side (no secrets). */
+function publicOptions(options) {
+  return { metamaskVersion: options.metamaskVersion, autoSetup: options.autoSetup, network: options.network };
+}
+
+module.exports = { DEFAULTS, resolveOptions, publicOptions };

package/src/download.js

@@ -0,0 +1,50 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { pipeline } = require('node:stream/promises');
+const { Readable } = require('node:stream');
+const extractZip = require('extract-zip');
+
+function releaseUrl(version) {
+  return `https://github.com/MetaMask/metamask-extension/releases/download/v${version}/metamask-chrome-${version}.zip`;
+}
+
+function extensionDir(cacheDir, version) {
+  return path.join(cacheDir, 'metamask', version);
+}
+
+async function download(url, destination) {
+  const response = await fetch(url, { redirect: 'follow' });
+  if (!response.ok || !response.body) {
+    throw new Error(`[dappress] Could not download ${url}: HTTP ${response.status}`);
+  }
+  await fs.promises.mkdir(path.dirname(destination), { recursive: true });
+  await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(destination));
+}
+
+/**
+ * Download and unzip the MetaMask Chrome build for `version` into the cache.
+ * Returns the path of the unpacked extension (the folder holding manifest.json).
+ * Already cached versions are reused.
+ */
+async function prepareExtension({ metamaskVersion, cacheDir }) {
+  const dir = extensionDir(cacheDir, metamaskVersion);
+  const manifest = path.join(dir, 'manifest.json');
+  if (fs.existsSync(manifest)) return dir;
+
+  const zipPath = path.join(cacheDir, 'metamask', `metamask-chrome-${metamaskVersion}.zip`);
+  if (!fs.existsSync(zipPath)) {
+    console.log(`[dappress] Downloading MetaMask ${metamaskVersion}…`);
+    await download(releaseUrl(metamaskVersion), zipPath);
+  }
+
+  console.log(`[dappress] Unpacking MetaMask ${metamaskVersion}…`);
+  await fs.promises.rm(dir, { recursive: true, force: true });
+  await extractZip(zipPath, { dir });
+
+  if (!fs.existsSync(manifest)) {
+    throw new Error(`[dappress] ${zipPath} does not look like a MetaMask build: no manifest.json after extraction`);
+  }
+  return dir;
+}
+
+module.exports = { prepareExtension };

package/src/index.js

@@ -0,0 +1,45 @@
+const { resolveOptions, publicOptions } = require('./config');
+const { captureDebuggerUrl } = require('./browser');
+const { prepareExtension } = require('./download');
+const { prepareProfile, installProfile } = require('./profile');
+const { createTasks } = require('./actions');
+
+/**
+ * Wire Dappress into a Cypress project. Call it from setupNodeEvents:
+ *
+ *   setupNodeEvents(on, config) {
+ *     return configureDappress(on, config);
+ *   }
+ *
+ * It loads the MetaMask extension into the browser Cypress launches, and
+ * registers the tasks behind the cy.* commands from 'dappress/support'.
+ */
+function configureDappress(on, config, userOptions = {}) {
+  const options = resolveOptions(userOptions, config);
+
+  // Build the wallet profile before the run, out of the time Cypress allows a browser to come up
+  on('before:run', async ({ browser }) => {
+    if (options.cache && browser) await prepareProfile({ browserPath: browser.path, extensionDir: await prepareExtension(options), options });
+  });
+
+  on('before:browser:launch', async (browser, launchOptions) => {
+    if (browser.family !== 'chromium') {
+      throw new Error(`[dappress] MetaMask is a Chromium extension; ${browser.name} is not supported`);
+    }
+    const extensionDir = await prepareExtension(options);
+    launchOptions.extensions.push(extensionDir);
+    if (options.cache) {
+      const profileDir = await prepareProfile({ browserPath: browser.path, extensionDir, options });
+      await installProfile(profileDir, browser, config.isTextTerminal);
+    }
+    return launchOptions;
+  });
+  captureDebuggerUrl(on);
+  on('task', createTasks(options));
+
+  // Non-sensitive settings the browser side reads with Cypress.expose()
+  config.expose = { ...config.expose, dappress: publicOptions(options) };
+  return config;
+}
+
+module.exports = { configureDappress };

package/src/metamask-pages.js

@@ -0,0 +1,91 @@
+// Find MetaMask's pages in the browser Cypress launched: the full-screen home
+// page, and the surface where dapp requests show up. On Chrome that surface
+// is the side panel when it is open, and the "MetaMask Dialog" popup otherwise.
+
+const { sleep } = require('./page-helpers');
+
+const HOME_PATH = '/home.html';
+const CONFIRMATION_PATHS = ['/notification.html', '/sidepanel.html'];
+
+function extensionIdOf(url) {
+  const match = /^chrome-extension:\/\/([a-z]{32})\//.exec(url);
+  return match ? match[1] : null;
+}
+
+function isHomeRoute(url) {
+  return url.includes('/notification.html') && /notification\.html(#\/?)?$/.test(url);
+}
+
+function pagesOf(browser, extensionId, pathname) {
+  return browser
+    .targets()
+    .filter((target) => target.type() === 'page' && target.url().startsWith(`chrome-extension://${extensionId}${pathname}`));
+}
+
+/**
+ * MetaMask's extension id. Cypress loads its own extension in headed
+ * Chromium browsers, so the id is the one whose home page is titled "MetaMask".
+ */
+async function findExtensionId(browser, timeout = 30000) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const ids = new Set(browser.targets().map((target) => extensionIdOf(target.url())).filter(Boolean));
+    for (const id of ids) {
+      if (await isMetaMask(browser, id)) return id;
+    }
+    await sleep(500);
+  }
+  throw new Error('[dappress] MetaMask extension not found in the browser. Is it loaded in before:browser:launch?');
+}
+
+async function isMetaMask(browser, extensionId) {
+  const [target] = pagesOf(browser, extensionId, HOME_PATH);
+  if (target) {
+    const page = await target.page();
+    return (await page.title()).startsWith('MetaMask');
+  }
+  const page = await browser.newPage();
+  try {
+    const response = await page.goto(`chrome-extension://${extensionId}${HOME_PATH}`, { waitUntil: 'domcontentloaded' });
+    return Boolean(response && response.ok()) && (await page.title()).startsWith('MetaMask');
+  } catch {
+    return false;
+  } finally {
+    await page.close();
+  }
+}
+
+/** The full-screen MetaMask page, opened if it isn't already. */
+async function getHomePage(browser, extensionId) {
+  const [target] = pagesOf(browser, extensionId, HOME_PATH);
+  if (target) return target.page();
+  const page = await browser.newPage();
+  await page.goto(`chrome-extension://${extensionId}${HOME_PATH}`, { waitUntil: 'domcontentloaded' });
+  return page;
+}
+
+/**
+ * The page a dapp request is shown on. Waits for the popup to open, or takes
+ * the side panel. A popup still on its home route is one closing after the
+ * previous request, or one that hasn't routed to the request yet: skipped.
+ */
+async function getConfirmationPage(browser, extensionId, timeout) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    for (const pathname of CONFIRMATION_PATHS) {
+      const [target] = pagesOf(browser, extensionId, pathname).filter((candidate) => !isHomeRoute(candidate.url()));
+      if (target) return target.page();
+    }
+    await sleep(250);
+  }
+  const seen = browser
+    .targets()
+    .filter((target) => extensionIdOf(target.url()) === extensionId)
+    .map((target) => `${target.type()} ${target.url()}`)
+    .join(', ');
+  throw new Error(
+    `[dappress] MetaMask showed no confirmation within ${timeout}ms. Did the dapp send a request? MetaMask pages seen: ${seen || 'none'}`,
+  );
+}
+
+module.exports = { findExtensionId, getHomePage, getConfirmationPage };

package/src/metamask.js

@@ -0,0 +1,220 @@
+// MetaMask's screens: what to click, and in which order.
+//
+// Selectors come from MetaMask's own end-to-end page objects
+// (test/e2e/page-objects in the metamask-extension repository), which MetaMask
+// has to keep working for its own test suite. Each entry lists the data-testid
+// first, then a fallback on the button's English text. When a MetaMask release
+// moves something, this is the file to fix.
+
+const { describe, waitFor, isVisible, isGone, click, clickWhenEnabled, dispatchClick, fill, failure, sleep } = require('./page-helpers');
+
+const testId = (id) => `[data-testid="${id}"]`;
+// XPath rather than Puppeteer's ::-p-text(): the latter needs MutationObserver,
+// which MetaMask's sandbox (LavaMoat) blocks in its pages.
+const buttonText = (text) => `xpath/.//button[normalize-space(.)="${text}"]`;
+const passwordInput = (position) => `xpath/(.//input[@type="password"])[${position}]`;
+
+const selectors = {
+  onboarding: {
+    importWallet: [testId('onboarding-import-wallet'), buttonText('I have an existing wallet')],
+    importWithSrp: [testId('onboarding-import-with-srp-button'), buttonText('Import using Secret Recovery Phrase')],
+    srpInput: testId('srp-input-import__srp-note'),
+    srpWord: (index) => testId(`import-srp__srp-word-${index}`),
+    srpConfirm: [testId('import-srp-confirm'), buttonText('Continue')],
+    newPassword: [testId('create-password-new-input'), passwordInput(1)],
+    confirmPassword: [testId('create-password-confirm-input'), passwordInput(2)],
+    passwordTerms: testId('create-password-terms'),
+    passwordSubmit: [testId('create-password-submit'), buttonText('Import my wallet')],
+    passkeyMaybeLater: [testId('passkey-maybe-later-button'), buttonText('Maybe later')],
+    metricsCheckbox: testId('metametrics-checkbox'),
+    metricsContinue: [testId('metametrics-i-agree'), buttonText('Continue')],
+    downloadAppContinue: testId('download-app-continue'),
+    done: [testId('onboarding-complete-done'), buttonText('Done')],
+  },
+  unlock: {
+    password: [testId('unlock-password'), passwordInput(1)],
+    submit: [testId('unlock-submit'), buttonText('Unlock')],
+  },
+  home: {
+    header: testId('parent-selector-header-navbar'),
+  },
+  // "Connect this website with MetaMask"
+  connect: {
+    confirm: [testId('confirm-btn'), buttonText('Connect')],
+    cancel: [testId('cancel-btn'), buttonText('Cancel')],
+  },
+  // Signatures, transactions and "Add network" share the same confirmation footer
+  confirmation: {
+    confirm: [testId('confirm-footer-button'), buttonText('Confirm'), buttonText('Approve')],
+    cancel: [testId('confirm-footer-cancel-button'), buttonText('Cancel')],
+    scrollToBottom: testId('confirm-scroll-to-bottom'),
+  },
+  // The older footer, still used by the permission update a network switch
+  // asks for, by "Add suggested tokens", and by template confirmations
+  pageContainer: {
+    confirm: [testId('page-container-footer-next'), testId('confirmation-submit-button'), buttonText('Confirm')],
+    cancel: [testId('page-container-footer-cancel'), testId('confirmation-cancel-button'), buttonText('Cancel')],
+  },
+  // "Switching network will cancel N pending transactions": a warning MetaMask
+  // raises after the confirmation is accepted; "Got it" carries on
+  alert: {
+    acknowledge: [testId('alert-modal-button'), buttonText('Got it')],
+  },
+  // "We've noticed multiple requests": shown over the confirmation when a dapp
+  // sends many requests in a row, and it swallows the clicks
+  modal: {
+    content: '.mm-modal-content',
+    lastButton: 'xpath/(.//div[contains(@class, "mm-modal-content")]//button)[last()]',
+  },
+};
+
+// Which button each command presses on the confirmation
+const decisions = {
+  connectToDapp: selectors.connect.confirm,
+  rejectConnection: selectors.connect.cancel,
+  approveNewNetwork: selectors.confirmation.confirm,
+  rejectNewNetwork: selectors.confirmation.cancel,
+  // A switch to a network the dapp is allowed on is silent; otherwise MetaMask asks for the permission
+  approveSwitchNetwork: selectors.pageContainer.confirm,
+  rejectSwitchNetwork: selectors.pageContainer.cancel,
+  // wallet_watchAsset
+  approveAddToken: selectors.pageContainer.confirm,
+  rejectAddToken: selectors.pageContainer.cancel,
+  confirmSignature: selectors.confirmation.confirm,
+  rejectSignature: selectors.confirmation.cancel,
+  confirmTransaction: selectors.confirmation.confirm,
+  rejectTransaction: selectors.confirmation.cancel,
+};
+
+/** Which screen the extension home page shows, once MetaMask has started. */
+async function walletState(page) {
+  const deadline = Date.now() + 20000;
+  while (Date.now() < deadline) {
+    if (await isVisible(page, selectors.onboarding.importWallet, 500)) return 'onboarding';
+    if (await isVisible(page, selectors.unlock.password, 500)) return 'locked';
+    if (await isVisible(page, selectors.home.header, 500)) return 'unlocked';
+  }
+  return 'unknown';
+}
+
+/** Import a wallet from its seed phrase on a fresh MetaMask install. */
+async function onboard(page, { seedPhrase, password }) {
+  const s = selectors.onboarding;
+  await click(page, s.importWallet, { timeout: 30000 });
+  await click(page, s.importWithSrp);
+
+  await fillSeedPhrase(page, seedPhrase);
+  await clickWhenEnabled(page, s.srpConfirm);
+
+  await fill(page, s.newPassword, password);
+  await fill(page, s.confirmPassword, password);
+  await click(page, s.passwordTerms);
+  await clickWhenEnabled(page, s.passwordSubmit);
+
+  await reachHome(page, { password });
+}
+
+// MetaMask's sandbox (LavaMoat) blocks a scripted paste, so the phrase is
+// typed word by word: a space after a word moves the cursor to the next field.
+async function fillSeedPhrase(page, seedPhrase) {
+  const words = seedPhrase.trim().split(/\s+/);
+  await fill(page, selectors.onboarding.srpInput, words[0]);
+  await page.keyboard.press('Space');
+  for (let index = 1; index < words.length; index++) {
+    await fill(page, selectors.onboarding.srpWord(index), words[index]);
+    if (index < words.length - 1) await page.keyboard.press('Space');
+  }
+}
+
+async function unlock(page, { password }) {
+  await fill(page, selectors.unlock.password, password);
+  await click(page, selectors.unlock.submit);
+  await reachHome(page, { password });
+}
+
+/**
+ * Go through whatever MetaMask shows until the wallet's home: the screens
+ * that may follow the password or an unlock (passkey, analytics, "download
+ * the app", "Done"), and the unlock form if MetaMask locked meanwhile. After
+ * "Done", MetaMask takes a moment to record the onboarding as complete and
+ * redirects to it until then, so the home page is reloaded.
+ */
+async function reachHome(page, { password }) {
+  const s = selectors.onboarding;
+  const deadline = Date.now() + 90000;
+  while (Date.now() < deadline) {
+    if (await isVisible(page, selectors.home.header, 500)) return;
+    if (await isVisible(page, s.passkeyMaybeLater, 500)) await click(page, s.passkeyMaybeLater);
+    if (await isVisible(page, s.metricsCheckbox, 500)) {
+      await optOutOfMetrics(page);
+      await click(page, s.metricsContinue);
+    }
+    if (await isVisible(page, s.downloadAppContinue, 500)) await click(page, s.downloadAppContinue);
+    if (await isVisible(page, s.done, 500)) {
+      await click(page, s.done);
+      await sleep(1000);
+      await reloadHome(page);
+    }
+    if (await isVisible(page, selectors.unlock.password, 500)) {
+      await fill(page, selectors.unlock.password, password);
+      await click(page, selectors.unlock.submit);
+    }
+  }
+  throw await failure(page, 'MetaMask did not show the wallet');
+}
+
+async function optOutOfMetrics(page) {
+  const checkbox = await waitFor(page, selectors.onboarding.metricsCheckbox);
+  const checked = await checkbox.evaluate((el) => el.getAttribute('data-checked') === 'true');
+  if (checked) await checkbox.click();
+}
+
+// Through about:blank: dropping only the "#" part of the URL would be a
+// same-document navigation, which goto() waits on forever
+async function reloadHome(page) {
+  const homeUrl = page.url().split('#')[0];
+  await page.goto('about:blank');
+  await page.goto(homeUrl);
+}
+
+/** Press the button of `decision` on the confirmation shown on `page`. */
+function decide(decision, page, timeout) {
+  return pressAndWaitForDismissal(page, decisions[decision], timeout);
+}
+
+/** wallet_addEthereumChain on a network MetaMask knows behaves like a switch: either prompt may show. */
+function approveNetworkChange(page, timeout) {
+  return pressAndWaitForDismissal(page, [...selectors.confirmation.confirm, ...selectors.pageContainer.confirm], timeout);
+}
+
+/**
+ * Press a footer button, then wait for the confirmation to go away: the
+ * popup closes, the side panel goes back to the home screen. A click that
+ * lands while the confirmation is still settling is lost, so the click is
+ * repeated while the button stays.
+ */
+async function pressAndWaitForDismissal(page, button, timeout) {
+  await waitFor(page, button, { timeout });
+  await dismissModal(page);
+  if (await isVisible(page, selectors.confirmation.scrollToBottom, 500)) {
+    await click(page, selectors.confirmation.scrollToBottom);
+  }
+  await clickWhenEnabled(page, button);
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (await isVisible(page, selectors.alert.acknowledge, 500)) await click(page, selectors.alert.acknowledge);
+    if (await isGone(page, button, 3000)) return;
+    await dismissModal(page);
+    await dispatchClick(page, button, { timeout: 3000 }).catch(() => {});
+  }
+  throw await failure(page, `"${describe(button)}" is still showing after being clicked`);
+}
+
+/** Close a modal shown over the confirmation (Escape, or its last button: "Cancel"). */
+async function dismissModal(page) {
+  if (!(await isVisible(page, selectors.modal.content, 300))) return;
+  await page.keyboard.press('Escape');
+  if (await isGone(page, selectors.modal.content, 1000)) return;
+  await dispatchClick(page, selectors.modal.lastButton);
+}
+
+module.exports = { decisions, walletState, onboard, unlock, decide, approveNetworkChange };

package/src/page-helpers.js

@@ -0,0 +1,117 @@
+// Small helpers on top of Puppeteer's Page API. They give every interaction
+// the same waiting and error reporting, and stay within what MetaMask's
+// sandbox (LavaMoat) allows: no script injected into the page.
+//
+// A "selector" is a CSS or XPath selector, or a list of them tried together:
+// the first one to show up wins.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const DEFAULT_TIMEOUT = 15000;
+const SCREENSHOTS_DIR = path.join(os.tmpdir(), 'dappress');
+
+const candidates = (selector) => [].concat(selector);
+
+/** A readable name for a selector, for error messages. */
+function describe(selector) {
+  return candidates(selector)
+    .map((candidate) => candidate.replace(/^\[data-testid="(.+)"\]$/, '$1').replace(/^xpath\/.*="(.+)"\]$/, 'button "$1"'))
+    .join(' | ');
+}
+
+/** Wait for the first candidate to be visible and return its element handle. */
+async function waitFor(page, selector, { timeout = DEFAULT_TIMEOUT } = {}) {
+  const attempts = candidates(selector).map((candidate) => page.waitForSelector(candidate, { visible: true, timeout }));
+  try {
+    return await Promise.any(attempts);
+  } catch {
+    throw await failure(page, `Timed out waiting for "${describe(selector)}"`);
+  } finally {
+    // Let the losing attempts fail quietly when they time out
+    attempts.forEach((attempt) => attempt.catch(() => {}));
+  }
+}
+
+/** Returns true when `selector` is visible within `timeout` ms, false otherwise. */
+async function isVisible(page, selector, timeout = 1500) {
+  try {
+    await waitFor(page, selector, { timeout });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Returns true once every candidate has left the page, or if the page itself closes. */
+async function isGone(page, selector, timeout = 1500) {
+  try {
+    await Promise.all(candidates(selector).map((candidate) => page.waitForSelector(candidate, { hidden: true, timeout })));
+    return true;
+  } catch {
+    return page.isClosed();
+  }
+}
+
+async function click(page, selector, options) {
+  const element = await waitFor(page, selector, options);
+  await waitForStill(element);
+  await element.click();
+}
+
+/** Wait until the element is both visible and enabled, then click it. */
+async function clickWhenEnabled(page, selector, { timeout = DEFAULT_TIMEOUT } = {}) {
+  const element = await waitFor(page, selector, { timeout });
+  const deadline = Date.now() + timeout;
+  while (await element.evaluate((el) => el.disabled)) {
+    if (Date.now() > deadline) throw await failure(page, `"${describe(selector)}" stayed disabled for ${timeout}ms`);
+    await sleep(100);
+  }
+  await waitForStill(element);
+  await element.click();
+}
+
+/** Click by dispatching the event on the element itself, for buttons something may cover. */
+async function dispatchClick(page, selector, options) {
+  const element = await waitFor(page, selector, options);
+  await element.evaluate((el) => el.click());
+}
+
+/** MetaMask animates its menus and confirmations in; a click during the animation lands elsewhere. */
+async function waitForStill(element, timeout = 2000) {
+  const deadline = Date.now() + timeout;
+  let previous = JSON.stringify(await element.boundingBox());
+  while (Date.now() < deadline) {
+    await sleep(100);
+    const current = JSON.stringify(await element.boundingBox());
+    if (current === previous) return;
+    previous = current;
+  }
+}
+
+/** Replace the content of a field with `text`. */
+async function fill(page, selector, text, options) {
+  const element = await waitFor(page, selector, options);
+  await element.click({ clickCount: 3 });
+  await element.type(text);
+}
+
+/** The error for something that went wrong on `page`, with a screenshot to look at. */
+async function failure(page, message) {
+  const prefix = `[dappress] ${message} on ${page.url()}`;
+  try {
+    fs.mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+    const file = path.join(SCREENSHOTS_DIR, `${Date.now()}.png`);
+    await page.screenshot({ path: file });
+    return new Error(`${prefix}. Screenshot: ${file}`);
+  } catch {
+    return new Error(prefix);
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = { describe, waitFor, isVisible, isGone, click, clickWhenEnabled, dispatchClick, fill, failure, sleep };

package/src/profile.js

@@ -0,0 +1,102 @@
+// Onboard the wallet once, in a browser of our own, and keep the resulting
+// profile. Each Cypress run then starts from a copy of it, with the wallet
+// imported but nothing else: no connected site, no added network.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const puppeteer = require('puppeteer-core');
+const metamask = require('./metamask');
+const { findExtensionId, getHomePage } = require('./metamask-pages');
+
+// One build at a time: Cypress calls before:browser:launch again when the
+// browser is slow to connect, and two builds on one profile would collide
+const builds = new Map();
+
+/** The cached profile for these options, built on first use. */
+function prepareProfile({ browserPath, extensionDir, options }) {
+  const key = crypto.createHash('sha256').update([options.metamaskVersion, options.seedPhrase, options.password].join('|')).digest('hex').slice(0, 16);
+  if (!builds.has(key)) builds.set(key, buildProfile(path.join(options.cacheDir, 'profiles', key), { browserPath, extensionDir, options }));
+  return builds.get(key);
+}
+
+async function buildProfile(dir, { browserPath, extensionDir, options }) {
+  if (fs.existsSync(path.join(dir, 'ready'))) return dir;
+
+  console.log('[dappress] Importing the wallet once, into a cached profile…');
+  await fs.promises.rm(dir, { recursive: true, force: true });
+  const launch = () =>
+    puppeteer.launch({
+      executablePath: browserPath,
+      headless: false,
+      userDataDir: dir,
+      args: [`--load-extension=${extensionDir}`, `--disable-extensions-except=${extensionDir}`, '--no-first-run'],
+    });
+
+  await withMetaMask(launch, (home) => metamask.onboard(home, options));
+  // Reopen the profile: the wallet must now be there, locked, with no onboarding left
+  await withMetaMask(launch, async (home) => {
+    const state = await metamask.walletState(home);
+    if (state !== 'locked') throw new Error(`[dappress] The cached profile did not keep the wallet: MetaMask is ${state} at ${home.url()}`);
+    await metamask.unlock(home, options);
+  });
+  fs.writeFileSync(path.join(dir, 'ready'), '');
+  return dir;
+}
+
+// MetaMask persists its state a moment after the last screen; leave it that moment before closing
+async function withMetaMask(launch, action) {
+  const browser = await launch();
+  try {
+    await action(await getHomePage(browser, await findExtensionId(browser)));
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+  } finally {
+    await browser.close();
+  }
+}
+
+// Where Cypress is about to create the browser profile:
+// <app data>/Cypress/cy/<env>/browsers/<name>-<channel>/run-<pid of the Cypress process>,
+// or .../interactive in open mode. The pid is our parent's: Cypress runs
+// setupNodeEvents in a child process. Returns null when it can't be found.
+function cypressProfileDir(browser, isTextTerminal) {
+  const appData = [
+    path.join(os.homedir(), 'Library', 'Application Support'),
+    process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'),
+    process.env.APPDATA,
+  ].filter(Boolean);
+  const cypressData = appData.map((dir) => path.join(dir, 'Cypress', 'cy')).find((dir) => fs.existsSync(dir));
+  if (!cypressData) return null;
+  const env = ['production', 'development'].find((name) => fs.existsSync(path.join(cypressData, name)));
+  if (!env) return null;
+  return path.join(cypressData, env, 'browsers', `${browser.name}-${browser.channel}`, isTextTerminal ? `run-${process.ppid}` : 'interactive');
+}
+
+/**
+ * Copy MetaMask's data from the cached profile into the profile Cypress is
+ * about to launch. Returns false when that profile can't be located; the
+ * wallet is then imported during the run instead.
+ */
+async function installProfile(profileDir, browser, isTextTerminal) {
+  const userDataDir = cypressProfileDir(browser, isTextTerminal);
+  if (!userDataDir) {
+    console.warn('[dappress] Could not locate the Cypress browser profile; importing the wallet in this run instead');
+    return false;
+  }
+  for (const entry of metamaskData(profileDir)) {
+    await fs.promises.cp(path.join(profileDir, entry), path.join(userDataDir, entry), { recursive: true });
+  }
+  return true;
+}
+
+// Where Chrome keeps an extension's storage: chrome.storage.local and IndexedDB
+function metamaskData(profileDir) {
+  const base = path.join(profileDir, 'Default');
+  const entries = ['Local Extension Settings', 'IndexedDB'];
+  return entries
+    .filter((entry) => fs.existsSync(path.join(base, entry)))
+    .flatMap((entry) => fs.readdirSync(path.join(base, entry)).map((name) => path.join('Default', entry, name)));
+}
+
+module.exports = { prepareProfile, installProfile };

package/src/support.js

@@ -0,0 +1,83 @@
+// Cypress commands. Import this file from your support file:
+//
+//   import 'dappress/support';
+//
+// Each command asks the Node side (src/actions.js) to drive MetaMask through
+// a Cypress task, then yields back to the test.
+
+const options = Cypress.expose('dappress') || {};
+
+function metamask(action, argument = null) {
+  Cypress.log({ name: 'metamask', message: argument ? `${action} ${argument}` : action });
+  return cy.task(`dappress:${action}`, argument, { log: false });
+}
+
+function provider(method, params) {
+  return cy.window({ log: false }).then((win) => win.ethereum.request({ method, params }));
+}
+
+Cypress.Commands.add('setupMetaMask', () => metamask('setupWallet'));
+Cypress.Commands.add('rejectConnection', () => metamask('rejectConnection'));
+Cypress.Commands.add('approveNewNetwork', () => metamask('approveNewNetwork'));
+Cypress.Commands.add('rejectNewNetwork', () => metamask('rejectNewNetwork'));
+Cypress.Commands.add('approveSwitchNetwork', () => metamask('approveSwitchNetwork'));
+Cypress.Commands.add('rejectSwitchNetwork', () => metamask('rejectSwitchNetwork'));
+Cypress.Commands.add('confirmSignature', () => metamask('confirmSignature'));
+Cypress.Commands.add('rejectSignature', () => metamask('rejectSignature'));
+Cypress.Commands.add('confirmTransaction', () => metamask('confirmTransaction'));
+Cypress.Commands.add('rejectTransaction', () => metamask('rejectTransaction'));
+Cypress.Commands.add('approveAddToken', () => metamask('approveAddToken'));
+Cypress.Commands.add('rejectAddToken', () => metamask('rejectAddToken'));
+
+
+// Connect, then move the dapp onto the network from the wallet setup, if there is one
+Cypress.Commands.add('connectToDapp', () => {
+  metamask('connectToDapp');
+  if (options.network) cy.useNetwork(options.network);
+});
+
+// Move the dapp onto `network` (a wallet_addEthereumChain parameter), adding
+// it to MetaMask if needed. A switch to a network the dapp is already allowed
+// on settles at once; anything else makes MetaMask ask, and we approve.
+Cypress.Commands.add('useNetwork', (network = options.network) => {
+  if (!network) throw new Error('[dappress] cy.useNetwork() needs a network, or one in cypress/wallet.setup.js');
+  Cypress.log({ name: 'metamask', message: `useNetwork ${network.chainName || network.chainId}` });
+  cy.window({ log: false }).then((win) => {
+    win.dappressNetwork = { settled: false };
+    win.dappressNetwork.request = win.ethereum
+      .request({ method: 'wallet_addEthereumChain', params: [network] })
+      .then((result) => ({ result }), (error) => ({ error }))
+      .finally(() => (win.dappressNetwork.settled = true));
+  });
+  cy.wait(1500, { log: false });
+  cy.window({ log: false }).then((win) => {
+    if (!win.dappressNetwork.settled) metamask('approveNetworkChange');
+  });
+  cy.window({ log: false }).then({ timeout: 60000 }, (win) => win.dappressNetwork.request).then(({ error }) => {
+    if (error) throw new Error(`[dappress] MetaMask refused the network: ${error.message}`);
+  });
+  waitForChainId(network.chainId);
+});
+
+// The address the dapp sees, asked to the injected provider rather than to the
+// MetaMask UI, so it keeps working across MetaMask versions.
+Cypress.Commands.add('getAccountAddress', () => {
+  Cypress.log({ name: 'metamask', message: 'getAccountAddress' });
+  return provider('eth_accounts').then(([address]) => address);
+});
+
+// MetaMask announces the new chain to the dapp shortly after the switch
+function waitForChainId(chainId, attempts = 20) {
+  return provider('eth_chainId').then((current) => {
+    if (current === chainId) return current;
+    if (attempts === 0) throw new Error(`[dappress] The dapp is on chain ${current}, not ${chainId}`);
+    return cy.wait(500, { log: false }).then(() => waitForChainId(chainId, attempts - 1));
+  });
+}
+
+// Onboard or unlock the wallet once per spec, before the dapp needs it.
+if (options.autoSetup !== false) {
+  before(() => {
+    cy.setupMetaMask();
+  });
+}

package/types/index.d.ts

@@ -0,0 +1,47 @@
+/// <reference types="cypress" />
+
+/** A network, as passed to MetaMask's wallet_addEthereumChain. */
+export interface Network {
+  chainId: string;
+  chainName: string;
+  rpcUrls: string[];
+  nativeCurrency: { name: string; symbol: string; decimals: number };
+  blockExplorerUrls?: string[];
+  iconUrls?: string[];
+}
+
+/** What cypress/wallet.setup.ts exports. */
+export interface WalletSetup {
+  /** Prefer DAPPRESS_SEED_PHRASE in cypress.env.json or the environment: this file is usually committed. */
+  seedPhrase?: string;
+  /** The network the dapp is moved onto by cy.connectToDapp(). */
+  network?: Network;
+}
+
+export interface DappressOptions extends WalletSetup {
+  /** Password of the throwaway browser profile's wallet. Default: Tester@1234. */
+  password?: string;
+  /** MetaMask release to load, downloaded from GitHub on first run. */
+  metamaskVersion?: string;
+  /** Run cy.setupMetaMask() before the first test of each spec. Default: true. */
+  autoSetup?: boolean;
+  /** Import the wallet once and reuse the profile across runs. Keeps the vault under cacheDir. Default: false. */
+  cache?: boolean;
+  /** Time allowed for MetaMask to display a request, in ms. Default: 20000. */
+  timeout?: number;
+  /** Where MetaMask builds are cached. Default: ~/.cache/dappress. */
+  cacheDir?: string;
+}
+
+/**
+ * Wire Dappress into a Cypress project, from setupNodeEvents:
+ *
+ *   setupNodeEvents(on, config) {
+ *     return configureDappress(on, config);
+ *   }
+ */
+export function configureDappress(
+  on: Cypress.PluginEvents,
+  config: Cypress.PluginConfigOptions,
+  options?: DappressOptions,
+): Cypress.PluginConfigOptions;

package/types/support.d.ts

@@ -0,0 +1,36 @@
+/// <reference types="cypress" />
+
+import type { Network } from './index';
+
+export type WalletState = 'onboarding' | 'locked' | 'unlocked';
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      /** Imports or unlocks the wallet. Runs by itself before each spec unless autoSetup is false. */
+      setupMetaMask(): Chainable<WalletState>;
+      /** Accepts the connection request, then moves the dapp onto the wallet setup's network if there is one. */
+      connectToDapp(): Chainable<void>;
+      rejectConnection(): Chainable<void>;
+      /** Answers a signature request (personal_sign, eth_signTypedData_*). */
+      confirmSignature(): Chainable<void>;
+      rejectSignature(): Chainable<void>;
+      /** Answers a transaction, including ERC-20 approvals. */
+      confirmTransaction(): Chainable<void>;
+      rejectTransaction(): Chainable<void>;
+      /** Answers wallet_addEthereumChain. */
+      approveNewNetwork(): Chainable<void>;
+      rejectNewNetwork(): Chainable<void>;
+      /** Answers the permission asked before switching to a network the dapp isn't allowed on yet. */
+      approveSwitchNetwork(): Chainable<void>;
+      rejectSwitchNetwork(): Chainable<void>;
+      /** Answers wallet_watchAsset ("Add suggested tokens"). */
+      approveAddToken(): Chainable<void>;
+      rejectAddToken(): Chainable<void>;
+      /** Moves the dapp onto a network, adding it to MetaMask if needed. Defaults to the wallet setup's network. Yields the chain id. */
+      useNetwork(network?: Network): Chainable<string>;
+      /** The address the dapp is connected with. */
+      getAccountAddress(): Chainable<string>;
+    }
+  }
+}