dappress 0.3.3 → 0.5.0

package/dist/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// The types of the public API, shared by the plugin (index.ts) and the
+// commands (support.ts), and the options as the plugin resolves them.
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dappress",
-  "version": "0.3.3",
+  "version": "0.5.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",
@@ -21,28 +21,28 @@
     "wallet",
     "dapp"
   ],
-  "main": "src/index.js",
-  "types": "types/index.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./types/index.d.ts",
-      "default": "./src/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./support": {
-      "types": "./types/support.d.ts",
-      "default": "./src/support.js"
+      "types": "./dist/support.d.ts",
+      "default": "./dist/support.js"
     }
   },
   "typesVersions": {
     "*": {
       "support": [
-        "types/support.d.ts"
+        "dist/support.d.ts"
       ]
     }
   },
   "files": [
-    "src",
-    "types",
+    "dist",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -50,10 +50,15 @@
     "node": ">=20"
   },
   "scripts": {
-    "conformance": "node scripts/conformance.js",
-    "matrix": "node scripts/matrix.js",
-    "test": "node --test scripts/*.test.js",
-    "check-types": "tsc -p tsconfig.json"
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "conformance": "tsx scripts/conformance.ts",
+    "matrix": "tsx scripts/matrix.ts",
+    "test": "tsx --test scripts/*.test.ts src/*.test.ts",
+    "check-types": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "peerDependencies": {
     "cypress": ">=13.6.0"
@@ -64,8 +69,15 @@
     "puppeteer-core": "^24.43.1"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^20.19.43",
     "cypress": "^16.1.1",
-    "typescript": "^5.6.0"
+    "eslint": "^10.12.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.9",
+    "tsx": "^4.23.15",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.71.0"
   }
 }

package/src/actions.js

@@ -1,67 +0,0 @@
-// The Node side of every cy.* command, registered as Cypress tasks. Each
-// action gets a Puppeteer browser connected to the Cypress browser, finds the
-// MetaMask page it needs and drives it through src/metamask.js.
-
-const { withBrowser } = require('./browser');
-const metamask = require('./metamask');
-const { findExtensionId, getHomePage, getConfirmationPage } = require('./metamask-pages');
-
-function createTasks(options) {
-  // Found once: the browser is the same for the whole run
-  let extensionId;
-
-  async function metamaskId(browser) {
-    extensionId = extensionId || (await findExtensionId(browser));
-    return extensionId;
-  }
-
-  /** Onboard the wallet or unlock it, so the dapp can talk to it. Safe to call repeatedly. */
-  async function setupWallet(browser) {
-    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 === 'locked') await metamask.unlock(home, options);
-    if (state === 'unknown') throw new Error(`[dappress] Unexpected MetaMask screen at ${home.url()}`);
-    await home.close();
-    return state;
-  }
-
-  /** A task that drives the wallet's own screens, from its full-screen page. */
-  const onHomePage = (flow) => async (browser, argument) => {
-    const home = await 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);
-    await metamask.approveNetworkChange(page, options.timeout);
-  }
-
-  /** The task for a decision: find the confirmation, press its button. */
-  const decide = (decision) => async (browser) => {
-    const page = await getConfirmationPage(browser, await metamaskId(browser), options.timeout);
-    await metamask.decide(decision, page, options.timeout);
-  };
-
-  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
-  const asTask = (action) => async (argument) => (await withBrowser((browser) => action(browser, argument))) ?? null;
-  return Object.fromEntries(Object.entries(actions).map(([name, action]) => [`dappress:${name}`, asTask(action)]));
-}
-
-module.exports = { createTasks };

package/src/browser.js

@@ -1,42 +0,0 @@
-// Connects Puppeteer to the browser Cypress launched, through the debugging
-// URL Cypress hands out in after:browser:launch (Cypress 13.6+).
-
-const puppeteer = require('puppeteer-core');
-
-let debuggerUrl;
-
-function captureDebuggerUrl(on) {
-  on('after:browser:launch', (browser, options) => {
-    debuggerUrl = options.webSocketDebuggerUrl;
-  });
-}
-
-/**
- * Run `action` with a Puppeteer browser connected to Cypress's browser, then
- * give the focus back to the Cypress tab and disconnect. The browser stays open.
- */
-async function withBrowser(action) {
-  if (!debuggerUrl) {
-    throw new Error('[dappress] No browser to connect to. Is configureDappress() called in setupNodeEvents, with Cypress 13.6 or later?');
-  }
-  const browser = await puppeteer.connect({ browserWSEndpoint: debuggerUrl, defaultViewport: null });
-  try {
-    return await action(browser);
-  } catch (error) {
-    // The browser side only gets the message, so keep the full stack in the terminal
-    console.error(error.stack || error);
-    throw error;
-  } finally {
-    await focusCypressTab(browser).catch(() => {});
-    await browser.disconnect();
-  }
-}
-
-// MetaMask opens its own tabs and popups; Chrome throttles the Cypress tab
-// while it is in the background. The Cypress runner lives under /__/.
-async function focusCypressTab(browser) {
-  const target = browser.targets().find((candidate) => candidate.type() === 'page' && candidate.url().includes('/__/'));
-  if (target) await (await target.page()).bringToFront();
-}
-
-module.exports = { captureDebuggerUrl, withBrowser };

