pw-repl 0.8.2 → 0.9.0

package/AGENTS.md

@@ -41,9 +41,14 @@ If you hit a limitation or write a workaround, consider adding the capability to
   command or behaviour. In `test/repl.test.js` each test starts in a fresh tab of its own, and every mode
   is turned off after it; a test whose REPL quits, times out or is killed goes in
   `test/repl-alone.test.js`, with a Chromium of its own.
-- Help entries (`lib/help.js`) are plain paragraphs: `wrap()` lays each out at 104 columns, and keeps as
-  written a paragraph with a bullet, a table or an indented example. `test/fixtures` holds the rendered
-  help; after an intended change to it, save it again (the command is in `test/units.test.js`).
+- A command's help (`lib/help.js`) follows playwright-cli's layout: `usage` and `summary`; `args` and
+  `options`, one `[name, text]` each, with the default in its text (`Default: 750; 0 none.`); `detail`,
+  short paragraphs on what most callers need, a paragraph on one theme starting with a label (`Steps
+  (--steps):`); and `more`, with `moreAbout` naming what is in it, for what only goes wrong now and then,
+  shown by `help <command> --all` and `help --all`. An error about something in `more` ends by naming it
+  (`help record --all`). Paragraphs are plain: `wrap()` lays each out at 104 columns, and keeps as written
+  a paragraph with a bullet, a table or an indented example. `test/fixtures` holds the rendered help;
+  after an intended change to it, save it again (the command is in `test/units.test.js`).
 - Time each full run, and put the result in the body of the commit it tests (`npm test: 151 tests, 79s`).
   Compare with the last commit that has one (`git log --grep='npm test:'`): a run that grew by more than
   a few seconds means a slow test crept in, usually one waiting out a real timeout (5s for a click).

package/README.md

@@ -78,8 +78,8 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 - For `send` to reach `run`, start it in tmux: `tmux new -s playwright-repl`, then `pw-repl run` there.
 - A URL after the command opens in a new tab: `pw-repl run http://localhost:3000`.
 - `--launch` works with each of them; flags after `--` go to that Chromium.
-- `serve` takes a socket of its own (`pw-repl serve --background /tmp/mine.sock`; then `-e /tmp/mine.sock`
-  for `send`, `attach`, `stop` and `where`), or `serve <port>` for TCP on 127.0.0.1.
+- A socket of its own: `-e /tmp/mine.sock` on every command, `serve` included (`pw-repl serve --background
+  -e /tmp/mine.sock`), or `PW_SOCKET`; `serve <port>` listens on TCP on 127.0.0.1.
 - A background REPL cannot be brought back like a Ctrl-Z job; `attach` is how you get back to it, from
   any terminal.
 
@@ -98,7 +98,7 @@ the Docker bridge gateway, `ip route | awk '/default/ {print $3}'`).
 | show an agent what I do              | `watch on`, click around in the browser, then `watch`                                 |
 | see each step as I click             | `watch on --live`                                                                     |
 | record requests and console together | `capture on`, then `capture off`                                                      |
-| record a video of the page           | `record on`, then `record off` (`help video` for the other ways)                      |
+| record a video of the page           | `record on`, then `record off` (`help video` for a take with a pointer)               |
 | show a pointer where the agent acts  | `cursor on`, then `cursor off` (in screenshots and videos)                            |
 | point something out on the page      | `highlight <ref>` (`--style=<css>` to restyle it), then `highlight off`               |
 | break the backend on purpose         | `route <glob> <status> <json>` (fake a response), `route <glob> abort`, `network off` |

package/bin/pw-repl.js

@@ -7,7 +7,7 @@ const USAGE = `Usage:
   pw-repl run [--launch [--headed]] [start-url] [-- <chromium flags>]
       connect to the browser and open the prompt
 
-  pw-repl serve [--background] [--launch [--headed]] [endpoint] [start-url] [-- <chromium flags>]
+  pw-repl serve [--background] [--launch [--headed]] [[-e] endpoint] [start-url] [-- <chromium flags>]
       the same, plus a command server (socket, port, or 127.0.0.1:port; default /tmp/playwright-repl.sock);
       --background runs it detached, with its output in a log next to the socket
 
@@ -17,8 +17,8 @@ const USAGE = `Usage:
   pw-repl stop [-e endpoint]
       stop a background REPL, and say what became of each recording it ended
 
-  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] <command...>
-      run one command in a running REPL and print its output
+  pw-repl send [-e endpoint | -s session] [-c client] [-t seconds] <command...> | --file <file>
+      run one command in a running REPL and print its output; --file runs a file of them, one per line
 
   pw-repl where [-e endpoint | -s session]
       say which REPL send would reach
