dappress 0.2.0 → 0.3.1

package/README.md

@@ -66,7 +66,7 @@ const wallet: WalletSetup = {
 export default wallet;
 ```
 
-Keep the seed phrase out of the repository, in `cypress.env.json` (git-ignored):
+Without a seed phrase, Dappress makes a new wallet for each run: enough to connect and sign. To test with a wallet of yours, one that holds test funds for instance, give its seed phrase and keep it out of the repository, in `cypress.env.json` (git-ignored):
 
 ```json
 {
@@ -82,7 +82,6 @@ env:
   DAPPRESS_SEED_PHRASE: ${{ secrets.DAPPRESS_SEED_PHRASE }}
 ```
 
-When neither is provided, Dappress uses the public Hardhat / Anvil development wallet. Give your test suite a seed phrase of its own: that one is shared with everybody.
 
 Add the command types to `tsconfig.json`:
 
@@ -96,12 +95,14 @@ Add the command types to `tsconfig.json`:
 
 JavaScript projects use the same files with a `.js` extension and `module.exports`.
 
-Run the tests in a headed browser that supports extensions:
+Run the tests in a browser that supports extensions:
 
 ```bash
 npx cypress run --browser chrome-for-testing --headed
 ```
 
+Without `--headed`, the run is headless and works the same, except for the wallet cache, which needs a headed browser.
+
 ## Usage
 
 ```ts
@@ -109,7 +110,7 @@ it('connects the wallet and signs in', () => {
   cy.visit('/');
   cy.contains('button', 'Connect wallet').click();
   cy.connectToDapp();
-  cy.getAccountAddress().should('eq', '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266');
+  cy.getAccountAddress().should('match', /^0x[0-9a-f]{40}$/);
 
   cy.contains('button', 'Sign in').click();
   cy.confirmSignature();
@@ -153,17 +154,17 @@ Settings normally live in `cypress/wallet.setup.ts`. Secrets go in `cypress.env.
 | Option | Environment variable | Default |
 |---|---|---|
 | `metamaskVersion` | `DAPPRESS_METAMASK_VERSION` | `13.50.0`. The build is downloaded from MetaMask's GitHub releases on first run and cached in `~/.cache/dappress`. |
-| `seedPhrase` | `DAPPRESS_SEED_PHRASE` | `test test test test test test test test test test test junk`, the Hardhat / Anvil development wallet. Its first account is `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`. |
+| `seedPhrase` | `DAPPRESS_SEED_PHRASE` | None. Dappress makes a new wallet for each run, which nobody else knows and which is never written anywhere. |
 | `password` | `DAPPRESS_PASSWORD` | `Tester@1234`. It only protects the throwaway browser profile Cypress creates for each run. |
 | `network` | | None. The dapp stays on the network MetaMask starts on, Ethereum mainnet. |
 | `backupAndSync` | | `false`. Dappress turns off MetaMask's backup and sync while importing the wallet, so that an account a test adds is not restored by the next import of the same seed phrase. With `true`, MetaMask keeps saving and restoring the accounts and contacts of that phrase. |
 | `autoSetup` | | `true`. Dappress imports or unlocks the wallet before the first test of each spec. Set to `false` to call `cy.setupMetaMask()` yourself. |
-| `cache` | | `false`. The wallet is imported in every run, about fifteen seconds. With `true`, it is imported once, in a browser Dappress opens before the run, and the resulting profile is reused by later runs, which then start by unlocking the wallet. |
+| `cache` | | `false`. The wallet is imported in every run, about fifteen seconds. With `true`, and a seed phrase of your own, it is imported once, in a browser Dappress opens before the run, and the resulting profile is reused by later runs, which then start by unlocking the wallet. Headed runs only: a headless run imports the wallet as usual. |
 | `timeout` | | `20000` ms. The time allowed for MetaMask to display a request before a command fails. |
 
 ### Security
 
-Use a wallet dedicated to testing, funded on test networks only. The default seed phrase is public: anyone can spend from it, and its accounts can carry activity nobody controls. It is fine for a first run, not for a test suite you rely on. The seed phrase and password remain on the Node.js side: they are never exposed to the browser nor written to the Cypress command log. The wallet setup file contains no secret and can be committed.
+When you give a seed phrase, make it one dedicated to testing, funded on test networks only. Avoid a phrase other people know, such as the Hardhat or Anvil development mnemonic: MetaMask restores the accounts others saved for it, so the wallet is not the one you expect. The seed phrase and password remain on the Node.js side: they are never exposed to the browser nor written to the Cypress command log. The wallet setup file contains no secret and can be committed.
 
 With `cache: true`, the profile under `~/.cache/dappress/profiles` holds the wallet's vault, encrypted by MetaMask with the password. Treat that directory like the seed phrase: keep it on the machine, and do not store it in a CI cache that other people or workflows can restore.
 
@@ -172,8 +173,9 @@ With `cache: true`, the profile under `~/.cache/dappress/profiles` holds the wal
 The suite runs one test per command against [MetaMask's test dapp](https://metamask.github.io/test-dapp/). Each run makes a wallet nobody has used, with Foundry's `cast`, and starts a local [Anvil](https://getfoundry.sh) node that funds it. It requires Chrome for Testing and Foundry.
 
 ```bash
-npm run conformance               # default MetaMask version
-npm run conformance -- 13.51.0    # a specific release
+npm run conformance                        # default MetaMask version
+npm run conformance -- 13.51.0             # a specific release
+DAPPRESS_HEADLESS=1 npm run conformance    # without a browser window
 ```
 
 Each run writes `reports/metamask-<version>.json`. The GitHub workflow runs the suite daily against the latest MetaMask release that has no report yet.
@@ -190,6 +192,8 @@ Cypress executes tests inside the dapp's tab and has no access to the extension.
 
 MetaMask displays requests in its side panel when the panel is open, and in its popup window otherwise. Without the cache, the import of the wallet ends by opening the side panel, so requests appear there. With the cache, the wallet was imported in another browser, the panel is closed, and requests appear in the popup. Dappress handles both, and the conformance suite covers both.
 
+Cypress leaves extensions out of a headless launch, so Dappress passes MetaMask to Chrome itself. Headless Chrome displays the side panel but does not open the popup window, which is why the cache, whose requests appear in the popup, is limited to headed runs.
+
 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.
 
 ```
@@ -214,11 +218,11 @@ Selectors are MetaMask's `data-testid` attributes, each with the button's Englis
 - **Cypress exits immediately with `MODULE_NOT_FOUND`.** The terminal sets `ELECTRON_RUN_AS_NODE=1`, as some IDEs do. Run `env -u ELECTRON_RUN_AS_NODE npx cypress run …`.
 - **"MetaMask showed no confirmation".** The dapp sent no request, or sent it on a network whose RPC endpoint is unreachable.
 - **Adding or importing an account never finishes.** `chromeWebSecurity: false` is set in the Cypress config. MetaMask then cannot start its snaps, which its account screens wait for. Leave Chrome's web security on, the Cypress default.
-- **The wallet shows accounts you did not create.** The seed phrase is used elsewhere, and MetaMask restored what its cloud holds for it. This happens with the public default phrase. Use a phrase made for your tests.
+- **The wallet shows accounts you did not create.** The seed phrase is used elsewhere, and MetaMask restored what its cloud holds for it. This happens with well-known development mnemonics. Use a phrase made for your tests, or none.
 
 ## Status
 
-Verified with MetaMask 13.49.0 and 13.50.0, Cypress 16 and Chrome for Testing 154, in headed mode, on macOS and on GitHub's Linux runners. Headless execution is not validated yet.
+Verified with MetaMask 13.49.0 and 13.50.0, Cypress 16 and Chrome for Testing 154: in headed mode on macOS and on GitHub's Linux runners, and in headless mode on macOS.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dappress",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",
@@ -57,6 +57,7 @@
     "cypress": ">=13.6.0"
   },
   "dependencies": {
+    "@scure/bip39": "^1.6.0",
     "extract-zip": "^2.0.1",
     "puppeteer-core": "^24.43.1"
   },

package/src/config.js

@@ -1,11 +1,14 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { generateMnemonic } = require('@scure/bip39');
+const { wordlist } = require('@scure/bip39/wordlists/english');
 
 const DEFAULTS = {
   metamaskVersion: '13.50.0',
-  // The Hardhat / Anvil development mnemonic. Account 0 is 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266.
-  seedPhrase: 'test test test test test test test test test test test junk',
+  // 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,
@@ -42,9 +45,20 @@ function resolveOptions(userOptions = {}, cypressConfig = {}) {
   for (const [key, value] of Object.entries(fromEnv)) {
     if (value) options[key] = value;
   }
+  if (!options.seedPhrase) useNewWallet(options);
   return options;
 }
 
+/** No seed phrase was given: make one for this run. It is never written anywhere. */
+function useNewWallet(options) {
+  options.seedPhrase = generateMnemonic(wordlist);
+  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;
+  }
+}
+
 /** The project's wallet setup file: { seedPhrase?, network? }. */
 function loadWalletSetup(projectRoot = process.cwd()) {
   const file = WALLET_SETUP_FILES.map((name) => path.join(projectRoot, name)).find((candidate) => fs.existsSync(candidate));

package/src/index.js

@@ -20,9 +20,12 @@ function configureDappress(on, config, userOptions = {}) {
     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 (options.cache && browser) await prepareProfile({ browserPath: browser.path, extensionDir: await prepareExtension(options), options });
+    if (browser && usesCache(browser)) await prepareProfile({ browserPath: browser.path, extensionDir: await prepareExtension(options), options });
   });
 
   on('before:browser:launch', async (browser, launchOptions) => {
@@ -31,7 +34,12 @@ function configureDappress(on, config, userOptions = {}) {
     }
     const extensionDir = await prepareExtension(options);
     launchOptions.extensions.push(extensionDir);
-    if (options.cache) {
+    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 prepareProfile({ browserPath: browser.path, extensionDir, options });
       await installProfile(profileDir, browser, config.isTextTerminal);
     }

package/src/metamask.js

@@ -214,23 +214,40 @@ async function reloadHome(page) {
   await page.goto(homeUrl);
 }
 
-/** Add an account to the wallet and select it. Yields its name, "Account N". */
+/**
+ * Add an account to the wallet and select it. Yields its name, "Account N".
+ * A click that lands while the list is still settling is lost, so the button
+ * is pressed again when no account shows up.
+ */
 async function addAccount(page) {
   await click(page, selectors.home.accountMenu);
   const before = await accountNames(page);
-  await clickWhenEnabled(page, selectors.accounts.add, { timeout: 30000 });
-  const deadline = Date.now() + 30000;
-  while (Date.now() < deadline) {
-    const [added] = (await accountNames(page)).filter((name) => !before.includes(name));
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const added = (await newAccount(page, before, 0)) || (await pressAddAccount(page, before));
     if (added) {
       await selectAccount(page, added);
       return added;
     }
-    await sleep(250);
   }
   throw await failure(page, 'MetaMask added no account');
 }
 
+async function pressAddAccount(page, before) {
+  await clickWhenEnabled(page, selectors.accounts.add, { timeout: 30000 });
+  return newAccount(page, before, 15000);
+}
+
+/** The name of an account that wasn't in `before`, within `timeout` ms. */
+async function newAccount(page, before, timeout) {
+  const deadline = Date.now() + timeout;
+  do {
+    const [added] = (await accountNames(page)).filter((name) => !before.includes(name));
+    if (added) return added;
+    await sleep(250);
+  } while (Date.now() < deadline);
+  return null;
+}
+
 async function accountNames(page) {
   await waitFor(page, selectors.accounts.name);
   return page.$$eval(selectors.accounts.name, (cells) => cells.map((cell) => cell.textContent.trim()));
@@ -242,15 +259,23 @@ async function switchAccount(page, name) {
   await selectAccount(page, name);
 }
 
-// Picking an account closes the list and shows it in the home header
+// Picking an account closes the list and shows it in the home header. As with
+// adding one, a lost click leaves the list open, so the account is pressed again.
 async function selectAccount(page, name) {
-  await click(page, selectors.accounts.cell(name));
-  const deadline = Date.now() + 15000;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    await click(page, selectors.accounts.cell(name));
+    if (await isSelected(page, name, 5000)) return;
+  }
+  throw await failure(page, `MetaMask did not select "${name}"`);
+}
+
+async function isSelected(page, name, timeout) {
+  const deadline = Date.now() + timeout;
   while (Date.now() < deadline) {
-    if ((await selectedAccount(page)) === name) return;
+    if ((await selectedAccount(page)) === name) return true;
     await sleep(250);
   }
-  throw await failure(page, `MetaMask did not select "${name}"`);
+  return false;
 }
 
 async function selectedAccount(page) {

package/types/index.d.ts

@@ -12,7 +12,10 @@ export interface Network {
 
 /** What cypress/wallet.setup.ts exports. */
 export interface WalletSetup {
-  /** Prefer DAPPRESS_SEED_PHRASE in cypress.env.json or the environment: this file is usually committed. */
+  /**
+   * 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;
@@ -30,7 +33,7 @@ export interface DappressOptions extends WalletSetup {
   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. Default: false. */
+  /** 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;