package/src/config.js

@@ -1,78 +0,0 @@
-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',
-  // None: a new wallet is made for each run. A phrase known to others is not
-  // blank, since MetaMask restores the accounts saved for it elsewhere.
-  seedPhrase: null,
-  password: 'Tester@1234',
-  // The network cy.connectToDapp() moves the dapp onto, as a wallet_addEthereumChain parameter; none by default
-  network: null,
-  // MetaMask's backup and sync saves the accounts and contacts of a seed phrase
-  // and restores them on other installs. Off, a test's accounts don't come back.
-  backupAndSync: false,
-  // Run cy.setupMetaMask() automatically before the first test of each spec
-  autoSetup: true,
-  // Import the wallet once and reuse the profile across runs (keeps the vault under cacheDir)
-  cache: false,
-  // How long to wait for MetaMask to show a confirmation after a dapp request (ms)
-  timeout: 20000,
-  cacheDir: path.join(os.homedir(), '.cache', 'dappress'),
-};
-
-// A .ts file loads when the Cypress config is itself in TypeScript
-const WALLET_SETUP_FILES = ['cypress/wallet.setup.ts', 'cypress/wallet.setup.js'];
-
-/**
- * The plugin options, in order of precedence: environment variables, the
- * Cypress `env` block (cypress.env.json), the wallet setup file
- * (cypress/wallet.setup.ts or .js), the options given to configureDappress(),
- * then the defaults above.
- */
-function resolveOptions(userOptions = {}, cypressConfig = {}) {
-  const env = cypressConfig.env || {};
-  const fromEnv = {
-    metamaskVersion: process.env.DAPPRESS_METAMASK_VERSION || env.DAPPRESS_METAMASK_VERSION,
-    seedPhrase: process.env.DAPPRESS_SEED_PHRASE || env.DAPPRESS_SEED_PHRASE,
-    password: process.env.DAPPRESS_PASSWORD || env.DAPPRESS_PASSWORD,
-  };
-
-  const options = { ...DEFAULTS, ...userOptions, ...loadWalletSetup(cypressConfig.projectRoot) };
-  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));
-  if (!file) return {};
-  const loaded = require(file);
-  const setup = loaded.default || loaded; // `export default` or `module.exports`
-  const unknown = Object.keys(setup).filter((key) => !['seedPhrase', 'network'].includes(key));
-  if (unknown.length) throw new Error(`[dappress] Unknown keys in ${path.basename(file)}: ${unknown.join(', ')}`);
-  return setup;
-}
-
-/** The subset of options that is safe to expose to the browser side (no secrets). */
-function publicOptions(options) {
-  return { metamaskVersion: options.metamaskVersion, autoSetup: options.autoSetup, network: options.network };
-}
-
-module.exports = { DEFAULTS, resolveOptions, publicOptions };

package/src/download.js

