dappress 0.1.0 → 0.2.0

package/README.md

@@ -82,7 +82,7 @@ env:
   DAPPRESS_SEED_PHRASE: ${{ secrets.DAPPRESS_SEED_PHRASE }}
 ```
 
-When neither is provided, Dappress uses the public Hardhat / Anvil development wallet.
+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`:
 
@@ -134,6 +134,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. |
@@ -153,19 +156,20 @@ Settings normally live in `cypress/wallet.setup.ts`. Secrets go in `cypress.env.
 | `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`. |
 | `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. |
 | `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.
+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.
 
 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 +213,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 the public default phrase. Use a phrase made for your tests.
 
 ## 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.0",
+  "version": "0.2.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

@@ -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

@@ -9,6 +9,9 @@ const DEFAULTS = {
   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)

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,69 @@ async function reloadHome(page) {
   await page.goto(homeUrl);
 }
 
+/** Add an account to the wallet and select it. Yields its name, "Account N". */
+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));
+    if (added) {
+      await selectAccount(page, added);
+      return added;
+    }
+    await sleep(250);
+  }
+  throw await failure(page, 'MetaMask added no account');
+}
+
+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);
@@ -191,7 +291,9 @@ function approveNetworkChange(page, timeout) {
  * 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
  * lands while the confirmation is still settling is lost, so the click is
- * repeated while the button stays.
+ * repeated while the button stays. If it stays anyway, the error says
+ * whether it is the same request or a new one the dapp sent meanwhile, and
+ * what MetaMask logged.
  */
 async function pressAndWaitForDismissal(page, button, timeout) {
   await waitFor(page, button, { timeout });
@@ -199,14 +301,41 @@ async function pressAndWaitForDismissal(page, button, timeout) {
   if (await isVisible(page, selectors.confirmation.scrollToBottom, 500)) {
     await click(page, selectors.confirmation.scrollToBottom);
   }
-  await clickWhenEnabled(page, button);
-  for (let attempt = 0; attempt < 3; attempt++) {
-    if (await isVisible(page, selectors.alert.acknowledge, 500)) await click(page, selectors.alert.acknowledge);
-    if (await isGone(page, button, 3000)) return;
-    await dismissModal(page);
-    await dispatchClick(page, button, { timeout: 3000 }).catch(() => {});
+  const logged = recordErrors(page);
+  const request = page.url();
+  try {
+    await clickWhenEnabled(page, button);
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (await isVisible(page, selectors.alert.acknowledge, 500)) await click(page, selectors.alert.acknowledge);
+      if (await isGone(page, button, 3000)) return;
+      await dismissModal(page);
+      await dispatchClick(page, button, { timeout: 3000 }).catch(() => {});
+    }
+    const what = page.url() === request ? 'MetaMask kept the same request open' : 'MetaMask shows a new request: the dapp asked again';
+    const distinct = [...new Set(logged.errors)].slice(-3);
+    const errors = distinct.length ? `MetaMask logged: ${distinct.join(' | ')}` : 'MetaMask logged no error';
+    throw await failure(page, `"${describe(button)}" is still showing after being clicked. ${what}. ${errors}`);
+  } finally {
+    logged.stop();
   }
-  throw await failure(page, `"${describe(button)}" is still showing after being clicked`);
+}
+
+/** Collect the errors MetaMask's page logs to its console, until stop(). */
+function recordErrors(page) {
+  const errors = [];
+  const onConsole = (message) => {
+    if (message.type() === 'error') errors.push(message.text().slice(0, 300));
+  };
+  const onPageError = (error) => errors.push(String(error.message || error).slice(0, 300));
+  page.on('console', onConsole);
+  page.on('pageerror', onPageError);
+  return {
+    errors,
+    stop() {
+      page.off('console', onConsole);
+      page.off('pageerror', onPageError);
+    },
+  };
 }
 
 /** Close a modal shown over the confirmation (Escape, or its last button: "Cancel"). */
@@ -217,4 +346,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

@@ -23,6 +23,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. */