pw-repl 0.4.2 → 0.6.0

package/lib/inspect.js

@@ -0,0 +1,460 @@
+// Reading the page: text, attributes, snapshots, screenshots, eval and CDP, cookies and storage, and waits.
+const path = require('path');
+const fs = require('fs');
+const { state, withTimeout } = require('./state');
+const out = require('./output');
+const { printOutput } = out;
+const { devices } = require('playwright-core');
+const { toSelector, REF, unquote } = require('./syntax');
+const { regexOf, COMMAND_TIMEOUT } = require('./util');
+const { tabState } = require('./tabstate');
+const { keptSession } = require('./cdp');
+const { onElement, soleSelector } = require('./elements');
+const { waitForLoad, waitForRequest } = require('./requestlog');
+const { deviceMetrics } = require('./emulation');
+
+const SCREENSHOT_DELAY_MAX = 60;
+
+function nextScreenshotPath(name) {
+  const filename = name ? `screenshot-${name}` : `screenshot-${Date.now()}`;
+  // A REPL on a socket of its own keeps its screenshots next to it, as its log is.
+  return path.join(process.env.PW_SCREENSHOT_DIR || state.ownDir || '/tmp', `${filename}.png`);
+}
+
+// A screenshot of an emulated phone, taken by Chrome as it draws it. Playwright's own sizes the page
+// again for the shot, and a page with no viewport meta tag, laid out wider than the phone and shown
+// shrunk, comes out drawn small in a corner of a mostly blank image. One image pixel per CSS pixel.
+async function deviceShot(device, { ref, full, type }) {
+  const session = await keptSession(state.page);
+  let clip = null;
+  if (ref) {
+    const selector = toSelector(ref);
+    const box = await onElement(selector, async () => {
+      const locator = state.page.locator(selector);
+      await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
+      return locator.evaluate(el => { const r = el.getBoundingClientRect(); return { x: r.x + scrollX, y: r.y + scrollY, width: r.width, height: r.height }; });
+    });
+    clip = box;
+  }
+  // Measured after scrolling to the element, if any.
+  const { cssVisualViewport: view, cssContentSize: content } = await session.send('Page.getLayoutMetrics');
+  // At the size the phone shows it: a page laid out wider than the phone is shown shrunk (view.scale).
+  const scale = view.scale / devices[device].deviceScaleFactor;
+  if (clip) clip = { ...clip, scale };
+  if (full) clip = { x: 0, y: 0, width: content.width, height: content.height, scale };
+  if (!clip) clip = { x: view.pageX, y: view.pageY, width: view.clientWidth, height: view.clientHeight, scale };
+  // Beyond the visible area, Chrome lays the page out again at its whole size for the shot, which
+  // someone looking at it would see move: only for --full, and an element that does not fit.
+  const inView = clip.x >= view.pageX && clip.y >= view.pageY && clip.x + clip.width <= view.pageX + view.clientWidth && clip.y + clip.height <= view.pageY + view.clientHeight;
+  const { data } = await session.send('Page.captureScreenshot', { format: type, clip, captureBeyondViewport: full || (!!ref && !inView) });
+  return Buffer.from(data, 'base64');
+}
+
+// Unnamed generic nodes are layout wrappers (mostly divs): they add depth and
+// nothing to read. Drop them, lift their children, and drop cursor hints.
+function compactSnapshot(text) {
+  const dropped = [];
+  const lines = [];
+  for (const line of text.split('\n')) {
+    const indent = line.length - line.trimStart().length;
+    while (dropped.length && dropped[dropped.length - 1] >= indent) dropped.pop();
+    if (/^- generic(?: \[[^\]]+\])*:?$/.test(line.trim())) { dropped.push(indent); continue; }
+    lines.push(' '.repeat(Math.max(0, indent - 2 * dropped.length)) + line.trimStart().replace(/ \[cursor=pointer\]/g, ''));
+  }
+  return lines.join('\n');
+}
+
+const WAIT_DEFAULT = 10;
+const WAIT_MAX = 120;
+
+// Gone once no match is visible, whether it was removed or hidden.
+async function waitGone(locator, what, timeout) {
+  try {
+    await locator.filter({ visible: true }).first().waitFor({ state: 'detached', timeout });
+  } catch (error) {
+    if (/Timeout \d+ms exceeded/.test(error.message)) throw new Error(`Still visible after ${timeout / 1000}s: ${what}`);
+    throw error;
+  }
+  out.log(`Gone: ${what}`);
+}
+
+const SNAPSHOT_HINT_LINES = 60;
+
+// Each matching line (any part of it: role, name, flags such as [disabled]),
+// with the named elements it sits in, so a match can be placed without the
+// rest of the tree.
+// needle: text to find in any case, or a RegExp.
+function grepSnapshot(text, needle) {
+  const lower = typeof needle === 'string' ? needle.toLowerCase() : null;
+  const matches = line => (lower === null ? needle.test(line) : line.toLowerCase().includes(lower));
+  const stack = [];
+  const hits = [];
+  const label = line => line.trim().replace(/^- /, '').replace(/:$/, '').replace(/^'(.*)'$/, '$1');
+  for (const line of text.split('\n')) {
+    const indent = line.length - line.trimStart().length;
+    while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop();
+    if (matches(line)) {
+      const around = stack.filter(a => !/^generic(?: \[|$)/.test(a.label));
+      // A hit with no ref of its own (text) keeps the ref of what holds it, so
+      // snapshot <ref> can show what sits beside it: the value next to a label.
+      const own = /\[ref=/.test(line);
+      const path = around.map((a, i) => (!own && i === around.length - 1 ? a.label : a.label.replace(/ \[ref=[^\]]+\]/g, '')));
+      hits.push([...path, label(line)].join(' › '));
+    }
+    stack.push({ indent, label: label(line) });
+  }
+  return hits;
+}
+
+// A function written out (el => ..., function (el) {...}), as one expression.
+function isFunctionText(text) {
+  // Wrapped in parentheses, as (el => el.id) is often written: only when the first one closes at the end.
+  const wrapped = /^\s*\(([\s\S]*)\)\s*$/.exec(text);
+  if (wrapped && closesAtEnd(text.trim()) && isFunctionText(wrapped[1])) return true;
+  if (!/^\s*(?:async\s+)?(?:function\b|\([^)]*\)\s*=>|[\w$]+\s*=>)/.test(text)) return false;
+  try { new Function(`return (${text}\n);`); return true; } catch { return false; }
+}
+
+// Whether the opening parenthesis is matched by the last character, not earlier: (a)(b) is a call.
+function closesAtEnd(text) {
+  let depth = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] === '(') depth += 1;
+    else if (text[i] === ')') { depth -= 1; if (depth === 0) return i === text.length - 1; }
+  }
+  return false;
+}
+
+const commands = {
+  async text(args, all) {
+    const selector = soleSelector(args, 'text <selector>');
+    printOutput(await onElement(selector, () => state.page.innerText(selector, { timeout: 5000 })), all);
+  },
+
+  async html(args, all) {
+    const selector = soleSelector(args, 'html <selector>');
+    printOutput(await onElement(selector, () => state.page.$eval(selector, el => el.outerHTML)), all);
+  },
+
+  async attrs(args, all) {
+    const selector = soleSelector(args, 'attrs <selector>');
+    const result = await onElement(selector, () => state.page.$eval(selector, el => {
+      const out = {};
+      for (const attr of el.attributes) out[attr.name] = attr.value;
+      return out;
+    }));
+    printOutput(result, all);
+  },
+
+  // The page's own event listeners on an element, which only DevTools can
+  // list: the element is handed to a CDP session through the page, so any
+  // Playwright selector works, and the session asks for its listeners.
+  async listeners(args, all) {
+    const text = (args || '').trim();
+    const usage = 'listeners <selector> | listeners document | listeners window';
+    if (!text) throw new Error(`Usage: ${usage}`);
+    const which = text === 'document' || text === 'window' ? text : null;
+    const selector = which ? null : soleSelector(args, usage);
+    if (selector) await onElement(selector, () => state.page.locator(selector).first().evaluate(el => { window.__pwReplListenersOf = el; }, null, { timeout: 5000 }));
+    const cdp = await state.page.context().newCDPSession(state.page);
+    try {
+      // Chrome includes each handler's source only for an object in a named group.
+      const { result } = await cdp.send('Runtime.evaluate', { expression: which || 'window.__pwReplListenersOf', objectGroup: 'pw-repl-listeners' });
+      if (!result.objectId) throw new Error(`No element matches ${text}`);
+      const { listeners: found } = await cdp.send('DOMDebugger.getEventListeners', { objectId: result.objectId });
+      // Playwright adds its own to window once it has acted on the page; they are not the page's.
+      // Told by the script they come from, the one its hit-target check is in.
+      const own = new Set(found.filter(l => /^__playwright_/.test(l.type) || /_hitTargetInterceptor/.test(l.handler?.description || '')).map(l => l.scriptId));
+      const listeners = found.filter(l => !own.has(l.scriptId));
+      const note = found.length > listeners.length ? ` (${found.length - listeners.length} of Playwright's own left out)` : '';
+      if (!listeners.length) { out.log(`No event listeners on ${text}${note}`); return; }
+      const lines = listeners.map(l => {
+        const how = [l.useCapture && 'capture', l.once && 'once', l.passive && 'passive'].filter(Boolean).join(', ');
+        const source = l.handler?.description || '';
+        // Whole, as written, with its lines indented; or its start on one line, where ↵ marks each
+        // line break, so a // comment is seen to end there.
+        const text = all
+          ? source.split('\n').map((line, i) => (i ? `    ${line}` : line)).join('\n')
+          : source.replace(/[ \t]*\r?\n\s*/g, ' ↵ ').replace(/[ \t]+/g, ' ');
+        const handler = all || text.length <= 100 ? text : `${text.slice(0, 100)}…`;
+        return `${l.type}${how ? ` (${how})` : ''}: ${handler} (line ${l.lineNumber + 1})`;
+      });
+      printOutput(lines.join('\n'), all);
+      if (note) out.log(note.trim());
+    } finally {
+      await cdp.send('Runtime.evaluate', { expression: 'delete window.__pwReplListenersOf' }).catch(() => {});
+      await cdp.send('Runtime.releaseObjectGroup', { objectGroup: 'pw-repl-listeners' }).catch(() => {});
+      await cdp.detach().catch(() => {});
+    }
+  },
+
+  async count(args) {
+    const selector = soleSelector(args, 'count <selector>');
+    const els = await state.page.$$(selector);
+    out.log(`${els.length} element(s)`);
+  },
+
+  async visible(args) {
+    const selector = soleSelector(args, 'visible <selector>');
+    const el = await state.page.$(selector);
+    if (!el) { out.log('Not found'); return; }
+    out.log(await el.isVisible() ? 'visible' : 'hidden');
+  },
+
+  async links(_args, all) {
+    const links = await state.page.$$eval('a[href]', els =>
+      els.map(e => ({ text: e.textContent.trim(), href: e.href }))
+        .filter(l => l.text)
+    );
+    if (!links.length) { out.log('No links found'); return; }
+    printOutput(links, all);
+  },
+
+  async inputs(_args, all) {
+    const inputs = await state.page.$$eval('input, select, textarea', els =>
+      els.map(e => ({
+        tag: e.tagName.toLowerCase(),
+        type: e.type || '',
+        name: e.name || '',
+        id: e.id || '',
+        placeholder: e.placeholder || '',
+        disabled: e.disabled,
+        autocomplete: e.autocomplete || ''
+      }))
+    );
+    if (!inputs.length) { out.log('No inputs found'); return; }
+    printOutput(inputs, all);
+  },
+
+  async screenshot(args) {
+    const usage = 'Usage: screenshot [<ref>] [--full] [--delay|-d <seconds>] [name | --filename=<file>]\nNames may contain letters, digits, underscores, and hyphens.';
+    // The file first: a path may be quoted, with spaces in it.
+    let file = null;
+    const rest = (args || '').replace(/(?:^|\s)--filename(?:=|\s+)("(?:[^"\\]|\\.)*"|'[^']*'|\S+)/, (_, value) => { file = unquote(value); return ' '; });
+    const tokens = rest.trim().split(/\s+/).filter(Boolean);
+    let full = false;
+    let delay = 0;
+    let ref = null;
+    const names = [];
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i];
+      // --full-page and --filename are playwright-cli's.
+      if (token === '--full' || token === '--full-page') { full = true; continue; }
+      if (token === '--filename' || token.startsWith('--filename=')) throw new Error(usage);
+      if (!ref && !names.length && REF.test(token)) { ref = token; continue; }
+      if (token === '--delay' || token === '-d') {
+        const value = tokens[++i];
+        // Capped low on purpose: a timed shot is human-in-the-loop, and a typo
+        // like `-d 300` would otherwise park the serialized command queue.
+        if (!value || !/^\d+$/.test(value) || Number(value) > SCREENSHOT_DELAY_MAX) throw new Error(`Usage: screenshot --delay <seconds> (maximum ${SCREENSHOT_DELAY_MAX})`);
+        delay = Number(value);
+        continue;
+      }
+      names.push(token);
+    }
+    if (names.length > 1 || (names[0] && !/^[a-zA-Z0-9_-]+$/.test(names[0])) || (file && names.length) || (ref && full)) throw new Error(usage);
+    const name = names[0] || null;
+    // Counted down out loud so a watcher can time a hover or menu state, and so
+    // the wait is distinguishable from a hung command in a tmux capture.
+    for (let remaining = delay; remaining > 0; remaining--) {
+      out.log(`${remaining}...`);
+      await state.page.waitForTimeout(1000);
+    }
+    // Named after the countdown so a default filename timestamps the capture.
+    // A file given is relative to the REPL's folder; pw-repl send makes it the sender's.
+    const filepath = file ? path.resolve(file) : nextScreenshotPath(name);
+    const type = /\.jpe?g$/i.test(filepath) ? 'jpeg' : 'png';
+    // Checked before the tab is brought to the front, which can move someone's view.
+    if (fs.existsSync(filepath)) throw new Error(`Screenshot already exists: ${filepath}`);
+    if (!fs.existsSync(path.dirname(filepath))) throw new Error(`No folder ${path.dirname(filepath)} to save ${path.basename(filepath)} in`);
+    // Chrome does not draw a tab that is not in front, and tabs open in the
+    // background, so the tab is brought to the front for the shot.
+    await state.page.bringToFront();
+    let image;
+    const device = tabState(state.page).emulation?.device;
+    try {
+      if (device) {
+        image = await deviceShot(device, { ref, full, type });
+      } else if (ref) {
+        const selector = toSelector(ref);
+        image = await onElement(selector, () => state.page.locator(selector).screenshot({ type, timeout: 5000 }));
+      } else {
+        image = await state.page.screenshot({ fullPage: full, type });
+      }
+    } finally {
+      // Playwright's screenshot resets the screen size and pixel ratio it
+      // finds; an emulated phone's are set again.
+      if (device) {
+        const session = await keptSession(state.page);
+        await session.send('Emulation.clearDeviceMetricsOverride');
+        await deviceMetrics(session, device);
+      }
+    }
+    try {
+      fs.writeFileSync(filepath, image, { flag: 'wx', mode: 0o600 });
+    } catch (error) {
+      if (error.code === 'EEXIST') throw new Error(`Screenshot already exists: ${filepath}`);
+      throw error;
+    }
+    out.log(`Saved: ${filepath}`);
+  },
+
+  async snapshot(args, all) {
+    let rest = (args || '').trim();
+    const full = /^--full(?:\s|$)/.test(rest);
+    if (full) rest = rest.slice(6).trim();
+    let needle = null;
+    const grep = /^--(grep|regex)(?:\s|$)/.exec(rest);
+    if (grep) {
+      needle = rest.slice(grep[0].length).trim().replace(/^(["'])(.*)\1$/, '$2').replace(/\\"/g, '"');
+      if (!needle) throw new Error(`Usage: snapshot [--full] --${grep[1]} <${grep[1] === 'grep' ? 'text' : 'pattern'}>`);
+      if (grep[1] === 'regex') needle = regexOf(needle);
+      rest = '';
+    }
+    // Playwright's labels are e5, or frame-prefixed like f1e5 in newer versions.
+    const selector = toSelector(rest);
+    let raw;
+    // A snapshot of one element gives the page new refs, and those of the last whole-page snapshot
+    // stop working; so a ref's part is cut from a whole-page snapshot, which keeps them.
+    if (REF.test(rest)) {
+      const lines = (await state.page.ariaSnapshot({ mode: 'ai', timeout: 5000 })).split('\n');
+      const at = lines.findIndex(line => line.includes(`[ref=${rest}]`));
+      if (at === -1) throw new Error(`No element matches ${rest}\n${rest} is a snapshot ref; if the page changed since that snapshot, take a new one.`);
+      const indent = line => line.length - line.trimStart().length;
+      const end = lines.findIndex((line, i) => i > at && indent(line) <= indent(lines[at]));
+      raw = lines.slice(at, end === -1 ? undefined : end).map(line => line.slice(indent(lines[at]))).join('\n');
+    } else if (selector) {
+      raw = await onElement(selector, () => state.page.locator(selector).first().ariaSnapshot({ mode: 'ai', timeout: 5000 }));
+    } else {
+      raw = await state.page.ariaSnapshot({ mode: 'ai', timeout: 5000 });
+    }
+    const text = full ? raw : compactSnapshot(raw);
+    if (needle !== null) {
+      const hits = grepSnapshot(text, needle);
+      if (!hits.length) { out.log(`No snapshot lines match ${needle}`); return; }
+      printOutput(hits.join('\n'), all);
+      return;
+    }
+    const lines = text.split('\n').length;
+    printOutput(lines > SNAPSHOT_HINT_LINES ? `${text}\n[${lines} lines; snapshot --grep <text> or snapshot <eN> shows less]` : text, all);
+  },
+
+  async wait(args) {
+    const usage = 'Usage: wait <selector> | wait text <text> | wait request <url-part|glob> | wait load, with optional [seconds]; --gone for a selector or text';
+    let tokens = (args || '').trim().split(/\s+/).filter(Boolean);
+    const gone = tokens.includes('--gone');
+    tokens = tokens.filter(t => t !== '--gone');
+    let seconds = WAIT_DEFAULT;
+    // A number last is the seconds, unless it is all there is to wait for: wait text 990.
+    const onlyWhat = (tokens[0] === 'text' || tokens[0] === 'request') && tokens.length === 2;
+    if (tokens.length > 1 && !onlyWhat && /^\d+$/.test(tokens[tokens.length - 1])) seconds = Number(tokens.pop());
+    if (!tokens.length || seconds < 1 || seconds > WAIT_MAX) throw new Error(`${usage} (1-${WAIT_MAX})`);
+    const timeout = seconds * 1000;
+    // Said plainly, not as Playwright's call log.
+    const plainly = message => error => { throw /Timeout \d+ms exceeded/.test(error.message) ? new Error(message) : error; };
+    const kind = tokens[0];
+    if (kind === 'load' && tokens.length === 1) {
+      if (gone) throw new Error(usage);
+      return waitForLoad(timeout);
+    }
+    if ((kind === 'text' || kind === 'request') && tokens.length > 1) {
+      const what = tokens.slice(1).join(' ').replace(/^(["'])(.*)\1$/, '$2').replace(/\\"/g, '"');
+      if (kind === 'request') {
+        if (gone) throw new Error(usage);
+        return waitForRequest(what, timeout);
+      }
+      if (gone) return waitGone(state.page.getByText(what), what, timeout);
+      await state.page.getByText(what).first().waitFor({ state: 'visible', timeout }).catch(plainly(`No visible text matches ${what} within ${seconds}s`));
+      out.log(`Visible: ${what}`);
+      return;
+    }
+    const selector = toSelector(unquote(tokens.join(' ')));
+    if (gone) return waitGone(state.page.locator(selector), tokens.join(' '), timeout);
+    await state.page.waitForSelector(selector, { state: 'visible', timeout }).catch(plainly(`No visible element matches ${tokens.join(' ')} within ${seconds}s`));
+    out.log(`Visible: ${tokens.join(' ')}`);
+  },
+
+  async sleep(args) {
+    if (!args || !/^\d+$/.test(args) || Number(args) > 3600000) throw new Error('Usage: sleep <ms> (maximum 3600000)');
+    await state.page.waitForTimeout(Number(args));
+    // sleep 3 is easily meant as seconds.
+    out.log(Number(args) < 100 ? `Slept ${args}ms (sleep takes milliseconds: sleep ${args}000 is ${args}s)` : `Slept ${args}ms`);
+  },
+
+  async eval(args, all) {
+    if (!args) throw new Error('Usage: eval <js-expression>');
+    // eval <function> <ref> calls the function with that element, as playwright-cli's eval does.
+    const onRef = /^([\s\S]+?)\s+((?:f\d+)?e\d+)$/.exec(args.trim());
+    if (onRef && isFunctionText(unquote(onRef[1]))) {
+      const selector = toSelector(onRef[2]);
+      const el = await onElement(selector, () => state.page.locator(selector).first().elementHandle({ timeout: 5000 }));
+      try {
+        // Made from its text by the debugger, as eval is, so a page's CSP cannot
+        // refuse it, and in the element's own frame, which may be an iframe.
+        const fn = await withTimeout((await el.ownerFrame()).evaluateHandle(unquote(onRef[1])), 'Page evaluation', COMMAND_TIMEOUT);
+        try {
+          printOutput(await el.evaluate((e, f) => f(e), fn), all);
+        } finally {
+          await fn.dispose().catch(() => {});
+        }
+      } finally {
+        await el.dispose().catch(() => {});
+      }
+      return;
+    }
+    // A function, as playwright-cli's eval takes, is called rather than returned.
+    // Only a single expression can be one; statements are evaluated as they are.
+    // await at the top level: one expression is run as an async function; statements as DevTools'
+    // console runs them (replMode), which gives back the last one's value.
+    const compiles = (Kind, body) => { try { new Kind(body); return true; } catch { return false; } };
+    const AsyncFunction = (async () => {}).constructor;
+    const awaits = /\bawait\b/.test(args) && !compiles(Function, `return (${args}\n);`);
+    const single = compiles(awaits ? AsyncFunction : Function, `return (${args}\n);`);
+    const call = `const value = (${args}\n); return typeof value === 'function' ? value() : value;`;
+    if (awaits && !single && compiles(AsyncFunction, args)) {
+      const session = await keptSession(state.page);
+      const { result, exceptionDetails } = await withTimeout(session.send('Runtime.evaluate', { expression: args, replMode: true, awaitPromise: true, returnByValue: true }), 'Page evaluation', COMMAND_TIMEOUT);
+      if (exceptionDetails) throw new Error(exceptionDetails.exception?.description || exceptionDetails.text);
+      printOutput(result.value !== undefined ? result.value : result.description ?? 'undefined', all);
+      return;
+    }
+    const expression = single ? `(${awaits ? 'async ' : ''}() => { ${call} })()` : args;
+    const value = await withTimeout(state.page.evaluate(expression), 'Page evaluation', COMMAND_TIMEOUT);
+    // An empty string is shown as one, not as no output at all.
+    printOutput(value === '' ? '""' : value, all);
+  },
+
+  async cdp(args, all) {
+    const match = /^(\S+)\s+([\s\S]+)$/.exec(args || '');
+    if (!match) throw new Error('Usage: cdp <method> <JSON object>');
+    if (['Browser.close', 'Target.closeTarget'].includes(match[1])) throw new Error('Browser lifecycle commands are reserved; use quit or tab close.');
+    const params = JSON.parse(match[2]);
+    if (!params || Array.isArray(params) || typeof params !== 'object') throw new Error('Parameters must be a JSON object');
+    const operation = async () => {
+      const cdp = await state.page.context().newCDPSession(state.page);
+      try {
+        return await cdp.send(match[1], params);
+      } finally {
+        await cdp.detach().catch(() => {});
+      }
+    };
+    printOutput(await withTimeout(operation(), 'CDP operation', COMMAND_TIMEOUT), all);
+  },
+
+  async cookies(_args, all) {
+    const cookies = await state.page.context().cookies();
+    if (!cookies.length) { out.log('No cookies'); return; }
+    printOutput(cookies.map(({ name, domain, path, expires, httpOnly, secure, sameSite }) =>
+      ({ name, domain, path, expires, httpOnly, secure, sameSite })), all);
+  },
+
+  async storage(_args, all) {
+    const keys = await state.page.evaluate(() =>
+      Array.from({ length: localStorage.length }, (_, i) => localStorage.key(i))
+    );
+    if (!keys.length) { out.log('localStorage is empty'); return; }
+    printOutput(keys, all);
+  },
+};
+
+module.exports = { commands, compactSnapshot, grepSnapshot };

package/lib/modes.js

@@ -0,0 +1,115 @@
+// The modes on in each tab, who turned each on, and turning them off.
+const { state } = require('./state');
+const out = require('./output');
+const { hints } = require('./util');
+const { tabState } = require('./tabstate');
+const { unroute } = require('./routes');
+const { setNetwork } = require('./network');
+const { emulatedKinds, setEmulation } = require('./emulation');
+const { currentCapture, endCapture } = require('./capture');
+const { nextTabWanted, waitingText, stopWaitingForNextTab, stopWatching } = require('./watch');
+
+// The modes turned on in a tab, in the order the prompt shows them.
+function activeModes(p) {
+  const modes = [];
+  if (tabState(p).watch?.on) modes.push('watch');
+  const network = tabState(p).network;
+  if (network) modes.push(network.offline ? 'network:off' : 'network:slow');
+  const emulated = emulatedKinds(tabState(p).emulation);
+  if (emulated.length) modes.push(`emulate:${emulated.join(',')}`);
+  const routes = tabState(p).routes?.size;
+  if (routes) modes.push(`routes:${routes}`);
+  if (currentCapture()?.page === p) modes.push('capture');
+  return modes;
+}
+
+function listModes() {
+  const all = state.browser.contexts().flatMap(c => c.pages());
+  state.tabListing = all.slice();
+  const on = all.map((p, i) => [p, i, activeModes(p)]).filter(([, , modes]) => modes.length);
+  const want = nextTabWanted();
+  if (want) out.log(`${waitingText()} (watch off stops waiting)${want.client ? `, for ${want.client}` : ''}${on.length ? '\n' : ''}`);
+  if (!on.length && want) return;
+  if (!on.length) {
+    out.log('No modes are on in any tab.');
+    out.log(hints([
+      ['watch on', 'record what the person at the browser does'],
+      ['capture on', 'record requests and console messages together'],
+      ['route <url-glob> <status> <json-body>', 'fake a response'],
+      ['network off', 'cut the tab\'s network'],
+      ['emulate mobile', 'show the tab as a phone would'],
+    ]));
+    return;
+  }
+  const width = Math.max(...on.map(([p, i]) => `[${i}] ${p.url()}`.length));
+  for (const [p, i, modes] of on) {
+    out.log(`${p === state.page ? '*' : ' '} ${`[${i}] ${p.url()}`.padEnd(width)}  (${modes.join(' ')})`);
+    const owners = modeOwners(p);
+    if (owners.some(([owner]) => owner)) out.log(`      on by ${ownersText(owners)}`);
+  }
+  out.log(hints([['modes off', 'turn them all off']]));
+}
+
+// Who turned on each mode in a tab: [client, what], client null for the prompt or an unnamed sender.
+function modeOwners(p) {
+  const owners = [];
+  const watch = tabState(p).watch;
+  if (watch?.on) owners.push([watch.owner ?? null, 'watch']);
+  const network = tabState(p).network;
+  if (network) owners.push([network.owner ?? null, network.offline ? 'network:off' : 'network:slow']);
+  const emulated = tabState(p).emulation;
+  if (emulated) owners.push([emulated.owner ?? null, 'emulate']);
+  for (const [glob, route] of tabState(p).routes || []) owners.push([route.owner ?? null, `route ${glob}`]);
+  const capture = currentCapture();
+  if (capture?.page === p) owners.push([capture.owner ?? null, 'capture']);
+  return owners;
+}
+
+function ownersText(owners) {
+  const byOwner = new Map();
+  for (const [owner, what] of owners) byOwner.set(owner, [...(byOwner.get(owner) || []), what]);
+  return [...byOwner].map(([owner, whats]) => `${owner || 'unnamed'}: ${whats.join(', ')}`).join('; ');
+}
+
+// Turns off everything the REPL turned on, in every tab: nothing it leaves
+// behind keeps acting on someone's browser. mine: only what the running client turned on.
+async function allModesOff(mine = false) {
+  const all = state.browser.contexts().flatMap(c => c.pages());
+  const ours = owner => !mine || (owner ?? null) === state.client;
+  let any = false;
+  let failed = 0;
+  const want = nextTabWanted();
+  if (want && ours(want.client)) { stopWaitingForNextTab(); any = true; out.log('Stopped waiting to watch a new tab'); }
+  // A tab that fails (e.g. it crashed) must not keep the others' modes on.
+  for (const p of all) {
+    const done = [];
+    let problem = null;
+    try {
+      const watch = tabState(p).watch;
+      if (watch?.on && ours(watch.owner)) { stopWatching(p, watch); done.push('watch off'); }
+      const capture = currentCapture();
+      if (capture?.page === p && ours(capture.owner)) { endCapture(); done.push('capture off (capture shows it)'); }
+      const globs = [...(tabState(p).routes || [])].filter(([, route]) => ours(route.owner)).map(([glob]) => glob);
+      if (globs.length) { await unroute(p, globs); done.push(`${globs.length} route${globs.length === 1 ? '' : 's'} removed`); }
+      if ('network' in tabState(p) && ours(tabState(p).network.owner)) { await setNetwork(p, null); done.push('network on'); }
+      if ('emulation' in tabState(p) && ours(tabState(p).emulation.owner)) { await setEmulation(p, {}); done.push('emulate off'); }
+    } catch (error) {
+      problem = error.message;
+    }
+    if (done.length) { any = true; out.log(`${p.url()}: ${done.join(', ')}`); }
+    if (problem) { failed += 1; out.error(`${p.url()}: could not turn everything off: ${problem}`); }
+  }
+  if (failed) throw new Error(`Modes may still be on in ${failed} tab${failed === 1 ? '' : 's'}; modes lists them`);
+  if (!any) out.log(mine ? 'None of your modes were on.' : 'No modes were on.');
+}
+
+const commands = {
+  async modes(args) {
+    const arg = (args || '').trim();
+    if (!arg) return listModes();
+    if (arg !== 'off' && arg !== 'off --mine') throw new Error('Usage: modes [off [--mine]]');
+    await allModesOff(arg === 'off --mine');
+  },
+};
+
+module.exports = { commands, activeModes, allModesOff };

package/lib/network.js

@@ -0,0 +1,59 @@
+// Cutting or slowing a tab's network.
+const { state } = require('./state');
+const out = require('./output');
+const { hints } = require('./util');
+const { tabState } = require('./tabstate');
+const { keptSession } = require('./cdp');
+
+// DevTools' "Slow 4G".
+const SLOW_DEFAULT = { latency: 563, down: 1440, up: 675 };
+const SLOW_LATENCY_MAX = 10000;
+
+// setting null restores the network.
+async function setNetwork(p, setting) {
+  const session = await keptSession(p);
+  if (!('networkEnabled' in tabState(p))) { await session.send('Network.enable'); tabState(p).networkEnabled = true; }
+  await session.send('Network.emulateNetworkConditions', {
+    offline: !!setting?.offline,
+    latency: setting?.latency || 0,
+    // kbps to bytes per second; -1 is no limit.
+    downloadThroughput: setting?.down ? setting.down * 125 : -1,
+    uploadThroughput: setting?.up ? setting.up * 125 : -1,
+  });
+  if (setting) tabState(p).network = { ...setting, owner: state.client }; else delete tabState(p).network;
+}
+
+function networkText(setting) {
+  return setting.offline ? 'off (offline)' : `slow (${setting.latency}ms latency, ${setting.down} kbps down, ${setting.up} kbps up)`;
+}
+
+const commands = {
+  // A stopped upstream does not reach the browser as a failure: the dev proxy
+  // holds the request open instead of refusing it. Cutting the connection at
+  // the browser is what a visitor's wifi or VPN dropping looks like to the page.
+  async network(args) {
+    const words = (args || '').trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const setting = tabState(state.page).network;
+    if (!words.length) {
+      out.log(`The selected tab's network is ${setting ? networkText(setting) : 'on'}.`);
+      if (setting) out.log(hints([['network on', 'restore it']]));
+      else out.log(hints([['network off', 'cut it, like dropped wifi'], ['network slow [<ms> [<kbps>]]', `slow it (default ${networkText(SLOW_DEFAULT).slice(6, -1)})`]]));
+      return;
+    }
+    const [how, ...rest] = words;
+    if ((how === 'on' || how === 'off') && !rest.length) {
+      await setNetwork(state.page, how === 'on' ? null : { offline: true });
+      out.log(`The selected tab's network is ${how}`);
+      return;
+    }
+    const usage = `Usage: network [on | off | slow [<latency-ms> [<kbps>]]] (latency up to ${SLOW_LATENCY_MAX}ms)`;
+    if (how !== 'slow' || rest.length > 2 || !rest.every(w => /^\d+$/.test(w))) throw new Error(usage);
+    const [latency, kbps] = rest.map(Number);
+    if (latency > SLOW_LATENCY_MAX || kbps === 0) throw new Error(usage);
+    const slow = rest.length ? { latency, down: kbps || SLOW_DEFAULT.down, up: kbps || SLOW_DEFAULT.up } : SLOW_DEFAULT;
+    await setNetwork(state.page, slow);
+    out.log(`The selected tab's network is ${networkText(slow)}`);
+  },
+};
+
+module.exports = { commands, setNetwork };

package/lib/output.js

@@ -43,8 +43,18 @@ function onIdlePrint(printer) {
   idlePrinter = printer;
 }
 
-function notice(text) {
+// The running command's selected tab, as state.js tells it (it requires this file, not the other way).
+let selectedTab = () => null;
+
+function onSelectedTab(fn) {
+  selectedTab = fn;
+}
+
+// A notice from a tab (page) is part of a command's answer only when that command's client has
+// the tab selected: another client's tab is not what it asked about. The pane shows it either way.
+function notice(text, page = null) {
   if (!sink && idlePrinter && idlePrinter.idle()) idlePrinter.print(String(text));
+  else if (sink && page && page !== selectedTab()) console.log(text);
   else log(text);
 }
 
@@ -67,4 +77,4 @@ function printOutput(value, all = false) {
   }
 }
 
-module.exports = { OUTPUT_LIMIT, log, error, collect, take, notice, aside, onIdlePrint, printOutput };
+module.exports = { OUTPUT_LIMIT, log, error, collect, take, notice, aside, onIdlePrint, onSelectedTab, printOutput };