@@ -1,50 +0,0 @@
-const fs = require('node:fs');
-const path = require('node:path');
-const { pipeline } = require('node:stream/promises');
-const { Readable } = require('node:stream');
-const extractZip = require('extract-zip');
-
-function releaseUrl(version) {
-  return `https://github.com/MetaMask/metamask-extension/releases/download/v${version}/metamask-chrome-${version}.zip`;
-}
-
-function extensionDir(cacheDir, version) {
-  return path.join(cacheDir, 'metamask', version);
-}
-
-async function download(url, destination) {
-  const response = await fetch(url, { redirect: 'follow' });
-  if (!response.ok || !response.body) {
-    throw new Error(`[dappress] Could not download ${url}: HTTP ${response.status}`);
-  }
-  await fs.promises.mkdir(path.dirname(destination), { recursive: true });
-  await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(destination));
-}
-
-/**
- * Download and unzip the MetaMask Chrome build for `version` into the cache.
- * Returns the path of the unpacked extension (the folder holding manifest.json).
- * Already cached versions are reused.
- */
-async function prepareExtension({ metamaskVersion, cacheDir }) {
-  const dir = extensionDir(cacheDir, metamaskVersion);
-  const manifest = path.join(dir, 'manifest.json');
-  if (fs.existsSync(manifest)) return dir;
-
-  const zipPath = path.join(cacheDir, 'metamask', `metamask-chrome-${metamaskVersion}.zip`);
-  if (!fs.existsSync(zipPath)) {
-    console.log(`[dappress] Downloading MetaMask ${metamaskVersion}…`);
-    await download(releaseUrl(metamaskVersion), zipPath);
-  }
-
-  console.log(`[dappress] Unpacking MetaMask ${metamaskVersion}…`);
-  await fs.promises.rm(dir, { recursive: true, force: true });
-  await extractZip(zipPath, { dir });
-
-  if (!fs.existsSync(manifest)) {
-    throw new Error(`[dappress] ${zipPath} does not look like a MetaMask build: no manifest.json after extraction`);
-  }
-  return dir;
-}
-
-module.exports = { prepareExtension };

package/src/index.js

@@ -1,56 +0,0 @@
-const { resolveOptions, publicOptions } = require('./config');
-const { captureDebuggerUrl } = require('./browser');
-const { prepareExtension } = require('./download');
-const { prepareProfile, installProfile } = require('./profile');
-const { createTasks } = require('./actions');
-
-/**
- * Wire Dappress into a Cypress project. Call it from setupNodeEvents:
- *
- *   setupNodeEvents(on, config) {
- *     return configureDappress(on, config);
- *   }
- *
- * It loads the MetaMask extension into the browser Cypress launches, and
- * registers the tasks behind the cy.* commands from 'dappress/support'.
- */
-function configureDappress(on, config, userOptions = {}) {
-  const options = resolveOptions(userOptions, config);
-  if (config.chromeWebSecurity === false) {
-    console.warn('[dappress] chromeWebSecurity is off: MetaMask cannot start its snaps, so adding or importing an account will hang');
-  }
-
-  // A cached wallet gets its requests in MetaMask's popup window, which headless Chrome doesn't open
-  const usesCache = (browser) => options.cache && !browser.isHeadless;
-
-  // Build the wallet profile before the run, out of the time Cypress allows a browser to come up
-  on('before:run', async ({ browser }) => {
-    if (browser && usesCache(browser)) await prepareProfile({ browserPath: browser.path, extensionDir: await prepareExtension(options), options });
-  });
-
-  on('before:browser:launch', async (browser, launchOptions) => {
-    if (browser.family !== 'chromium') {
-      throw new Error(`[dappress] MetaMask is a Chromium extension; ${browser.name} is not supported`);
-    }
-    const extensionDir = await prepareExtension(options);
-    launchOptions.extensions.push(extensionDir);
-    if (browser.isHeadless) {
-      // Cypress leaves extensions out of a headless launch, so ask Chrome directly
-      launchOptions.args.push(`--load-extension=${extensionDir}`);
-      if (options.cache) console.warn('[dappress] The wallet cache needs a headed browser: importing the wallet in this run instead');
-    }
-    if (usesCache(browser)) {
-      const profileDir = await prepareProfile({ browserPath: browser.path, extensionDir, options });
-      await installProfile(profileDir, browser, config.isTextTerminal);
-    }
-    return launchOptions;
-  });
-  captureDebuggerUrl(on);
-  on('task', createTasks(options));
-
-  // Non-sensitive settings the browser side reads with Cypress.expose()
-  config.expose = { ...config.expose, dappress: publicOptions(options) };
-  return config;
-}
-
-module.exports = { configureDappress };

package/src/metamask-pages.js

