dappress 0.3.2 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 **MetaMask automation for Cypress.**
 
+[![MetaMask conformance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/blassaut/dappress/conformance-reports/badge.json)](https://github.com/blassaut/dappress/blob/conformance-reports/MATRIX.md)
+
 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.
@@ -124,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 |
@@ -138,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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dappress",
-  "version": "0.3.2",
+  "version": "0.4.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",

package/src/actions.js

@@ -4,7 +4,7 @@
 
 const { withBrowser } = require('./browser');
 const metamask = require('./metamask');
-const { findExtensionId, getHomePage, getConfirmationPage } = require('./metamask-pages');
+const { findExtensionId, getHomePage, getRequestPages, getConfirmationPage } = require('./metamask-pages');
 
 function createTasks(options) {
   // Found once: the browser is the same for the whole run
@@ -16,11 +16,13 @@ function createTasks(options) {
   }
 
   /** Onboard the wallet or unlock it, so the dapp can talk to it. Safe to call repeatedly. */
-  async function setupWallet(browser) {
+  const setupWallet = (browser) => openWallet(browser, { onboard: true });
+
+  async function openWallet(browser, { onboard }) {
     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 === '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();
@@ -38,6 +40,18 @@ function createTasks(options) {
     }
   };
 
+  /**
+   * 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 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 getConfirmationPage(browser, await metamaskId(browser), options.timeout);
@@ -45,9 +59,9 @@ function createTasks(options) {
   }
 
   /** The task for a decision: find the confirmation, press its button. */
-  const decide = (decision) => async (browser) => {
+  const decide = (decision) => async (browser, argument) => {
     const page = await getConfirmationPage(browser, await metamaskId(browser), options.timeout);
-    await metamask.decide(decision, page, options.timeout);
+    await metamask.decide(decision, page, options.timeout, argument);
   };
 
   const actions = {
@@ -56,6 +70,9 @@ function createTasks(options) {
     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);
 

package/src/metamask-pages.js

@@ -41,8 +41,14 @@ async function findExtensionId(browser, timeout = 30000) {
 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');
+    // A page still loading or redirecting loses its execution context while its
+    // title is read; not MetaMask yet, findExtensionId looks again
+    try {
+      const page = await target.page();
+      return (await page.title()).startsWith('MetaMask');
+    } catch {
+      return false;
+    }
   }
   const page = await browser.newPage();
   try {
@@ -64,6 +70,18 @@ async function getHomePage(browser, extensionId) {
   return page;
 }
 
+/** The pages open where dapp requests show up: the side panel, a popup. */
+async function getRequestPages(browser, extensionId) {
+  const pages = [];
+  for (const pathname of CONFIRMATION_PATHS) {
+    for (const target of pagesOf(browser, extensionId, pathname)) {
+      const page = await target.page();
+      if (page) pages.push(pathname === '/notification.html' ? await withUsableWindow(page) : page);
+    }
+  }
+  return pages;
+}
+
 /**
  * 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
@@ -112,4 +130,4 @@ async function withUsableWindow(page) {
   return page;
 }
 
-module.exports = { findExtensionId, getHomePage, getConfirmationPage, withUsableWindow };
+module.exports = { findExtensionId, getHomePage, getRequestPages, getConfirmationPage, withUsableWindow };

package/src/metamask.js

@@ -12,6 +12,7 @@ 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 linkText = (text) => `xpath/.//a[normalize-space(.)="${text}"]`;
 const passwordInput = (position) => `xpath/(.//input[@type="password"])[${position}]`;
 
 const selectors = {
@@ -46,6 +47,27 @@ const selectors = {
     header: testId('parent-selector-header-navbar'),
     accountMenu: testId('account-menu-icon'),
   },
+  // The menu of the home header, a drawer: settings, permissions, lock
+  menu: {
+    open: [testId('account-options-menu-button'), 'button[aria-label="Account options"]'],
+    lock: [testId('global-menu-lock'), buttonText('Lock')],
+    permissions: [testId('global-menu-connected-sites'), linkText('Permissions')],
+  },
+  // "Permissions": the sites connected to the wallet, then the page of one site
+  permissions: {
+    list: testId('parent-selector-permission-list'),
+    // Shown first when the wallet also holds token permissions; "Connections" leads to the list
+    hub: testId('parent-selector-gator-permissions'),
+    connections: 'xpath/.//p[normalize-space(.)="Connections"]',
+    // A site is listed by its host, "localhost:3000"
+    site: (host) => [
+      `xpath/.//*[@data-testid="connection-list-item"][.//p[normalize-space(.)="${host}"]]`,
+      `xpath/.//p[normalize-space(.)="${host}"]`,
+    ],
+    disconnect: [testId('disconnect-button'), 'button[aria-label="Disconnect"]'],
+    // "Disconnect", in the modal that asks to confirm
+    confirmDisconnect: [testId('disconnect-all'), `xpath/.//*[@data-testid="disconnect-all-modal"]//button[normalize-space(.)="Disconnect"]`],
+  },
   // The account list, opened from the home header
   accounts: {
     name: '[data-testid^="multichain-account-cell-name-"]',
@@ -62,6 +84,19 @@ const selectors = {
     confirm: [testId('confirm-btn'), buttonText('Connect')],
     cancel: [testId('cancel-btn'), buttonText('Cancel')],
   },
+  // The accounts of a connection: the request names the one it suggests, and
+  // pressing it opens the list of the wallet's accounts, a checkbox on each
+  connectAccounts: {
+    // The suggested account, or their count when there are several
+    edit: [testId('account-selection-section'), '[data-testid="parent-selector-connect-page"] .multichain-account-cell, [data-testid^="accounts-count-"]'],
+    checkbox: (name) => `xpath/.//*[contains(@class, "multichain-account-cell")][.//*[@data-testid="multichain-account-cell-name-${name}"]]//input[@type="checkbox"]`,
+    save: [testId('connect-more-accounts-button'), buttonText('Save')],
+    // What the request shows once the list is saved: the account alone, or how many there are
+    chosen: (names) =>
+      names.length === 1
+        ? `[data-testid="parent-selector-connect-page"] [data-testid="multichain-account-cell-name-${names[0]}"]`
+        : testId(`accounts-count-${names.length}`),
+  },
   // Signatures, transactions and "Add network" share the same confirmation footer
   confirmation: {
     confirm: [testId('confirm-footer-button'), buttonText('Confirm'), buttonText('Approve')],
@@ -71,6 +106,24 @@ const selectors = {
     // The pane the content scrolls in, by its inline style: it has no test id
     scrollPane: '[style*="overflow: auto"]',
   },
+  // What a transaction lets its reader change before confirming it: the
+  // spending cap of an ERC-20 approval, and the network fee
+  transaction: {
+    // The pencil of the "Spending cap" row, before the amount it edits
+    editSpendingCap: [testId('edit-spending-cap-icon'), 'xpath/.//button[@aria-label="Edit"][following::*[@data-testid="simulation-token-value"]]'],
+    spendingCap: testId('simulation-token-value'),
+    spendingCapInput: [testId('custom-spending-cap-input'), '.edit-spending-cap-modal input'],
+    // "Save", the last button of the modal's footer: it has no test id
+    spendingCapSave: ['.edit-spending-cap-modal .mm-modal-footer__button:last-child', 'xpath/.//*[contains(@class, "edit-spending-cap-modal")]//button[normalize-space(.)="Save"]'],
+    // The pencil of the "Network fee" row opens the fee editor: a list of
+    // estimates, whose last entry, "Advanced", leads to a form
+    editGas: [testId('edit-gas-fee-icon'), `${testId('gas-fee-section')} button[aria-label="Edit"]`],
+    gasEstimates: testId('gas-fee-estimates-modal'),
+    gasOption: (key, label) => [testId(`gas-option-${key}`), `xpath/.//*[@data-testid="gas-fee-estimates-modal"]//p[normalize-space(.)="${label}"]`],
+    gasForm: testId('gas-fee-advanced-eip1559-modal'),
+    gasField: (id) => [`#${id}`, `${testId(id)} input`],
+    gasSave: [testId('gas-fee-modal-save-button'), buttonText('Save')],
+  },
   // The older footer, still used by the permission update a network switch
   // asks for, by "Add suggested tokens", and by template confirmations
   pageContainer: {
@@ -151,9 +204,28 @@ async function fillSeedPhrase(page, seedPhrase) {
 }
 
 async function unlock(page, { password }) {
+  await submitPassword(page, password);
+  await reachHome(page, { password });
+}
+
+async function submitPassword(page, password) {
   await fill(page, selectors.unlock.password, password);
   await click(page, selectors.unlock.submit);
-  await reachHome(page, { password });
+}
+
+/**
+ * A page that was showing the unlock form when the wallet got unlocked from
+ * another one keeps showing it, and the dapp's requests wait behind it. The
+ * password is given there too, as a user would; what follows is the wallet
+ * or a request, so only the form is watched.
+ */
+async function leaveUnlockForm(page, { password }) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (!(await isVisible(page, selectors.unlock.password, 500))) return;
+    await submitPassword(page, password);
+    if (await isGone(page, selectors.unlock.password, 10000)) return;
+  }
+  throw await failure(page, 'MetaMask kept showing its unlock form');
 }
 
 /**
@@ -184,10 +256,7 @@ async function reachHome(page, { password, backupAndSync }) {
       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);
-    }
+    if (await isVisible(page, selectors.unlock.password, 500)) await submitPassword(page, password);
   }
   throw await failure(page, 'MetaMask did not show the wallet');
 }
@@ -322,8 +391,152 @@ async function importAccount(page, privateKey) {
   throw await failure(page, 'MetaMask did not import the account');
 }
 
-/** Press the button of `decision` on the confirmation shown on `page`. */
-function decide(decision, page, timeout) {
+/** Lock the wallet from the menu of its home page. Nothing to do on a wallet already locked. */
+async function lock(page) {
+  if ((await walletState(page)) === 'locked') return;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await openMenu(page);
+    await click(page, selectors.menu.lock);
+    if (await isVisible(page, selectors.unlock.password, 10000)) return;
+  }
+  throw await failure(page, 'MetaMask did not lock');
+}
+
+// As with the account list, a click on the menu is lost while the home screen
+// settles or swallowed by a modal, so it is pressed again until the menu shows.
+async function openMenu(page) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await page.bringToFront().catch(() => {});
+    await dismissModal(page);
+    await click(page, selectors.menu.open);
+    if (await isVisible(page, selectors.menu.lock, 5000)) return;
+  }
+  throw await failure(page, 'MetaMask did not open its menu');
+}
+
+/**
+ * Disconnect the site at `origin` from the wallet, on its page of the
+ * "Permissions" screen. The dapp gets an empty accountsChanged.
+ */
+async function disconnectSite(page, origin) {
+  const s = selectors.permissions;
+  const { host } = new URL(origin);
+  await openConnections(page);
+  if (!(await isVisible(page, s.site(host), 5000))) throw await failure(page, `MetaMask lists no connection to "${host}"`);
+  await openSite(page, host);
+  // Disconnecting goes back to the list, without the site. A lost click
+  // leaves the site's page or the modal showing, and is pressed again.
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (!(await isVisible(page, s.confirmDisconnect, 500))) await click(page, s.disconnect);
+    if (!(await isVisible(page, s.confirmDisconnect, 5000))) continue;
+    await click(page, s.confirmDisconnect);
+    if ((await isGone(page, [...s.confirmDisconnect, ...s.disconnect], 5000)) && (await isGone(page, s.site(host), 5000))) return;
+  }
+  throw await failure(page, `MetaMask did not disconnect "${host}"`);
+}
+
+/** The list of connected sites, from the menu's "Permissions". */
+async function openConnections(page) {
+  const s = selectors.permissions;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await openMenu(page);
+    await click(page, selectors.menu.permissions);
+    if (!(await isVisible(page, [s.list, s.hub], 10000))) continue;
+    if (await isVisible(page, s.list, 500)) return;
+    // The hub goes on to the list by itself when there is nothing else to show
+    if (await isVisible(page, s.connections, 3000)) await click(page, s.connections);
+    if (await isVisible(page, s.list, 10000)) return;
+  }
+  throw await failure(page, 'MetaMask did not open its permissions');
+}
+
+async function openSite(page, host) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await click(page, selectors.permissions.site(host));
+    if (await isVisible(page, selectors.permissions.disconnect, 5000)) return;
+  }
+  throw await failure(page, `MetaMask did not open the permissions of "${host}"`);
+}
+
+// What a command sets on its confirmation before pressing the button, when the
+// test passed it options: adjustments[command](page, options, timeout)
+const adjustments = {
+  connectToDapp: chooseAccounts,
+  confirmTransaction: adjustTransaction,
+};
+
+/**
+ * Connect the dapp with the accounts named in `accounts` and no other, in the
+ * list the connection request opens: the boxes of the others are unticked,
+ * theirs ticked, and the list saved, which goes back to the request.
+ */
+async function chooseAccounts(page, { accounts }) {
+  if (accounts === undefined) return;
+  if (!Array.isArray(accounts) || accounts.length === 0) throw new Error('[dappress] connectToDapp({ accounts }) needs the name of at least one account');
+  const wanted = [...new Set(accounts)];
+  await openConnectAccounts(page);
+  const listed = await accountNames(page);
+  const unknown = wanted.filter((name) => !listed.includes(name));
+  if (unknown.length) {
+    const quoted = (names) => names.map((name) => `"${name}"`).join(', ');
+    throw await failure(page, `MetaMask lists no account named ${quoted(unknown)} to connect: it lists ${quoted(listed)}`);
+  }
+  for (const name of listed) await tickAccount(page, name, wanted.includes(name));
+  await saveConnectAccounts(page, wanted);
+}
+
+// As elsewhere, a click that lands while the request settles is lost: pressed again until the list shows
+async function openConnectAccounts(page) {
+  const s = selectors.connectAccounts;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (!(await isVisible(page, s.save, 500))) await click(page, s.edit);
+    if (await isVisible(page, s.save, 5000)) return;
+  }
+  throw await failure(page, 'MetaMask did not open the accounts of the connection');
+}
+
+// A click on an account's row ticks or unticks its box. The box is read
+// before each click: a second click on a row that took the first undoes it.
+async function tickAccount(page, name, ticked) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (await isTicked(page, name, ticked, 500)) return;
+    await click(page, selectors.accounts.cell(name));
+    if (await isTicked(page, name, ticked, 3000)) return;
+  }
+  throw await failure(page, `MetaMask did not ${ticked ? 'tick' : 'untick'} "${name}"`);
+}
+
+async function isTicked(page, name, ticked, timeout) {
+  const deadline = Date.now() + timeout;
+  do {
+    const checkbox = await page.$(selectors.connectAccounts.checkbox(name));
+    const state = checkbox ? await checkbox.evaluate((el) => el.checked).catch(() => null) : null;
+    if (state === ticked) return true;
+    await sleep(250);
+  } while (Date.now() < deadline);
+  return false;
+}
+
+// Saving goes back to the request, which then shows what was chosen
+async function saveConnectAccounts(page, names) {
+  const s = selectors.connectAccounts;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (await isVisible(page, s.save, 500)) await clickWhenEnabled(page, s.save);
+    if (!(await isGone(page, s.save, 5000))) continue;
+    if (await isVisible(page, s.chosen(names), 5000)) return;
+    break;
+  }
+  throw await failure(page, `MetaMask did not keep ${names.map((name) => `"${name}"`).join(', ')} as the accounts to connect`);
+}
+
+/** Press the button of `decision` on the confirmation shown on `page`, once it is set as `options` ask. */
+async function decide(decision, page, timeout, options) {
+  if (options) {
+    const adjust = adjustments[decision];
+    if (!adjust) throw new Error(`[dappress] ${decision} takes no options`);
+    await waitFor(page, decisions[decision], { timeout });
+    await adjust(page, options, timeout);
+  }
   return pressAndWaitForDismissal(page, decisions[decision], timeout);
 }
 
