dappress 0.4.0 → 0.5.1

package/dist/page-helpers.d.ts

@@ -0,0 +1,33 @@
+import type { ElementHandle, Page } from 'puppeteer-core';
+export type Selector = string | string[];
+type WaitOptions = {
+    timeout?: number;
+};
+/** A readable name for a selector, for error messages. */
+export declare function describe(selector: Selector): string;
+/** Wait for the first candidate to be visible and return its element handle. */
+export declare function waitFor(page: Page, selector: Selector, { timeout }?: WaitOptions): Promise<ElementHandle<Element>>;
+/** Returns true when `selector` is visible within `timeout` ms, false otherwise. */
+export declare function isVisible(page: Page, selector: Selector, timeout?: number): Promise<boolean>;
+/** Returns true once every candidate has left the page, or if the page itself closes. */
+export declare function isGone(page: Page, selector: Selector, timeout?: number): Promise<boolean>;
+export declare function click(page: Page, selector: Selector, options?: WaitOptions): Promise<void>;
+/**
+ * Wait until the element is both visible and enabled, then click it. The
+ * element is taken again at each turn: MetaMask re-renders its screens, and
+ * a handle on a replaced element reads its last state forever.
+ */
+export declare function clickWhenEnabled(page: Page, selector: Selector, { timeout, whileDisabled }?: WaitOptions & {
+    whileDisabled?: () => Promise<void>;
+}): Promise<void>;
+/** Click by dispatching the event on the element itself, for buttons something may cover. */
+export declare function dispatchClick(page: Page, selector: Selector, options?: WaitOptions): Promise<void>;
+/** Replace the content of a field with `text`. */
+export declare function fill(page: Page, selector: Selector, text: string, options?: WaitOptions): Promise<void>;
+/**
+ * The error for something that went wrong on `page`: what the page shows, in
+ * words for the log and as a screenshot to look at.
+ */
+export declare function failure(page: Page, message: string): Promise<Error>;
+export declare function sleep(ms: number): Promise<void>;
+export {};

package/dist/page-helpers.js

