dappress 0.3.3 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+What changes for the users of Dappress, version by version. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the versions [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-10-03
+
+### Changed
+
+- The sources are in TypeScript. The package ships compiled JavaScript in `dist`, and its type declarations are generated from the code. `dappress` and `dappress/support` are imported as before.
+- `cy.useNetwork()` goes on as soon as MetaMask has answered a switch it makes without asking, in place of a fixed pause of 1.5 s, and waits for the provider's `chainChanged` in place of asking for the chain every half second.
+
+### Fixed
+
+- The Transaction Shield offer is closed by its cross when MetaMask is not in English. Its "Learn more" button was pressed instead, which opened a tab over MetaMask's page: the next command timed out.
+
+## [0.4.0] - 2026-10-03
+
+### Added
+
+- `cy.lockWallet()`, `cy.unlockWallet()` and `cy.disconnectFromDapp()`.
+- `cy.connectToDapp({ accounts })` chooses the accounts the dapp is connected with.
+- `cy.confirmTransaction({ spendingCap, gas })` sets the spending cap of an ERC-20 approval and the network fee before confirming.
+
+## [0.3.3] - 2026-10-03
+
+### Fixed
+
+- MetaMask's extension is looked for again when its page is read while it loads.
+
+## [0.3.2] - 2026-10-03
+
+### Added
+
+- A failed command says what the MetaMask page shows, and what may keep a button disabled.
+
+### Fixed
+
+- A confirmation is scrolled to its end while its button stays disabled.
+- An element is taken again before each check and click: MetaMask re-renders its screens.
+- MetaMask's popup is given its size back when the window it gets is too small to lay out.
+- A modal over the home screen is dismissed before the account list is opened, by its cross first, and the account menu is pressed again when the list doesn't open.
+- The browser that builds the cached profile starts without the sandbox on Linux, and keeps MetaMask's page in front.
+
+## [0.3.1] - 2026-10-02
+
+### Added
+
+- Headless runs: Dappress passes MetaMask to Chrome itself, since Cypress leaves extensions out of a headless launch.
+
+## [0.3.0] - 2026-10-02
+
+### Changed
+
+- Without a seed phrase, a new wallet is made for each run.
+
+## [0.2.0] - 2026-10-02
+
+### Added
+
+- `cy.addAccount()`, `cy.importAccount()` and `cy.switchAccount()`.
+
+### Changed
+
+- MetaMask's backup and sync is turned off while the wallet is imported, unless `backupAndSync` is set.
+
+## [0.1.1] - 2026-10-02
+
+### Changed
+
+- The error of a confirmation that stays after its button was pressed says whether it is the same request, and what MetaMask logged.
+
+## [0.1.0] - 2026-10-02
+
+### Added
+
+- MetaMask loaded into the browser Cypress launches, the wallet imported from a seed phrase, and commands to answer a dapp's requests: connection, signatures, transactions, networks and tokens.
+- The wallet setup file, `cypress/wallet.setup.ts`, and the opt-in profile cache.
+- TypeScript declarations.
+
+[Unreleased]: https://github.com/blassaut/dappress/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/blassaut/dappress/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/blassaut/dappress/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/blassaut/dappress/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/blassaut/dappress/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/blassaut/dappress/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/blassaut/dappress/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/blassaut/dappress/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/blassaut/dappress/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/blassaut/dappress/releases/tag/v0.1.0

package/README.md

@@ -126,10 +126,12 @@ The wallet is imported once, before the first test of each spec. Each command wa
 | Command | What it does |
 |---|---|
 | `cy.connectToDapp()` | Accepts the connection request, then moves the dapp onto the network of the wallet setup |
+| `cy.connectToDapp({ accounts })` | The same, with the accounts named in `accounts` and no other, such as `['Account 1', 'Account 2']`, in place of the wallet's selected account |
 | `cy.rejectConnection()` | Rejects the connection request |
+| `cy.disconnectFromDapp()` | Disconnects the dapp from MetaMask's permissions screen. The dapp receives an empty `accountsChanged`. |
 | `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.confirmTransaction(options?)` | Sends the transaction, including ERC-20 approvals. With options, sets its spending cap or its network fee first: see [Transaction options](#transaction-options). |
 | `cy.rejectTransaction()` | Rejects the transaction |
 | `cy.approveNewNetwork()` | Adds the network requested by `wallet_addEthereumChain` |
 | `cy.rejectNewNetwork()` | Rejects the network |
@@ -140,10 +142,35 @@ The wallet is imported once, before the first test of each spec. Each command wa
 | `cy.addAccount()` | Adds an account to the wallet and selects it. Yields its name, such as `Account 2`. |
 | `cy.importAccount(privateKey)` | Imports an account from its private key and selects it. Yields its name. The key stays out of the command log. |
 | `cy.switchAccount(name)` | Selects an account of the wallet by its name |
+| `cy.lockWallet()` | Locks the wallet from MetaMask's menu. Requests wait behind its unlock screen until it is unlocked. |
+| `cy.unlockWallet()` | Unlocks the wallet with the configured password. Yields how it was found: `locked`, or `unlocked` when there was nothing to do. |
 | `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. |
 
+### Transaction options
+
+`cy.confirmTransaction()` takes what a user may change on the confirmation before confirming it:
+
+```ts
+// An ERC-20 approval: let the spender use 2.5 tokens, whatever the dapp asked for
+cy.confirmTransaction({ spendingCap: '2.5' });
+
+// The network fee, from the advanced form of MetaMask's fee editor
+cy.confirmTransaction({ gas: { maxBaseFee: 30, priorityFee: 2, gasLimit: 100000 } });
+
+// Or one of the estimates the fee editor lists
+cy.confirmTransaction({ gas: 'aggressive' });
+```
+
+| Option | Value |
+|---|---|
+| `spendingCap` | The amount the spender may use, in tokens, as typed in MetaMask: `5` or `'2.5'`. The command fails on a transaction that is not an ERC-20 approval. |
+| `gas` | `'low'`, `'market'` or `'aggressive'` on a network MetaMask has fee estimates for; `'networkSuggested'` on one it only has a gas price for, such as a local node. The command fails when MetaMask does not list the estimate. |
+| `gas` | Or custom values, named as MetaMask labels them: `maxBaseFee` and `priorityFee` in GWEI, which become the transaction's `maxFeePerGas` and `maxPriorityFeePerGas`, and `gasLimit`. A field left out keeps MetaMask's value. EIP-1559 transactions only. |
+
+Both options can be given together. MetaMask remembers the fee chosen for an account on a network, and starts the next transactions from it.
+
 ### 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:
@@ -189,7 +216,26 @@ The GitHub workflow runs the suite daily, in the three modes, against the latest
 
 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.
+3. Update `src/metamask.ts`, run the suite against the new and the previous release, bump the default version in `src/config.ts`, and commit the report.
+
+## Development
+
+```bash
+npm run lint            # ESLint
+npm run format          # Prettier, on everything but the Markdown files
+npm run check-types     # TypeScript, on the sources, the scripts and the suite
+npm test                # unit tests
+npm run build           # the package, compiled into dist
+```
+
+The CI workflow runs these on every pull request, with `format:check` in place of `format`.
+
+### Releasing
+
+1. Move what `CHANGELOG.md` lists under "Unreleased" to a section for the new version, and set the version in `package.json` (`npm version <version> --no-git-tag-version`).
+2. Commit, then tag the commit `v<version>` and push the tag.
+
+The release workflow checks the tag against `package.json`, publishes the package to npm and makes a GitHub release from the version's section of the changelog. npm trusts the workflow itself ([trusted publishing](https://docs.npmjs.com/trusted-publishers)): no npm token is stored.
 
 ## Architecture
 
@@ -202,17 +248,17 @@ Cypress leaves extensions out of a headless launch, so Dappress passes MetaMask
 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
+src/index.ts            configureDappress(): plugin entry point
+src/config.ts           options and wallet setup file
+src/download.ts         download and cache of MetaMask builds
+src/browser.ts          Puppeteer connection to the Cypress browser
+src/profile.ts          wallet profile built once and reused across runs
+src/metamask-pages.ts   discovery of MetaMask's pages
+src/metamask.ts         MetaMask screens: selectors and flows
+src/page-helpers.ts     wait, click and fill primitives with fallback selectors
+src/actions.ts          Cypress tasks behind the commands
+src/support.ts          cy.* commands
+src/types.ts            types of the public API
 conformance/            conformance suite
 ```
 

package/dist/actions.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedOptions } from './types';
+export declare function createTasks(options: ResolvedOptions): Cypress.Tasks;

package/dist/actions.js

@@ -0,0 +1,114 @@
+"use strict";
+// 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.ts.
+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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTasks = createTasks;
+const browser_1 = require("./browser");
+const metamask = __importStar(require("./metamask"));
+const metamask_pages_1 = 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 (0, metamask_pages_1.findExtensionId)(browser));
+        return extensionId;
+    }
+    /** Onboard the wallet or unlock it, so the dapp can talk to it. Safe to call repeatedly. */
+    const setupWallet = (browser) => openWallet(browser, { onboard: true });
+    async function openWallet(browser, { onboard }) {
+        const home = await (0, metamask_pages_1.getHomePage)(browser, await metamaskId(browser));
+        const state = await metamask.walletState(home);
+        console.log(`[dappress] MetaMask is ${state}`);
+        if (state === 'onboarding' && onboard)
+            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;
+    }
+    /** A task that drives the wallet's own screens, from its full-screen page. */
+    const onHomePage = (flow) => async (browser, argument) => {
+        const home = await (0, metamask_pages_1.getHomePage)(browser, await metamaskId(browser));
+        try {
+            await home.bringToFront();
+            return await flow(home, argument);
+        }
+        finally {
+            await home.close();
+        }
+    };
+    /**
+     * Unlock a locked wallet with the configured password, and say how it was
+     * found. Nothing to do on one already unlocked.
+     */
+    async function unlockWallet(browser) {
+        const state = await openWallet(browser, { onboard: false });
+        if (state === 'onboarding')
+            throw new Error('[dappress] No wallet to unlock: MetaMask is at its onboarding');
+        // The side panel, or a popup opened by a request, keeps its unlock form after an unlock made elsewhere
+        for (const page of await (0, metamask_pages_1.getRequestPages)(browser, await metamaskId(browser)))
+            await metamask.leaveUnlockForm(page, options);
+        return state;
+    }
+    /** Approve the prompt a network change raised: "Add network" or the permission to switch. */
+    async function approveNetworkChange(browser) {
+        const page = await (0, metamask_pages_1.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, argument) => {
+        const page = await (0, metamask_pages_1.getConfirmationPage)(browser, await metamaskId(browser), options.timeout);
+        await metamask.decide(decision, page, options.timeout, argument);
+    };
+    const actions = {
+        setupWallet,
+        approveNetworkChange,
+        addAccount: onHomePage(metamask.addAccount),
+        switchAccount: onHomePage(metamask.switchAccount),
+        importAccount: onHomePage(metamask.importAccount),
+        lockWallet: onHomePage(metamask.lock),
+        unlockWallet,
+        disconnectFromDapp: onHomePage(metamask.disconnectSite),
+    };
+    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 (0, browser_1.withBrowser)((browser) => action(browser, argument))) ?? null;
+    return Object.fromEntries(Object.entries(actions).map(([name, action]) => [`dappress:${name}`, asTask(action)]));
+}

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+import { type Browser } from 'puppeteer-core';
+export declare function captureDebuggerUrl(on: Cypress.PluginEvents): void;
+/**
+ * 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.
+ */
+export declare function withBrowser<T>(action: (browser: Browser) => Promise<T>): Promise<T>;