@@ -31,13 +31,20 @@ const USAGE = `Usage:
 
 send uses the server when -e, $PW_ENDPOINT, or the socket ($PW_SOCKET, default /tmp/playwright-repl.sock)
 is there, and the tmux session (-s, $PW_TMUX_SESSION, default playwright-repl) otherwise. If the socket
-exists but nothing answers, send fails rather than fall back.
+exists but nothing answers, send fails rather than fall back. serve without an endpoint serves on that
+same one: $PW_ENDPOINT, then $PW_SOCKET, then the default.
 
 send -c <client> (or $PW_CLIENT) sends as a client of the REPL's with a selected tab of its own, so
 several agents can share one REPL; pw-repl help session has the rest.
 
 send exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable.
 
+send --file <file> runs each line of a file as a command, in order, as if typed at the REPL's prompt:
+quoted as the prompt reads it (no shell), with a file it records, uploads or saves relative to this
+folder, as on send's command line, and # comments and blank lines skipped. It stops at the first
+command that fails, saying its line, with its exit status. -t is each command's own limit. Other
+clients' commands can run between its lines, on their own tabs.
+
 The browser must be running with --remote-debugging-port (default http://localhost:9222; set $PW_CDP_URL).
 
 --launch is the quick start instead: it starts a Chromium of the REPL's own (headless unless --headed, in
@@ -50,8 +57,8 @@ In a tmux session named playwright-repl, pw-repl send reaches pw-repl run withou
 
 const REPL_HELP = `The REPL's own commands: help at the pw> prompt, or pw-repl send help here (no REPL needed).
 
