dappress 0.1.1 → 0.3.0

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.
 
 Add the command types to `tsconfig.json`:
 
@@ -109,7 +108,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();
@@ -134,6 +133,9 @@ The wallet is imported once, before the first test of each spec. Each command wa
 | `cy.rejectSwitchNetwork()` | Denies that permission |
 | `cy.approveAddToken()` | Adds the token requested by `wallet_watchAsset` |
 | `cy.rejectAddToken()` | Rejects the token |
+| `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.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. |
@@ -150,22 +152,23 @@ 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. |
 | `timeout` | | `20000` ms. The time allowed for MetaMask to display a request before a command fails. |
 
 ### Security
 
-Use a wallet dedicated to testing, funded on test networks only. The default seed phrase is public. The seed phrase and password remain on the Node.js side: they are never exposed to the browser nor written to the Cypress command log. The wallet setup file contains no secret and can be committed.
+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.
 
 ## Conformance suite
 
-The suite runs one test per command against [MetaMask's test dapp](https://metamask.github.io/test-dapp/), with a local [Anvil](https://getfoundry.sh) node for the funded transaction. It requires Chrome for Testing and Foundry.
+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
@@ -209,10 +212,12 @@ 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 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 on macOS, in headed mode. Headless execution and continuous integration are 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. Headless execution is not validated yet.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dappress",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -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/actions.js

@@ -27,6 +27,17 @@ function createTasks(options) {
     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 getHomePage(browser, await metamaskId(browser));
+    try {
+      await home.bringToFront();
+      return await flow(home, argument);
+    } finally {
+      await home.close();
+    }
+  };
+
   /** 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);
@@ -39,7 +50,13 @@ function createTasks(options) {
     await metamask.decide(decision, page, options.timeout);
   };
 
-  const actions = { setupWallet, approveNetworkChange };
+  const actions = {
+    setupWallet,
+    approveNetworkChange,
+    addAccount: onHomePage(metamask.addAccount),
+    switchAccount: onHomePage(metamask.switchAccount),
+    importAccount: onHomePage(metamask.importAccount),
+  };
   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

package/src/config.js

@@ -1,14 +1,20 @@
 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,
+  // 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)
@@ -39,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

@@ -16,6 +16,9 @@ const { createTasks } = require('./actions');
  */
 function configureDappress(on, config, userOptions = {}) {
   const options = 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');
+  }
 
   // Build the wallet profile before the run, out of the time Cypress allows a browser to come up
   on('before:run', async ({ browser }) => {

package/src/metamask.js

@@ -30,6 +30,13 @@ const selectors = {
     metricsContinue: [testId('metametrics-i-agree'), buttonText('Continue')],
     downloadAppContinue: testId('download-app-continue'),
     done: [testId('onboarding-complete-done'), buttonText('Done')],
+    // "Manage default settings", offered next to "Done"
+    manageDefaultSettings: testId('manage-default-settings'),
+    // The first category, "General": its testid carries the translated label
+    generalSettings: 'xpath/(.//*[starts-with(@data-testid, "category-item-")])[1]',
+    backupAndSyncToggle: testId('backup-and-sync-toggle-button'),
+    categoryBack: testId('category-back-button'),
+    settingsBack: testId('privacy-settings-back-button'),
   },
   unlock: {
     password: [testId('unlock-password'), passwordInput(1)],
@@ -37,6 +44,18 @@ const selectors = {
   },
   home: {
     header: testId('parent-selector-header-navbar'),
+    accountMenu: testId('account-menu-icon'),
+  },
+  // The account list, opened from the home header
+  accounts: {
+    name: '[data-testid^="multichain-account-cell-name-"]',
+    cell: (name) => `xpath/.//*[contains(@class, "multichain-account-cell")][.//*[@data-testid="multichain-account-cell-name-${name}"]]`,
+    add: 'xpath/(.//*[@data-testid="add-multichain-account-button"])[1]',
+    addWallet: testId('account-list-add-wallet-button'),
+    importAccount: testId('choose-wallet-type-import-account'),
+    privateKey: '#private-key-box',
+    importConfirm: [testId('import-account-confirm-button'), buttonText('Import')],
+    back: testId('account-list-page-back-button'),
   },
   // "Connect this website with MetaMask"
   connect: {
@@ -98,7 +117,7 @@ async function walletState(page) {
 }
 
 /** Import a wallet from its seed phrase on a fresh MetaMask install. */
-async function onboard(page, { seedPhrase, password }) {
+async function onboard(page, { seedPhrase, password, backupAndSync }) {
   const s = selectors.onboarding;
   await click(page, s.importWallet, { timeout: 30000 });
   await click(page, s.importWithSrp);
@@ -111,7 +130,7 @@ async function onboard(page, { seedPhrase, password }) {
   await click(page, s.passwordTerms);
   await clickWhenEnabled(page, s.passwordSubmit);
 
-  await reachHome(page, { password });
+  await reachHome(page, { password, backupAndSync });
 }
 
 // MetaMask's sandbox (LavaMoat) blocks a scripted paste, so the phrase is
@@ -139,9 +158,10 @@ async function unlock(page, { password }) {
  * "Done", MetaMask takes a moment to record the onboarding as complete and
  * redirects to it until then, so the home page is reloaded.
  */
-async function reachHome(page, { password }) {
+async function reachHome(page, { password, backupAndSync }) {
   const s = selectors.onboarding;
   const deadline = Date.now() + 90000;
+  let syncTurnedOff = false;
   while (Date.now() < deadline) {
     if (await isVisible(page, selectors.home.header, 500)) return;
     if (await isVisible(page, s.passkeyMaybeLater, 500)) await click(page, s.passkeyMaybeLater);
@@ -150,6 +170,10 @@ async function reachHome(page, { password }) {
       await click(page, s.metricsContinue);
     }
     if (await isVisible(page, s.downloadAppContinue, 500)) await click(page, s.downloadAppContinue);
+    if (backupAndSync === false && !syncTurnedOff && (await isVisible(page, s.manageDefaultSettings, 500))) {
+      await turnOffBackupAndSync(page);
+      syncTurnedOff = true;
+    }
     if (await isVisible(page, s.done, 500)) {
       await click(page, s.done);
       await sleep(1000);
@@ -163,6 +187,19 @@ async function reachHome(page, { password }) {
   throw await failure(page, 'MetaMask did not show the wallet');
 }
 
+// Backup and sync restores, for a seed phrase, the accounts and contacts saved
+// from other installs. Off, every import starts from the same state.
+async function turnOffBackupAndSync(page) {
+  const s = selectors.onboarding;
+  await click(page, s.manageDefaultSettings);
+  await click(page, s.generalSettings);
+  const toggle = await waitFor(page, s.backupAndSyncToggle);
+  const on = await toggle.evaluate((el) => el.closest('.toggle-button')?.classList.contains('toggle-button--on') ?? el.className.includes('--on'));
+  if (on) await toggle.click();
+  await click(page, s.categoryBack);
+  await click(page, s.settingsBack);
+}
+
 async function optOutOfMetrics(page) {
   const checkbox = await waitFor(page, selectors.onboarding.metricsCheckbox);
   const checked = await checkbox.evaluate((el) => el.getAttribute('data-checked') === 'true');
@@ -177,6 +214,86 @@ async function reloadHome(page) {
   await page.goto(homeUrl);
 }
 
+/**
+ * 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);
+  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;
+    }
+  }
+  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()));
+}
+
+/** Make `name` the selected account of the wallet. */
+async function switchAccount(page, name) {
+  await click(page, selectors.home.accountMenu);
+  await selectAccount(page, name);
+}
+
+// Picking an account closes the list and shows it in the home header
+async function selectAccount(page, name) {
+  await click(page, selectors.accounts.cell(name));
+  const deadline = Date.now() + 15000;
+  while (Date.now() < deadline) {
+    if ((await selectedAccount(page)) === name) return;
+    await sleep(250);
+  }
+  throw await failure(page, `MetaMask did not select "${name}"`);
+}
+
+async function selectedAccount(page) {
+  const menu = await page.$(selectors.home.accountMenu);
+  return menu ? menu.evaluate((el) => el.textContent.trim()) : null;
+}
+
+/** Import an account from its private key and select it. Yields its name. */
+async function importAccount(page, privateKey) {
+  await waitFor(page, selectors.home.accountMenu);
+  const before = await selectedAccount(page);
+  // Straight to the form the account list's "Add wallet" menu leads to
+  const homeUrl = page.url().split('#')[0];
+  await page.goto('about:blank');
+  await page.goto(`${homeUrl}#/add-wallet-page`);
+  await fill(page, selectors.accounts.privateKey, privateKey, { timeout: 30000 });
+  await clickWhenEnabled(page, selectors.accounts.importConfirm);
+  const deadline = Date.now() + 30000;
+  while (Date.now() < deadline) {
+    const selected = await selectedAccount(page);
+    if (selected && selected !== before) return selected;
+    await sleep(250);
+  }
+  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) {
   return pressAndWaitForDismissal(page, decisions[decision], timeout);
@@ -246,4 +363,4 @@ async function dismissModal(page) {
   await dispatchClick(page, selectors.modal.lastButton);
 }
 
-module.exports = { decisions, walletState, onboard, unlock, decide, approveNetworkChange };
+module.exports = { decisions, walletState, onboard, unlock, addAccount, switchAccount, importAccount, decide, approveNetworkChange };

package/src/profile.js

@@ -16,7 +16,7 @@ const builds = new Map();
 
 /** The cached profile for these options, built on first use. */
 function prepareProfile({ browserPath, extensionDir, options }) {
-  const key = crypto.createHash('sha256').update([options.metamaskVersion, options.seedPhrase, options.password].join('|')).digest('hex').slice(0, 16);
+  const key = crypto.createHash('sha256').update([options.metamaskVersion, options.seedPhrase, options.password, options.backupAndSync].join('|')).digest('hex').slice(0, 16);
   if (!builds.has(key)) builds.set(key, buildProfile(path.join(options.cacheDir, 'profiles', key), { browserPath, extensionDir, options }));
   return builds.get(key);
 }

package/src/support.js

@@ -7,8 +7,9 @@
 
 const options = Cypress.expose('dappress') || {};
 
-function metamask(action, argument = null) {
-  Cypress.log({ name: 'metamask', message: argument ? `${action} ${argument}` : action });
+// `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 });
 }
 
@@ -29,6 +30,12 @@ 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));
 
 // Connect, then move the dapp onto the network from the wallet setup, if there is one
 Cypress.Commands.add('connectToDapp', () => {

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;
@@ -23,6 +26,11 @@ export interface DappressOptions extends WalletSetup {
   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. Default: false. */

package/types/support.d.ts

@@ -27,6 +27,12 @@ declare global {
       /** 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>;
       /** 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. */