@@ -332,6 +545,161 @@ function approveNetworkChange(page, timeout) {
   return pressAndWaitForDismissal(page, [...selectors.confirmation.confirm, ...selectors.pageContainer.confirm], timeout);
 }
 
+// The estimates of the fee editor, by the name MetaMask shows: its test id and its English label
+const gasEstimates = { low: ['low', 'Low'], market: ['medium', 'Market'], aggressive: ['high', 'Aggressive'], networkSuggested: ['gasPrice', 'Network suggested'] };
+// The fields of the fee editor's advanced form, by the name MetaMask labels them with
+const gasFields = { maxBaseFee: 'max-base-fee-input', priorityFee: 'priority-fee-input', gasLimit: 'gas-input' };
+
+/**
+ * Set what the test asked of a transaction before it is confirmed. The cap
+ * goes first: saving it makes MetaMask estimate the gas limit again.
+ */
+async function adjustTransaction(page, options) {
+  const { spendingCap, gas, ...unknown } = options;
+  const [stray] = Object.keys(unknown);
+  if (stray) throw new Error(`[dappress] confirmTransaction takes spendingCap and gas, not "${stray}"`);
+  const cap = spendingCap === undefined ? undefined : amount(spendingCap, 'spendingCap');
+  const fee = gas === undefined ? undefined : gasChoice(gas);
+  await dismissModal(page);
+  if (cap !== undefined) await setSpendingCap(page, cap);
+  if (fee !== undefined) await setGas(page, fee);
+}
+
+// An amount as a user types it, "5" or "2.5", from a number or a string
+function amount(value, name) {
+  const text = String(value).trim();
+  if (!/^\d+(\.\d+)?$/.test(text)) throw new Error(`[dappress] ${name} is an amount such as 5 or '2.5', not ${JSON.stringify(value)}`);
+  return text;
+}
+
+// The estimate to pick, or the fields of the advanced form to fill with what
+function gasChoice(gas) {
+  if (typeof gas === 'string') {
+    if (!gasEstimates[gas]) throw new Error(`[dappress] gas is ${Object.keys(gasEstimates).join(', ')} or custom values, not "${gas}"`);
+    return gas;
+  }
+  const fields = Object.keys(gas || {});
+  const [stray] = fields.filter((field) => !gasFields[field]);
+  if (stray || !fields.length) throw new Error(`[dappress] Custom gas takes ${Object.keys(gasFields).join(', ')}, not ${stray ? `"${stray}"` : 'nothing'}`);
+  return Object.fromEntries(fields.map((field) => [field, amount(gas[field], `gas.${field}`)]));
+}
+
+/**
+ * Set the amount an ERC-20 approval lets the spender use, in tokens, from the
+ * pencil of its "Spending cap" row. The row shows once MetaMask has read the
+ * token, and only an ERC-20 approval has one.
+ */
+async function setSpendingCap(page, cap) {
+  const s = selectors.transaction;
+  if (!(await isVisible(page, s.editSpendingCap, 10000))) throw await failure(page, 'MetaMask shows no spending cap to edit: spendingCap is for an ERC-20 approval');
+  const shown = await textOf(page, s.spendingCap);
+  const asked = await openSpendingCap(page);
+  await type(page, s.spendingCapInput, cap, 'spending cap');
+  if (!(await pressToClose(page, s.spendingCapSave, s.spendingCapInput))) throw await failure(page, `MetaMask did not save the spending cap of ${cap}`);
+  // The modal closes before the confirmation has the new cap, and confirming
+  // meanwhile approves the old one. Two caps may read the same once MetaMask
+  // has rounded them, so a row that stays as it was is not a failure.
+  const deadline = Date.now() + (Number(asked) === Number(cap) ? 0 : 5000);
+  while (Date.now() < deadline && (await textOf(page, s.spendingCap)) === shown) await sleep(250);
+}
+
+/** Open the spending cap's modal. Yields the cap the dapp asked for, which its field starts with. */
+async function openSpendingCap(page) {
+  const s = selectors.transaction;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (!(await isVisible(page, s.spendingCapInput, 500))) await click(page, s.editSpendingCap);
+    if (await isVisible(page, s.spendingCapInput, 5000)) return valueOf(page, s.spendingCapInput);
+  }
+  throw await failure(page, 'MetaMask did not open the spending cap');
+}
+
+/**
+ * Set the network fee in the fee editor, opened from the pencil of the
+ * "Network fee" row: one of its estimates, or the values of its advanced form.
+ */
+async function setGas(page, gas) {
+  const s = selectors.transaction;
+  if (!(await isVisible(page, s.editGas, 10000))) throw await failure(page, 'MetaMask shows no network fee to edit on this confirmation');
+  await openFeeEditor(page);
+  if (typeof gas === 'string') await pickGasEstimate(page, gas);
+  else await fillGasForm(page, gas);
+}
+
+async function openFeeEditor(page) {
+  const s = selectors.transaction;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (!(await isVisible(page, s.gasEstimates, 500))) await click(page, s.editGas);
+    if (await isVisible(page, s.gasEstimates, 5000)) return;
+  }
+  throw await failure(page, 'MetaMask did not open its fee editor');
+}
+
+// Picking an estimate closes the editor. MetaMask lists the estimates it has
+// for the network: Low, Market and Aggressive where it has fee estimates,
+// "Network suggested" where it only has a gas price, as on a local node.
+async function pickGasEstimate(page, name) {
+  const s = selectors.transaction;
+  const option = s.gasOption(...gasEstimates[name]);
+  if (!(await isVisible(page, option, 5000))) throw await failure(page, `MetaMask offers no "${name}" fee for this transaction`);
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await click(page, option);
+    if (await isGone(page, s.gasEstimates, 10000)) return;
+  }
+  throw await failure(page, `MetaMask did not take the "${name}" fee`);
+}
+
+async function fillGasForm(page, values) {
+  const s = selectors.transaction;
+  await openGasForm(page);
+  // The form checks each fee against the other as it stood, and keeps the old
+  // value of a fee it refused: the max base fee is typed again once the
+  // priority fee is in, for two fees that both move below or above the old ones.
+  const fields = Object.keys(gasFields).filter((field) => values[field] !== undefined);
+  if (values.maxBaseFee !== undefined && values.priorityFee !== undefined) fields.push('maxBaseFee');
+  for (const field of fields) await type(page, s.gasField(gasFields[field]), values[field], field);
+  // "Save" stays disabled on a value the form refuses, and the error quotes what the form says of it
+  if (!(await pressToClose(page, s.gasSave, s.gasForm))) throw await failure(page, 'MetaMask did not save the network fee');
+}
+
+// "Advanced", in the list of estimates, replaces the list with the form. A
+// transaction with a gas price gets another form, which has none of these fields.
+async function openGasForm(page) {
+  const s = selectors.transaction;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (!(await isVisible(page, s.gasForm, 500))) await click(page, s.gasOption('advanced', 'Advanced'));
+    if (await isVisible(page, s.gasForm, 5000)) return;
+  }
+  throw await failure(page, 'MetaMask did not open the advanced fee form of an EIP-1559 transaction');
+}
+
+// Type into a field and read it back: keys pressed while MetaMask re-renders are lost
+async function type(page, selector, text, what) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await fill(page, selector, text);
+    if (Number(await valueOf(page, selector)) === Number(text)) return;
+  }
+  throw await failure(page, `MetaMask's field for the ${what} did not take "${text}"`);
+}
+
+// Press the button that saves a modal until the modal closes: a lost click leaves it open
+async function pressToClose(page, button, content) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await clickWhenEnabled(page, button);
+    if (await isGone(page, content, 10000)) return true;
+  }
+  return false;
+}
+
+async function valueOf(page, selector) {
+  const field = await waitFor(page, selector);
+  return field.evaluate((el) => el.value);
+}
+
+async function textOf(page, selector) {
+  const element = await page.$(selector);
+  return element ? element.evaluate((el) => el.textContent.trim()).catch(() => null) : null;
+}
+
 /**
  * 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
@@ -424,4 +792,17 @@ async function dismissModal(page) {
   await dispatchClick(page, selectors.modal.lastButton);
 }
 
-module.exports = { decisions, walletState, onboard, unlock, addAccount, switchAccount, importAccount, decide, approveNetworkChange };
+module.exports = {
+  decisions,
+  walletState,
+  onboard,
+  unlock,
+  leaveUnlockForm,
+  lock,
+  addAccount,
+  switchAccount,
+  importAccount,
+  disconnectSite,
+  decide,
+  approveNetworkChange,
+};

package/src/support.js

@@ -25,7 +25,8 @@ Cypress.Commands.add('approveSwitchNetwork', () => metamask('approveSwitchNetwor
 Cypress.Commands.add('rejectSwitchNetwork', () => metamask('rejectSwitchNetwork'));
 Cypress.Commands.add('confirmSignature', () => metamask('confirmSignature'));
 Cypress.Commands.add('rejectSignature', () => metamask('rejectSignature'));
-Cypress.Commands.add('confirmTransaction', () => metamask('confirmTransaction'));
+// 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'));
@@ -37,9 +38,20 @@ Cypress.Commands.add('switchAccount', (name) => metamask('switchAccount', name,
 // The private key is kept out of the command log
 Cypress.Commands.add('importAccount', (privateKey) => metamask('importAccount', privateKey));
 
-// Connect, then move the dapp onto the network from the wallet setup, if there is one
-Cypress.Commands.add('connectToDapp', () => {
-  metamask('connectToDapp');
+// 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);
 });
 

package/types/support.d.ts

@@ -4,19 +4,31 @@ import type { Network } from './index';
 
 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[];
+};
+
 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>;
+      /** 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. */
-      confirmTransaction(): 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>;
@@ -33,6 +45,10 @@ declare global {
       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. */
@@ -40,3 +56,33 @@ declare global {
     }
   }
 }
+
+/** 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;
+}