package/dist/browser.js

@@ -0,0 +1,45 @@
+"use strict";
+// Connects Puppeteer to the browser Cypress launched, through the debugging
+// URL Cypress hands out in after:browser:launch (Cypress 13.6+).
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureDebuggerUrl = captureDebuggerUrl;
+exports.withBrowser = withBrowser;
+const puppeteer_core_1 = __importDefault(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_core_1.default.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();
+}

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+import type { DappressOptions, Network, PublicOptions, ResolvedOptions } from './types';
+export declare const DEFAULTS: {
+    metamaskVersion: string;
+    seedPhrase: string | null;
+    password: string;
+    network: Network | null;
+    backupAndSync: boolean;
+    autoSetup: boolean;
+    cache: boolean;
+    timeout: number;
+    cacheDir: string;
+};
+/**
+ * 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.
+ */
+export declare function resolveOptions(userOptions?: DappressOptions, cypressConfig?: Partial<Pick<Cypress.PluginConfigOptions, 'env' | 'projectRoot'>>): ResolvedOptions;
+/** The subset of options that is safe to expose to the browser side (no secrets). */
+export declare function publicOptions(options: ResolvedOptions): PublicOptions;

package/dist/config.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULTS = void 0;
+exports.resolveOptions = resolveOptions;
+exports.publicOptions = publicOptions;
+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 bip39_1 = require("@scure/bip39");
+const english_1 = require("@scure/bip39/wordlists/english");
+exports.DEFAULTS = {
+    metamaskVersion: '13.50.0',
+    // None: a new wallet is made for each run. A phrase known to others is not
+    // blank, since MetaMask restores the accounts saved for it elsewhere.
+    seedPhrase: null,
+    password: 'Tester@1234',
+    // The network cy.connectToDapp() moves the dapp onto, as a wallet_addEthereumChain parameter; none by default
+    network: null,
+    // MetaMask's backup and sync saves the accounts and contacts of a seed phrase
+    // and restores them on other installs. Off, a test's accounts don't come back.
+    backupAndSync: false,
+    // 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: node_path_1.default.join(node_os_1.default.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 = { ...exports.DEFAULTS, ...userOptions, ...loadWalletSetup(cypressConfig.projectRoot) };
+    for (const [key, value] of Object.entries(fromEnv)) {
+        if (value)
+            options[key] = value;
+    }
+    const seedPhrase = options.seedPhrase || newWallet(options);
+    return { ...options, seedPhrase };
+}
+/** No seed phrase was given: make one for this run. It is never written anywhere. */
+function newWallet(options) {
+    console.log('[dappress] No seed phrase configured: using a new wallet for this run');
+    if (options.cache) {
+        console.warn('[dappress] The profile cache needs a seed phrase of your own: importing the wallet in this run instead');
+        options.cache = false;
+    }
+    return (0, bip39_1.generateMnemonic)(english_1.wordlist);
+}
+/** The project's wallet setup file: { seedPhrase?, network? }. */
+function loadWalletSetup(projectRoot = process.cwd()) {
+    const file = WALLET_SETUP_FILES.map((name) => node_path_1.default.join(projectRoot, name)).find((candidate) => node_fs_1.default.existsSync(candidate));
+    if (!file)
+        return {};
+    // The file is the project's, found at run time: there is nothing to import statically
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    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 ${node_path_1.default.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 };
+}