@@ -0,0 +1,199 @@
+"use strict";
+// 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.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describe = describe;
+exports.waitFor = waitFor;
+exports.isVisible = isVisible;
+exports.isGone = isGone;
+exports.click = click;
+exports.clickWhenEnabled = clickWhenEnabled;
+exports.dispatchClick = dispatchClick;
+exports.fill = fill;
+exports.failure = failure;
+exports.sleep = sleep;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const DEFAULT_TIMEOUT = 15000;
+const SCREENSHOTS_DIR = node_path_1.default.join(node_os_1.default.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 {
+        // Never null: that is for a wait on a hidden element
+        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) {
+    await clickFresh(page, selector, options);
+}
+/**
+ * Wait until the element is both visible and enabled, then click it. The
+ * element is taken again at each turn: MetaMask re-renders its screens, and
+ * a handle on a replaced element reads its last state forever.
+ */
+async function clickWhenEnabled(page, selector, { timeout = DEFAULT_TIMEOUT, whileDisabled } = {}) {
+    const deadline = Date.now() + timeout;
+    let nudged = 0;
+    for (;;) {
+        const element = await waitFor(page, selector, { timeout });
+        if (!(await element.evaluate((el) => el.disabled)))
+            break;
+        if (Date.now() > deadline) {
+            throw await failure(page, `"${describe(selector)}" stayed disabled for ${timeout}ms. ${await describeDisabled(page, element)}`);
+        }
+        // Something the page wants done before it enables the button, every half second
+        if (whileDisabled && Date.now() - nudged > 500) {
+            await whileDisabled();
+            nudged = Date.now();
+        }
+        await sleep(100);
+    }
+    await clickFresh(page, selector, { timeout });
+}
+// What may keep a button disabled: the button itself (a spinner, a class),
+// a pane left to scroll, the page not being the focused one
+async function describeDisabled(page, element) {
+    try {
+        const state = await page.evaluate((button) => {
+            const panes = [...document.querySelectorAll('[style*="overflow"]')]
+                .filter((pane) => pane.scrollHeight > pane.clientHeight)
+                .map((pane) => `${pane.scrollTop}+${pane.clientHeight}/${pane.scrollHeight}`);
+            return {
+                button: button.outerHTML.replace(/\s+/g, ' ').slice(0, 300),
+                panesToScroll: panes,
+                viewport: `${document.documentElement.clientWidth}x${document.documentElement.clientHeight}`,
+                focused: document.hasFocus(),
+                visibility: document.visibilityState,
+            };
+        }, element);
+        return `Button: ${JSON.stringify({ ...state, window: await windowBounds(page) })}.`;
+    }
+    catch {
+        return '';
+    }
+}
+// The size and state of the window the page is in, as "400x620 normal"
+async function windowBounds(page) {
+    const session = await page.target().createCDPSession();
+    try {
+        const { bounds } = await session.send('Browser.getWindowForTarget');
+        return `${bounds.width}x${bounds.height} ${bounds.windowState}`;
+    }
+    catch {
+        return 'unknown';
+    }
+    finally {
+        await session.detach().catch(() => { });
+    }
+}
+// Find the element and click it; once more if a re-render replaced it between the two
+async function clickFresh(page, selector, options) {
+    for (let attempt = 0;; attempt++) {
+        const element = await waitFor(page, selector, options);
+        await waitForStill(element);
+        try {
+            return await element.click();
+        }
+        catch (error) {
+            if (attempt > 0 || !/detached/.test(error.message))
+                throw error;
+        }
+    }
+}
+/** 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`: what the page shows, in
+ * words for the log and as a screenshot to look at.
+ */
+async function failure(page, message) {
+    const prefix = `[dappress] ${message} on ${page.url()}`;
+    const shown = await pageText(page);
+    try {
+        node_fs_1.default.mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+        const file = node_path_1.default.join(SCREENSHOTS_DIR, `${Date.now()}.png`);
+        await page.screenshot({ path: file });
+        return new Error(`${prefix}. ${shown}Screenshot: ${file}`);
+    }
+    catch {
+        return new Error(`${prefix}. ${shown}`.trim());
+    }
+}
+// The visible text of the page, shortened: enough to tell which MetaMask
+// screen it is from the log alone, when the screenshot is out of reach
+async function pageText(page) {
+    try {
+        const text = await Promise.race([page.evaluate(() => document.body.innerText.replace(/\s+/g, ' ').trim()), sleep(2000).then(() => null)]);
+        return text ? `The page shows: "${text.length > 500 ? `${text.slice(0, 500)}…` : text}". ` : '';
+    }
+    catch {
+        return '';
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/profile.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedOptions } from './types';
+type ProfileBuild = {
+    browserPath: string;
+    extensionDir: string;
+    options: ResolvedOptions;
+};
+/** The cached profile for these options, built on first use. */
+export declare function prepareProfile({ browserPath, extensionDir, options }: ProfileBuild): Promise<string>;
+/**
+ * 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.
+ */
+export declare function installProfile(profileDir: string, browser: Cypress.Browser, isTextTerminal?: boolean): Promise<boolean>;
+export {};

package/dist/profile.js

@@ -0,0 +1,165 @@
+"use strict";
+// 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.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareProfile = prepareProfile;
+exports.installProfile = installProfile;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const puppeteer_core_1 = __importDefault(require("puppeteer-core"));
+const metamask = __importStar(require("./metamask"));
+const metamask_pages_1 = 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 = node_crypto_1.default
+        .createHash('sha256')
+        .update([options.metamaskVersion, options.seedPhrase, options.password, options.backupAndSync].join('|'))
+        .digest('hex')
+        .slice(0, 16);
+    let build = builds.get(key);
+    if (!build) {
+        build = buildProfile(node_path_1.default.join(options.cacheDir, 'profiles', key), { browserPath, extensionDir, options });
+        builds.set(key, build);
+    }
+    return build;
+}
+async function buildProfile(dir, { browserPath, extensionDir, options }) {
+    if (node_fs_1.default.existsSync(node_path_1.default.join(dir, 'ready')))
+        return dir;
+    console.log('[dappress] Importing the wallet once, into a cached profile…');
+    await node_fs_1.default.promises.rm(dir, { recursive: true, force: true });
+    const launch = () => puppeteer_core_1.default.launch({
+        executablePath: browserPath,
+        headless: false,
+        userDataDir: dir,
+        args: [
+            `--load-extension=${extensionDir}`,
+            `--disable-extensions-except=${extensionDir}`,
+            '--no-first-run',
+            // No sandbox on Linux: Ubuntu 23.10+ (GitHub's ubuntu-latest) blocks the
+            // user namespaces it needs, and this browser only imports a test wallet
+            ...(process.platform === 'linux' ? ['--no-sandbox'] : []),
+        ],
+    });
+    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);
+    });
+    node_fs_1.default.writeFileSync(node_path_1.default.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 {
+        const home = await (0, metamask_pages_1.getHomePage)(browser, await (0, metamask_pages_1.findExtensionId)(browser));
+        await keepInFront(browser, home);
+        await action(home);
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+    }
+    finally {
+        await browser.close();
+    }
+}
+// Chrome stops rendering a tab that isn't the active one, and Puppeteer waits
+// on rendering to find an element or to click it: a hidden tab never answers.
+// So the home page is made the active tab, and again whenever MetaMask opens
+// a tab of its own, as it does for its onboarding right after the install.
+async function keepInFront(browser, home) {
+    const toFront = () => home.bringToFront().catch(() => { });
+    await toFront();
+    browser.on('targetcreated', (target) => {
+        if (target.type() !== 'page')
+            return;
+        toFront();
+        setTimeout(toFront, 500);
+    });
+}
+// 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 = [
+        node_path_1.default.join(node_os_1.default.homedir(), 'Library', 'Application Support'),
+        process.env.XDG_CONFIG_HOME || node_path_1.default.join(node_os_1.default.homedir(), '.config'),
+        process.env.APPDATA,
+    ].filter((dir) => Boolean(dir));
+    const cypressData = appData.map((dir) => node_path_1.default.join(dir, 'Cypress', 'cy')).find((dir) => node_fs_1.default.existsSync(dir));
+    if (!cypressData)
+        return null;
+    const env = ['production', 'development'].find((name) => node_fs_1.default.existsSync(node_path_1.default.join(cypressData, name)));
+    if (!env)
+        return null;
+    return node_path_1.default.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 node_fs_1.default.promises.cp(node_path_1.default.join(profileDir, entry), node_path_1.default.join(userDataDir, entry), { recursive: true });
+    }
+    return true;
+}
+// Where Chrome keeps an extension's storage: chrome.storage.local and IndexedDB
+function metamaskData(profileDir) {
+    const base = node_path_1.default.join(profileDir, 'Default');
+    const entries = ['Local Extension Settings', 'IndexedDB'];
+    return entries
+        .filter((entry) => node_fs_1.default.existsSync(node_path_1.default.join(base, entry)))
+        .flatMap((entry) => node_fs_1.default.readdirSync(node_path_1.default.join(base, entry)).map((name) => node_path_1.default.join('Default', entry, name)));
+}