-pw-repl help <topic | command | --all> shows one part of it; pw-repl help video and pw-repl help
-playwright-cli are guides.`;
+pw-repl help <topic | command [--all] | --all> shows one part of it; pw-repl help video and pw-repl
+help playwright-cli are guides.`;
 
 function usage() {
   console.error(USAGE);
@@ -60,7 +67,7 @@ function usage() {
 
 // -e, -s, -c and -t, then the command words (unquoted words are one command).
 function parseSendArgs(args, allowCommand) {
-  const options = { endpoint: null, session: null, client: null, timeout: 20, command: '' };
+  const options = { endpoint: null, session: null, client: null, timeout: 20, command: '', file: null };
   let i = 0;
   for (; i < args.length; i++) {
     const arg = args[i];
@@ -73,6 +80,13 @@ function parseSendArgs(args, allowCommand) {
       console.error('browser it shares, cookies, storage and modes and all.');
       process.exit(64);
     }
+    // A file of commands, one per line, as typed at the prompt.
+    if (arg.startsWith('--file=') && arg.length > 7) { options.file = require('path').resolve(arg.slice(7)); continue; }
+    if (arg === '--file') {
+      if (args[i + 1] === undefined) usage();
+      options.file = require('path').resolve(args[++i]);
+      continue;
+    }
     if (arg === '-e' || arg === '-s' || arg === '-c' || arg === '-t') {
       const value = args[++i];
       if (value === undefined) usage();
@@ -96,39 +110,9 @@ function parseSendArgs(args, allowCommand) {
     }
   }
   const words = args.slice(i);
-  if (!allowCommand && words.length) usage();
-  // For a command that reads a quoted selector (fill "text=Your name" Ada), a
-  // word the shell kept whole is quoted again so it stays one word. Any other
-  // command takes the rest of its line as it is (eval, route's JSON), so its
-  // words are joined as they are.
-  const { SELECTOR_FIRST } = require('../lib/syntax');
-  // So does playwright-cli's storage key (localstorage-set "my key" v).
-  // And record's file, which may have spaces in it.
-  const requote = words.length > 1 && (SELECTOR_FIRST.has(words[0]) || /^(?:local|session)storage-/.test(words[0]) || words[0] === 'record' || /^video-(?:start|stop)$/.test(words[0]));
-  // An empty word (fill #name "") is the empty value.
-  // upload's files are read by the REPL, whose folder may not be this one.
-  // So are the files upload reads and screenshot --filename writes.
-  const resolve = require('path').resolve;
-  let resolved = words[0] === 'upload' ? words.map((w, n) => (n > 1 ? resolve(w) : w)) : words;
-  // record on <file> writes it too.
-  if (words[0] === 'record' || /^video-(?:start|stop)$/.test(words[0])) {
-    resolved = words.map((w, n) => {
-      if (n < (words[0] === 'record' ? 2 : 1)) return w;
-      if (w.startsWith('--filename=') && w.length > 11) return `--filename=${resolve(w.slice(11))}`;
-      return words[n - 1] === '--filename' || !/^(?:\d+|-.*)$/.test(w) ? resolve(w) : w;
-    });
-  }
-  if (words[0] === 'screenshot') {
-    resolved = words.map((w, n) => (w.startsWith('--filename=') && w.length > 11 ? `--filename=${resolve(w.slice(11))}` : words[n - 1] === '--filename' ? resolve(w) : w));
-  }
-  const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? JSON.stringify(w) : w)) : resolved;
-  // An option's value the shell kept whole stays whole too: --device='iPhone 15'.
-  // Single quotes escape nothing, so a backslash (a regexp's \d) reaches it as typed.
-  for (const [n, w] of quoted.entries()) {
-    const option = /^(--[A-Za-z][\w-]*=)([\s\S]*\s[\s\S]*)$/.exec(w);
-    if (n && option && !requote) quoted[n] = `${option[1]}${option[2].includes("'") ? JSON.stringify(option[2]) : `'${option[2]}'`}`;
-  }
-  options.command = quoted.join(' ').trim();
+  if (!allowCommand && (words.length || options.file)) usage();
+  if (options.file && words.length) usage();
+  options.command = require('../lib/send').commandLine(words);
   return options;
 }
 
@@ -143,7 +127,15 @@ function startOptions(args, serve) {
   options.launch = flag('--launch');
   options.headed = flag('--headed');
   if ((options.headed || options.chromeArgs.length) && !options.launch) usage();
-  if (serve && rest[0] && looksLikeEndpoint(rest[0])) options.endpoint = rest.shift();
+  // -e <endpoint>, as send, attach, stop and where take it, or the endpoint as the first word.
+  const e = rest.indexOf('-e');
+  if (serve && e !== -1 && rest[e + 1] && looksLikeEndpoint(rest[e + 1])) {
+    options.endpoint = rest.splice(e, 2)[1];
+    // Two endpoints, one with -e: neither silently wins.
+    if (rest[0] && looksLikeEndpoint(rest[0])) usage();
+  } else if (serve && rest[0] && looksLikeEndpoint(rest[0])) options.endpoint = rest.shift();
+  // Otherwise the socket send would look for: PW_ENDPOINT, then PW_SOCKET, then the default.
+  if (serve && !options.endpoint) options.endpoint = process.env.PW_ENDPOINT || process.env.PW_SOCKET || null;
   if (rest.length > 1 || (rest[0] && rest[0].startsWith('-'))) usage();
   options.startUrl = rest[0] || null;
   return options;

package/lib/cli-names.js

@@ -91,9 +91,10 @@ for (const what of ['reduced-motion', 'forced-colors', 'contrast', 'media']) {
   NEAREST[`clear-${what}`] = 'not here yet; emulate dark|light sets the color scheme';
 }
 for (const name of ['request-headers', 'response-headers', 'request-body']) NEAREST[name] = 'not here yet; body <#> shows the response body';
-for (const name of ['video-chapter', 'video-show-actions', 'video-hide-actions']) {
-  NEAREST[name] = 'not here: record on|off records a video, without chapters or action labels';
-}
+NEAREST['video-chapter'] = 'not here: record on|off records a video, without chapters';
+// Theirs labels each action and pauses on it; the cursor is a pointer that moves to each action instead.
+NEAREST['video-show-actions'] = 'not here; cursor on draws a pointer that moves to each action, without labels';
+NEAREST['video-hide-actions'] = 'not here; cursor off hides the pointer cursor on draws';
 for (const name of ['pause-at', 'resume', 'step-over']) NEAREST[name] = 'not here: they step through a Playwright test';
 
 const NAME_LIST = Object.keys(NAMES);

package/lib/client.js

@@ -69,6 +69,9 @@ function request(endpoint, command, timeoutMs, client = null) {
       ...target(endpoint),
       path: '/run',
       method: 'POST',
+      // A connection of its own each time: on one kept alive from an earlier command (send --file),
+      // 'connect' never fires, and a drop would be taken for a command never sent.
+      agent: false,
       headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
     }, res => {
       let text = '';

package/lib/cursor.js

@@ -9,7 +9,7 @@ const { unquote, toSelector } = require('./syntax');
 const { recordingOf, stepTarget, cursorStep } = require('./record');
 
 // Scaled with the distance, so a short hop is quick and a long one does not drag. Slower while the tab
-// records, so a video (and a zoom that follows the cursor) can be followed.
+// records, so a viewer can follow it.
 const DWELL_MS = 300;
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
 
@@ -80,8 +80,8 @@ function pageCursor({ x, y, action, ms, count, fade, box, items, index }) {
     cursor.y = y;
     place(cursor.arrow, x, y);
     if (!ms) return;
-    // Smoothstep, exactly (x = t with these control points, and y = 3t² - 2t³): the easing a zoom that
-    // follows the cursor uses, so it knows where the cursor is on every frame.
+    // Smoothstep, exactly (x = t with these control points, and y = 3t² - 2t³), so a tool editing the
+    // video can work out from the steps file where the cursor is on every frame.
     const glide = cursor.arrow.animate([{ transform: from }, { transform: to }], { duration: ms, easing: 'cubic-bezier(0.3333, 0, 0.6667, 1)' });
     // A hidden tab draws no frames, and its animation may never finish: not waited on past its time.
     return Promise.race([glide.finished, new Promise(resolve => setTimeout(resolve, ms + 300))]).then(() => {}, () => {});
@@ -158,19 +158,52 @@ async function glideTo(p, x, y) {
   const cursor = cursorOf(p);
   if (!cursor) return;
   const ms = glideTime(Math.hypot(x - cursor.x, y - cursor.y), !!recordingOf(p));
-  // A recording notes where the pointer went and when, for a zoom to follow it.
+  // A recording with --steps notes where the pointer went and when, for whoever edits the video.
   if (ms) cursorStep(p, `(cursor from ${cursor.x} ${cursor.y})`, { x, y }, ms);
   cursor.x = x;
   cursor.y = y;
   await p.evaluate(pageCursor, { x, y, action: 'move', ms }).catch(() => {});
 }
 
-// Whether a command should find its element first: to glide the cursor there, or to note it in a
-// recording's steps.
+// Whether a command should find its element first: to glide the cursor there, or, while recording, to
+// scroll to it smoothly and note it in the steps (record on --steps).
 function aiming(p) {
   return !!(cursorOf(p) || recordingOf(p));
 }
 
+// While recording, an element out of view is scrolled to smoothly, to the middle, rather than jumped to
+// as Playwright's own scroll would. The page scrolls itself, so no input is sent and a scrollable box
+// it is in scrolls too. One larger than the view is scrolled to only if its centre, where Playwright
+// acts, is out of view. Done when it has held still for a few frames: a nested box ends its scroll on
+// its own, and nothing ends one that never started.
+async function scrollSmoothly(target) {
+  // Chrome slows a background tab's timers too, so the REPL bounds the wait as well.
+  await Promise.race([sleep(2000), target.evaluate(async (el, cap) => {
+    const r = el.getBoundingClientRect();
+    const cx = r.left + r.width / 2;
+    const cy = r.top + r.height / 2;
+    const inView = r.width > innerWidth || r.height > innerHeight
+      ? cx >= 0 && cy >= 0 && cx <= innerWidth && cy <= innerHeight
+      : r.left >= 0 && r.top >= 0 && r.right <= innerWidth && r.bottom <= innerHeight;
+    if (inView) return;
+    el.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'center' });
+    // A tab that is not drawing (behind another, minimised) has no frames: the timer keeps the cap.
+    const frame = () => new Promise(resolve => { requestAnimationFrame(resolve); setTimeout(resolve, 100); });
+    const started = performance.now();
+    const from = `${r.left},${r.top}`;
+    let last = from;
+    let still = 0;
+    // A smooth scroll can take a frame or two to start: longer to wait while nothing has moved yet.
+    while (performance.now() - started < cap && still < (last === from ? 10 : 3)) {
+      await frame();
+      const b = el.getBoundingClientRect();
+      const at = `${b.left},${b.top}`;
+      still = at === last ? still + 1 : 0;
+      last = at;
+    }
+  }, 1500).catch(() => {})]);
+}
+
 // Finds the centre of an element (a locator or a handle), where Playwright clicks, after scrolling it
 // into view as Playwright would, and glides the cursor there if it is on: the pointer is there before
 // the click, not after. A recording notes the element in its steps.
@@ -182,6 +215,7 @@ async function aimAt(p, target, timeout) {
   if (target.waitFor) await target.waitFor({ state: 'attached', timeout });
   try {
     if (!await target.isVisible()) return null;
+    if (recordingOf(p)) await scrollSmoothly(target);
     await target.scrollIntoViewIfNeeded({ timeout: 2000 });
     const box = await target.boundingBox({ timeout: 1000 });
     if (!box) return null;
@@ -270,10 +304,11 @@ const commands = {
     const usage = 'Usage: cursor [on [<selector> | <x> <y>] | off]';
     const on = /^on(?:\s+([\s\S]+))?$/.exec(arg);
     if (!on) throw new Error(usage);
-    if (cursor) { out.log(`The cursor is already on in the selected tab, at ${cursor.x}, ${cursor.y}; mousemove or a command on an element moves it`); return; }
     // Where it is asked to appear (a video's first element, say), or where the mouse last went, if the
     // REPL knows; otherwise the middle of the viewport.
     const where = (on[1] || '').trim();
+    if (cursor && !where) { out.log(`The cursor is already on in the selected tab, at ${cursor.x}, ${cursor.y}; cursor on <selector> or <x> <y> moves it`); return; }
+    const still = cursor ? 'the cursor stays where it was' : 'the cursor is still off';
     let at;
     if (/^-?\d+(?:\.\d+)?\s+-?\d+(?:\.\d+)?$/.test(where)) {
       const [x, y] = where.split(/\s+/).map(n => Math.round(Number(n)));
@@ -283,14 +318,20 @@ const commands = {
       try {
         await target.scrollIntoViewIfNeeded({ timeout: 5000 });
       } catch {
-        throw new Error(`No element matches ${where} that can be shown (waited 5s); the cursor is still off`);
+        throw new Error(`No element matches ${where} that can be shown (waited 5s); ${still}`);
       }
       const box = await target.boundingBox();
-      if (!box) throw new Error(`${where} is not on the page to show the cursor at; the cursor is still off`);
+      if (!box) throw new Error(`${where} is not on the page to show the cursor at; ${still}`);
       at = { x: Math.round(box.x + box.width / 2), y: Math.round(box.y + box.height / 2) };
     } else {
       at = tabState(p).mouseAt || await p.evaluate(() => ({ x: Math.round(innerWidth / 2), y: Math.round(innerHeight / 2) }));
     }
+    // Already on: the drawing glides there, and the real mouse stays put, as with fill.
+    if (cursor) {
+      await glideTo(p, at.x, at.y);
+      out.log(`The cursor moved to ${at.x}, ${at.y}`);
+      return;
+    }
     await p.evaluate(pageCursor, { x: at.x, y: at.y, action: 'draw', fade: true });
     tabState(p).cursor = { owner: state.client, x: at.x, y: at.y };
     cursorStep(p, '(cursor on)', at, 0);

package/lib/elements.js

@@ -66,8 +66,9 @@ function selectorAndValue(args, usage, example) {
 // An element that never appeared is said plainly, not as Playwright's call
 // log, and so is one that timed out: its call log (dozens of lines of retries) goes
 // to the REPL's pane and log only. A ref that no longer matches usually means the page
-// changed since the snapshot it came from.
-async function onElement(selector, action) {
+// changed since the snapshot it came from. It says the command's whole budget: Playwright's own
+// timeout is what was left of it for the last call, after a glide say, and can read 4999ms for 5000.
+async function onElement(selector, action, budget = 5000) {
   try {
     return await action();
   } catch (error) {
@@ -77,12 +78,12 @@ async function onElement(selector, action) {
     const staleRef = ref ? `\n${ref} is a snapshot ref; if the page changed since that snapshot, take a new one.` : '';
     const timeout = /Timeout (\d+)ms exceeded/.exec(message);
     if (timeout && /waiting for locator/.test(message) && !/resolved to/.test(message)) {
-      throw new Error(`No element matches ${ref || selector} (waited ${timeout[1] / 1000}s)${staleRef}`);
+      throw new Error(`No element matches ${ref || selector} (waited ${budget / 1000}s)${staleRef}`);
     }
     if (!timeout) { error.message += staleRef; throw error; }
     console.error(`Playwright's call log:\n${message}`);
     // Found, so the ref is not stale: no hint.
-    const summary = new Error(`Timed out after ${timeout[1] / 1000}s on ${ref || selector}: ${lastBlocker(message)} (its call log is in the REPL's pane or log)`);
+    const summary = new Error(`Timed out after ${budget / 1000}s on ${ref || selector}: ${lastBlocker(message)} (its call log is in the REPL's pane or log)`);
     // Worked out from the whole log: the summary no longer says whether the element was found.
     summary.uncertain = !/waiting for locator/.test(message) || /resolved to/.test(message);
     throw summary;