@@ -1,121 +0,0 @@
-// Find MetaMask's pages in the browser Cypress launched: the full-screen home
-// page, and the surface where dapp requests show up. On Chrome that surface
-// is the side panel when it is open, and the "MetaMask Dialog" popup otherwise.
-
-const { sleep } = require('./page-helpers');
-
-const HOME_PATH = '/home.html';
-const CONFIRMATION_PATHS = ['/notification.html', '/sidepanel.html'];
-
-function extensionIdOf(url) {
-  const match = /^chrome-extension:\/\/([a-z]{32})\//.exec(url);
-  return match ? match[1] : null;
-}
-
-function isHomeRoute(url) {
-  return url.includes('/notification.html') && /notification\.html(#\/?)?$/.test(url);
-}
-
-function pagesOf(browser, extensionId, pathname) {
-  return browser
-    .targets()
-    .filter((target) => target.type() === 'page' && target.url().startsWith(`chrome-extension://${extensionId}${pathname}`));
-}
-
-/**
- * MetaMask's extension id. Cypress loads its own extension in headed
- * Chromium browsers, so the id is the one whose home page is titled "MetaMask".
- */
-async function findExtensionId(browser, timeout = 30000) {
-  const deadline = Date.now() + timeout;
-  while (Date.now() < deadline) {
-    const ids = new Set(browser.targets().map((target) => extensionIdOf(target.url())).filter(Boolean));
-    for (const id of ids) {
-      if (await isMetaMask(browser, id)) return id;
-    }
-    await sleep(500);
-  }
-  throw new Error('[dappress] MetaMask extension not found in the browser. Is it loaded in before:browser:launch?');
-}
-
-async function isMetaMask(browser, extensionId) {
-  const [target] = pagesOf(browser, extensionId, HOME_PATH);
-  if (target) {
-    // 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 {
-    const response = await page.goto(`chrome-extension://${extensionId}${HOME_PATH}`, { waitUntil: 'domcontentloaded' });
-    return Boolean(response && response.ok()) && (await page.title()).startsWith('MetaMask');
-  } catch {
-    return false;
-  } finally {
-    await page.close();
-  }
-}
-
-/** The full-screen MetaMask page, opened if it isn't already. */
-async function getHomePage(browser, extensionId) {
-  const [target] = pagesOf(browser, extensionId, HOME_PATH);
-  if (target) return target.page();
-  const page = await browser.newPage();
-  await page.goto(`chrome-extension://${extensionId}${HOME_PATH}`, { waitUntil: 'domcontentloaded' });
-  return page;
-}
-
-/**
- * The page a dapp request is shown on. Waits for the popup to open, or takes
- * the side panel. A popup still on its home route is one closing after the
- * previous request, or one that hasn't routed to the request yet: skipped.
- */
-async function getConfirmationPage(browser, extensionId, timeout) {
-  const deadline = Date.now() + timeout;
-  while (Date.now() < deadline) {
-    for (const pathname of CONFIRMATION_PATHS) {
-      const [target] = pagesOf(browser, extensionId, pathname).filter((candidate) => !isHomeRoute(candidate.url()));
-      if (target) return pathname === '/notification.html' ? withUsableWindow(await target.page()) : target.page();
-    }
-    await sleep(250);
-  }
-  const seen = browser
-    .targets()
-    .filter((target) => extensionIdOf(target.url()) === extensionId)
-    .map((target) => `${target.type()} ${target.url()}`)
-    .join(', ');
-  throw new Error(
-    `[dappress] MetaMask showed no confirmation within ${timeout}ms. Did the dapp send a request? MetaMask pages seen: ${seen || 'none'}`,
-  );
-}
-
-// MetaMask asks Chrome for a 400x620 popup. Under Xvfb on a GitHub runner the
-// window it gets is 1x1: nothing is laid out, the pane of a confirmation that
-// must be read to the end has no height, so it can never be scrolled there and
-// its Confirm button stays disabled. The popup is given its size back first.
-const POPUP = { width: 400, height: 620 };
-
-async function withUsableWindow(page) {
-  const session = await page.target().createCDPSession();
-  try {
-    const { windowId, bounds } = await session.send('Browser.getWindowForTarget');
-    if (bounds.windowState === 'normal' && bounds.width >= 200 && bounds.height >= 200) return page;
-    console.log(`[dappress] MetaMask's popup is ${bounds.width}x${bounds.height} (${bounds.windowState}); resizing it to ${POPUP.width}x${POPUP.height}`);
-    if (bounds.windowState !== 'normal') await session.send('Browser.setWindowBounds', { windowId, bounds: { windowState: 'normal' } });
-    await session.send('Browser.setWindowBounds', { windowId, bounds: { ...POPUP } });
-    // Let the page lay itself out at its new size before anything is looked for in it
-    await sleep(300);
-  } catch (error) {
-    console.warn(`[dappress] Could not check the popup window's size: ${error.message}`);
-  } finally {
-    await session.detach().catch(() => {});
-  }
-  return page;
-}
-
-module.exports = { findExtensionId, getHomePage, getConfirmationPage, withUsableWindow };