package/dist/support.d.ts

@@ -0,0 +1,45 @@
+/// <reference types="cypress" preserve="true" />
+import type { ConnectOptions, Network, TransactionOptions, WalletState } from './types';
+export type { ConnectOptions, CustomGas, GasEstimate, TransactionOptions, WalletState } from './types';
+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, with the accounts named in `accounts` if any, then moves the dapp onto the wallet setup's network if there is one. */
+            connectToDapp(options?: ConnectOptions): Chainable<void>;
+            rejectConnection(): Chainable<void>;
+            /** Disconnects the dapp from the wallet's permissions screen: the dapp gets an empty accountsChanged. */
+            disconnectFromDapp(): Chainable<void>;
+            /** Answers a signature request (personal_sign, eth_signTypedData_*). */
+            confirmSignature(): Chainable<void>;
+            rejectSignature(): Chainable<void>;
+            /** Answers a transaction, including ERC-20 approvals. Confirming takes what to set first: a spending cap, a network fee. */
+            confirmTransaction(options?: TransactionOptions): 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>;
+            /** Adds an account to the wallet and selects it. Yields its name, "Account N". */
+            addAccount(): Chainable<string>;
+            /** Selects an account of the wallet by its name. */
+            switchAccount(name: string): Chainable<void>;
+            /** Imports an account from its private key and selects it. Yields its name. */
+            importAccount(privateKey: string): Chainable<string>;
+            /** Locks the wallet from MetaMask's menu: requests wait behind its unlock screen until it is unlocked. */
+            lockWallet(): Chainable<void>;
+            /** Unlocks a locked wallet with the configured password. Yields how it was found: "unlocked" when there was nothing to do. */
+            unlockWallet(): Chainable<WalletState>;
+            /** 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>;
+        }
+    }
+}

package/dist/support.js

@@ -0,0 +1,113 @@
+"use strict";
+/// <reference types="cypress" preserve="true" />
+Object.defineProperty(exports, "__esModule", { value: true });
+// A network change MetaMask makes without asking is answered well within this (ms)
+const SILENT_SWITCH = 1500;
+// How long MetaMask may take to announce the new chain to the dapp (ms)
+const CHAIN_ANNOUNCED = 10000;
+const options = Cypress.expose('dappress') || {};
+const dappWindow = () => cy.window({ log: false });
+// `shown` is what the command log displays for the argument, if anything
+function metamask(action, argument = null, shown = '') {
+    Cypress.log({ name: 'metamask', message: `${action} ${shown}`.trim() });
+    return cy.task(`dappress:${action}`, argument, { log: false });
+}
+function provider(method, params) {
+    return dappWindow().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'));
+// Options are what to set on the confirmation before confirming it: { spendingCap, gas }
+Cypress.Commands.add('confirmTransaction', (options) => metamask('confirmTransaction', options, options ? JSON.stringify(options) : ''));
+Cypress.Commands.add('rejectTransaction', () => metamask('rejectTransaction'));
+Cypress.Commands.add('approveAddToken', () => metamask('approveAddToken'));
+Cypress.Commands.add('rejectAddToken', () => metamask('rejectAddToken'));
+// The wallet's own accounts. A new or imported account becomes the selected
+// one; the dapp sees it once it connects with it.
+Cypress.Commands.add('addAccount', () => metamask('addAccount'));
+Cypress.Commands.add('switchAccount', (name) => metamask('switchAccount', name, name));
+// The private key is kept out of the command log
+Cypress.Commands.add('importAccount', (privateKey) => metamask('importAccount', privateKey));
+// A locked wallet keeps the dapp's requests behind its unlock screen
+Cypress.Commands.add('lockWallet', () => metamask('lockWallet'));
+Cypress.Commands.add('unlockWallet', () => metamask('unlockWallet'));
+// The wallet's side of a disconnection: the site to remove from its
+// permissions is the dapp under test, known by the origin of its window.
+Cypress.Commands.add('disconnectFromDapp', () => {
+    cy.location('origin', { log: false }).then((origin) => metamask('disconnectFromDapp', origin, origin));
+});
+// Connect, then move the dapp onto the network from the wallet setup, if there is one.
+// `accounts` names the accounts to connect with, in place of the one MetaMask suggests.
+Cypress.Commands.add('connectToDapp', (connection) => {
+    metamask('connectToDapp', connection, connection?.accounts?.join(', '));
+    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 ?? undefined) => {
+    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}` });
+    let request;
+    // Whether MetaMask asks: the request is still pending once a silent switch would have been answered
+    dappWindow()
+        .then((win) => {
+        request = win.ethereum.request({ method: 'wallet_addEthereumChain', params: [network] }).then((result) => ({ result }), (error) => ({ error }));
+        const silent = new Promise((resolve) => setTimeout(resolve, SILENT_SWITCH, false));
+        return Promise.race([request.then(() => true), silent]);
+    })
+        .then((answered) => {
+        if (!answered)
+            metamask('approveNetworkChange');
+    });
+    dappWindow()
+        .then({ timeout: 60000 }, () => 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: the
+// dapp is on it already, or the provider's chainChanged says when it is
+function waitForChainId(chainId) {
+    return dappWindow().then({ timeout: CHAIN_ANNOUNCED + 1000 }, (win) => {
+        return new Promise((resolve, reject) => {
+            let current;
+            const settle = (act) => {
+                clearTimeout(timer);
+                win.ethereum.removeListener('chainChanged', onChainChanged);
+                act();
+            };
+            const onChainChanged = (announced) => {
+                current = announced;
+                if (announced === chainId)
+                    settle(() => resolve(chainId));
+            };
+            const timer = setTimeout(() => settle(() => reject(new Error(`[dappress] The dapp is on chain ${current}, not ${chainId}`))), CHAIN_ANNOUNCED);
+            // Listening first: a change announced while the chain is asked for is not missed
+            win.ethereum.on('chainChanged', onChainChanged);
+            win.ethereum.request({ method: 'eth_chainId' }).then(onChainChanged, () => { });
+        });
+    });
+}
+// Onboard or unlock the wallet once per spec, before the dapp needs it.
+if (options.autoSetup !== false) {
+    before(() => {
+        cy.setupMetaMask();
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+/** 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 {
+    /**
+     * The wallet to import. Without one, Dappress makes a new wallet for each run.
+     * 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;
+    /**
+     * Keep MetaMask's backup and sync on. It saves the accounts and contacts of a
+     * seed phrase and restores them on other installs. Default: false.
+     */
+    backupAndSync?: boolean;
+    /** 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. Headed runs only. 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;
+}
+/** The options once resolved: every one has a value, the seed phrase included. */
+export interface ResolvedOptions {
+    metamaskVersion: string;
+    seedPhrase: string;
+    password: string;
+    network: Network | null;
+    backupAndSync: boolean;
+    autoSetup: boolean;
+    cache: boolean;
+    timeout: number;
+    cacheDir: string;
+}
+/** The subset of the options the browser side reads with Cypress.expose(). */
+export type PublicOptions = Pick<ResolvedOptions, 'metamaskVersion' | 'autoSetup' | 'network'>;
+export type WalletState = 'onboarding' | 'locked' | 'unlocked';
+export type ConnectOptions = {
+    /**
+     * The accounts to connect the dapp with, by their names in MetaMask:
+     * `['Account 1', 'Account 2']`. These and no other are connected, in the
+     * order MetaMask gives them to the dapp, whatever their order here.
+     * Default: the account MetaMask suggests, the wallet's selected one.
+     */
+    accounts?: string[];
+};
+/** What cy.confirmTransaction() sets on the confirmation before confirming it. */
+export interface TransactionOptions {
+    /**
+     * On an ERC-20 approval, the amount the spender may use, in tokens, as a user types it: 5 or '2.5'.
+     * A string keeps an amount a number would round. Fails on a transaction that has no spending cap.
+     */
+    spendingCap?: number | string;
+    /**
+     * The network fee: one of the estimates MetaMask's fee editor offers for the network, or custom values.
+     * Fails when MetaMask doesn't offer that estimate.
+     */
+    gas?: GasEstimate | CustomGas;
+}
+/**
+ * An estimate of MetaMask's fee editor, by the name it shows. Low, Market and Aggressive are offered on the
+ * networks MetaMask has fee estimates for; Network suggested on those it only has a gas price for, such as a local node.
+ */
+export type GasEstimate = 'low' | 'market' | 'aggressive' | 'networkSuggested';
+/** The fields of the fee editor's advanced form, on an EIP-1559 transaction. One left out keeps MetaMask's value. */
+export interface CustomGas {
+    /** "Max base fee", in GWEI: the transaction's maxFeePerGas. */
+    maxBaseFee?: number | string;
+    /** "Priority fee", in GWEI: the transaction's maxPriorityFeePerGas. At most the max base fee. */
+    priorityFee?: number | string;
+    /** "Gas limit", in units of gas: 21000 or more. */
+    gasLimit?: number | string;
+}