package/dist/download.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedOptions } from './types';
+/**
+ * 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.
+ */
+export declare function prepareExtension({ metamaskVersion, cacheDir }: Pick<ResolvedOptions, 'metamaskVersion' | 'cacheDir'>): Promise<string>;

package/dist/download.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareExtension = prepareExtension;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = require("node:stream/promises");
+const node_stream_1 = require("node:stream");
+const extract_zip_1 = __importDefault(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 node_path_1.default.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 node_fs_1.default.promises.mkdir(node_path_1.default.dirname(destination), { recursive: true });
+    await (0, promises_1.pipeline)(node_stream_1.Readable.fromWeb(response.body), node_fs_1.default.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 = node_path_1.default.join(dir, 'manifest.json');
+    if (node_fs_1.default.existsSync(manifest))
+        return dir;
+    const zipPath = node_path_1.default.join(cacheDir, 'metamask', `metamask-chrome-${metamaskVersion}.zip`);
+    if (!node_fs_1.default.existsSync(zipPath)) {
+        console.log(`[dappress] Downloading MetaMask ${metamaskVersion}…`);
+        await download(releaseUrl(metamaskVersion), zipPath);
+    }
+    console.log(`[dappress] Unpacking MetaMask ${metamaskVersion}…`);
+    await node_fs_1.default.promises.rm(dir, { recursive: true, force: true });
+    await (0, extract_zip_1.default)(zipPath, { dir });
+    if (!node_fs_1.default.existsSync(manifest)) {
+        throw new Error(`[dappress] ${zipPath} does not look like a MetaMask build: no manifest.json after extraction`);
+    }
+    return dir;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="cypress" preserve="true" />
+import type { DappressOptions } from './types';
+export type { DappressOptions, Network, WalletSetup } from './types';
+/**
+ * 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'.
+ */
+export declare function configureDappress(on: Cypress.PluginEvents, config: Cypress.PluginConfigOptions, userOptions?: DappressOptions): Cypress.PluginConfigOptions;

package/dist/index.js

@@ -0,0 +1,55 @@
+"use strict";
+/// <reference types="cypress" preserve="true" />
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureDappress = configureDappress;
+const config_1 = require("./config");
+const browser_1 = require("./browser");
+const download_1 = require("./download");
+const profile_1 = require("./profile");
+const actions_1 = 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 = (0, config_1.resolveOptions)(userOptions, config);
+    if (config.chromeWebSecurity === false) {
+        console.warn('[dappress] chromeWebSecurity is off: MetaMask cannot start its snaps, so adding or importing an account will hang');
+    }
+    // A cached wallet gets its requests in MetaMask's popup window, which headless Chrome doesn't open
+    const usesCache = (browser) => options.cache && !browser.isHeadless;
+    // Build the wallet profile before the run, out of the time Cypress allows a browser to come up
+    on('before:run', async ({ browser }) => {
+        if (browser && usesCache(browser))
+            await (0, profile_1.prepareProfile)({ browserPath: browser.path, extensionDir: await (0, download_1.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 (0, download_1.prepareExtension)(options);
+        launchOptions.extensions.push(extensionDir);
+        if (browser.isHeadless) {
+            // Cypress leaves extensions out of a headless launch, so ask Chrome directly
+            launchOptions.args.push(`--load-extension=${extensionDir}`);
+            if (options.cache)
+                console.warn('[dappress] The wallet cache needs a headed browser: importing the wallet in this run instead');
+        }
+        if (usesCache(browser)) {
+            const profileDir = await (0, profile_1.prepareProfile)({ browserPath: browser.path, extensionDir, options });
+            await (0, profile_1.installProfile)(profileDir, browser, config.isTextTerminal);
+        }
+        return launchOptions;
+    });
+    (0, browser_1.captureDebuggerUrl)(on);
+    on('task', (0, actions_1.createTasks)(options));
+    // Non-sensitive settings the browser side reads with Cypress.expose()
+    config.expose = { ...config.expose, dappress: (0, config_1.publicOptions)(options) };
+    return config;
+}

package/dist/metamask-pages.d.ts

@@ -0,0 +1,17 @@
+import type { Browser, Page } from 'puppeteer-core';
+/**
+ * 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".
+ */
+export declare function findExtensionId(browser: Browser, timeout?: number): Promise<string>;
+/** The full-screen MetaMask page, opened if it isn't already. */
+export declare function getHomePage(browser: Browser, extensionId: string): Promise<Page>;
+/** The pages open where dapp requests show up: the side panel, a popup. */
+export declare function getRequestPages(browser: Browser, extensionId: string): Promise<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.
+ */
+export declare function getConfirmationPage(browser: Browser, extensionId: string, timeout: number): Promise<Page>;
+export declare function withUsableWindow(page: Page): Promise<Page>;