pw-repl 0.13.0 → 0.14.0

package/AGENTS.md

@@ -56,48 +56,24 @@ If you hit a limitation or write a workaround, consider adding the capability to
   after an intended change to it, save it again (the command is in `test/units.test.js`). The common
   tasks and modes on help's front page (`TASKS` and `MODES`) are the README's too: change both, as a
   unit test compares them.
-- 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).
+- Time each full run, and put the result in the body of the commit it tests (`npm test: 151 tests, 79s`),
+  with the load average (`uptime`) when it is high. Compare with the last commit that has one (`git log
+  --grep='npm test:'`): a run that grew by more than a few seconds, at a like load (a busy machine slows
+  every test), means a slow test crept in, usually one waiting out a real timeout (5s for a click).
   Find it (each test prints its time) and make it faster, or say why it can't be, before committing.
 - Don't race the clock in a test: a page that changes on a timer, or a command timed against a budget,
   fails on a busy machine. Have the page change when the test asks (eval), or measure the thing itself
   (frames drawn, not clicks timed). A click waits for its element to hold still for two frames.
 - For anything the tests can't reach, exercise the change in a running REPL of your own: on a socket of
   your own, with `--launch` unless the change needs the user's browser, and then in a tab of your own.
+  One started before a change to `lib/` runs the old code: restart it after a change. Stop a process by
+  its pid, after checking what it is; a broad `pkill -f` pattern can match your own shell, or a REPL
+  someone else is using.
 - `skill/SKILL.md` is how agents learn to use the REPL: keep it in step with a change to how it is
   used, and leave its Custom rules section empty. Keep its `<!-- pw-repl skill stamp -->` line: `pw-repl
   skill` replaces it with the version and a hash of the skill's text, which `where` reports, so agents
   can tell a saved copy is out of date.
 
-## Waves
-
-Work goes in waves, and each one ends with a release that is ready to push.
-
-1. Build what was asked, with tests, and try it in a running REPL. For anything the user will look at
-   (a cursor, an overlay, a video), show them a demo while it is still a prototype (a recording or
-   screenshots they can open) and get their go-ahead on how it looks before writing tests or
-   building on it.
-2. Try it on a fresh agent that has not seen the code or the change (a guinea pig), on something real: a
-   small local page whose planted bugs need the change to find.
-   - Brief it with goals only: what to find out or do in the browser, never the commands.
-   - First it reads back its plan, learned from `pw-repl skill` and help alone: the commands, where it
-     found them, and what is unclear. It runs nothing yet.
-   - A wrong or unsure plan means the docs or the brief were unclear: find out which, fix that, then
-     ask again.
-   - Then it carries the plan out, in a browser and on a socket of its own, and reports as it goes:
-     above all, where the tool did something other than what the docs led it to expect.
-   - Once it has confirmed the fixes work, it reviews them as a second pair of eyes: anything important
-     they miss or get wrong, not nitpicks.
-3. Triage what it reports. Fix what matters, and what is small and useful; don't put off something
-   useful for later. Leave trivia alone, and say why.
-4. Repeat 2 and 3, with a fresh agent each time, until a pass comes back clean: no real bugs, and
-   nothing unclear in the docs or the brief that changed the plan. A pass after fixes tries the fixes,
-   and something not tried yet.
-5. Only then cut the release (Releasing, steps 1-3), and say it is ready. The maintainer pushes and
-   publishes it, and the next wave starts from what they find. A release cut too early and not pushed
-   yet is undone (its commit and tag) and cut again after the fixes.
-
 ## Releasing
 
 Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `docs:`,
@@ -106,9 +82,9 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `fe
 
 1. `npm test` passes and the working tree is clean.
 2. `npm outdated` and `npm audit` show nothing that needs doing first. Dependencies are always the newest
-   stable release, never pinned back (user ruling). When the newest breaks a test, fix it in our code;
-   only a regression of the dependency's own, with the fix already in its next release, keeps the version
-   before it, until that release ships. playwright-core stays at 1.63 for that reason: on 1.64.1 a click
+   stable release, never pinned back. When the newest breaks a test, fix it in our code; only a
+   regression of the dependency's own, with the fix already in its next release, keeps the version before
+   it, until that release ships. playwright-core stays at 1.63 for that reason: on 1.64.1 a click
    on a link to a 204 hangs at "waiting for scheduled navigations to finish" until its timeout, in plain
    Playwright too (chromium.launch, a page with a link to a 204, page.click on it); 1.65's alphas fix it.
    The test "waits for the page to load, counting a navigation that just began" shows it: move up once it
@@ -118,4 +94,6 @@ Commits follow [Conventional Commits](https://www.conventionalcommits.org/): `fe
 4. `git push --follow-tags` pushes the commits and the tag.
 5. `npm publish` publishes it; `prepublishOnly` runs the tests again first.
 
+A release cut too early and not pushed yet is undone (its commit and tag) and cut again after the fixes.
+
 Pushing and publishing need the maintainer's GitHub and npm credentials.

package/README.md

@@ -199,7 +199,10 @@ pw-repl where           # which REPL send would reach
 
 `pw-repl send` sends one command and prints its result, through the server when one is running, and
 through the `pw-repl` tmux session otherwise. Chain several in the shell: `&&` stops at the first that
-fails or is not confirmed (exit 1 or 2), and `;` carries on.
+fails or is not confirmed (exit 1 or 2), and `;` carries on. `-t` is how long it waits for the answer
+(default 20s). Times, there and in every command, are in milliseconds, as in Playwright, or in seconds
+with an `s`: `-t 90000` or `-t 90s`. A send that gives up cancels its command: one still queued never
+runs, and one running is no longer waited for.
 
 Several agents can share one REPL. `pw-repl send -c <name>` (or `PW_CLIENT=<name>`) sends as a client
 with a selected tab of its own, shown in the REPL as `[server:<name>]`. `modes` says which client turned
@@ -227,7 +230,8 @@ The body may also have `"client": "<name>"`, and `"vars": {"PW_NAME": "<value>"}
 "error", "output": "..."}`, plus `"unconfirmed": true` when the command may or may not have done what it
 was sent to do (it timed out, or the REPL quit while it ran and it was not read-only). While the REPL
 starts, `/run` answers 503 with `"starting": true`: retry. `GET /health` says `"status": "starting"` until
-it serves, then `"ok"`. `pw-repl serve <port>` serves TCP on 127.0.0.1; other addresses are refused.
+it serves, then `"ok"`. A client that closes its connection before the answer cancels the command, as
+`send` does when it gives up. `pw-repl serve <port>` serves TCP on 127.0.0.1; other addresses are refused.
 
 ## How it differs from playwright-cli
 
@@ -237,6 +241,7 @@ playwright-cli's command names and most of their options work here too (`help pl
 them). Where pw-repl differs, it is mostly because someone else may be using the browser:
 
 - `open` and `close` open a tab and turn off your modes; they never start, close or wipe a browser.
+  `close` also lists the files you wrote that are still there.
 - Routes, network and emulation apply to one tab, not the whole browser.
 - File pickers are not caught, since they may be the user's: `upload` names the input instead.
 - There is no snapshot after every command, since the user reads the REPL too; `snapshot` shows one.

package/lib/elements.js

@@ -39,7 +39,7 @@ const MODIFIERS = ['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift'];
 // click takes --click-count too; dblclick is click's count of 2.
 function clickArgs(args, usage, counts = false) {
   // Found outside quotes only, so a quoted selector keeps whatever is in it.
-  const { found, rest: text } = takeOptions((args || '').trim(), { modifiers: 'value', button: 'value', 'click-count': 'value' });
+  const { found, rest: text } = takeOptions((args || '').trim(), { modifiers: 'value', button: 'value', 'click-count': 'value', force: 'flag' });
   if (!counts && found.some(o => o.name === 'click-count')) throw new Error('dblclick is a click count of 2; for another count, click --click-count=<n>');
   const clickCount = clickCountOf(found, usage);
   const modifiers = found.filter(o => o.name === 'modifiers').flatMap(o => (o.value || '').split(',').filter(Boolean).map(keyName));
@@ -49,12 +49,14 @@ function clickArgs(args, usage, counts = false) {
   const positional = parsed && /^(?:left|right|middle)$/.test(parsed.rest || '') && (REF.test(parsed.word) || /^["']/.test(text)) ? parsed.rest : null;
   const button = chooseButton(found, positional, usage);
   const selector = positional ? parsed.selector : soleSelector(text, usage);
-  const options = { ...(button ? { button } : {}), ...(modifiers.length ? { modifiers } : {}), ...(clickCount > 1 ? { clickCount } : {}) };
+  const force = found.some(o => o.name === 'force');
+  const options = { ...(button ? { button } : {}), ...(modifiers.length ? { modifiers } : {}), ...(clickCount > 1 ? { clickCount } : {}), ...(force ? { force } : {}) };
   // The selector as written, then the kind of click, so an option never reads as part of the selector.
   const kind = [
     ...(button && button !== 'left' ? [`${button} button`] : []),
     ...(clickCount > 1 ? [`${clickCount} times`] : []),
     ...(modifiers.length ? [`with ${modifiers.join('+')}`] : []),
+    ...(force ? ['forced'] : []),
   ];
   return { selector, shown: [positional ? parsed.word : unquote(text), ...kind].join(', '), options };
 }
@@ -104,8 +106,9 @@ async function onElement(selector, action, budget = 5000) {
     console.error(`Playwright's call log:\n${message}`);
     // Found, so the ref is not stale: no hint.
     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);
+    // Unknown only once input was sent, in any retry. Playwright's checks (visible, enabled, stable, and
+    // an element covering the point) come before it logs "performing <x> action" and sends it.
+    summary.uncertain = /performing \w+ action/.test(message);
     throw summary;
   }
 }
@@ -227,6 +230,18 @@ function mouseButton(args, name) {
 // A page that renders the chosen element again (as React lists do) replaces it before it is
 // acted on; it is chosen again then, as Playwright finds a locator's element again.
 async function pointerAction(selector, act, options = {}, clicks = 0) {
+  try {
+    return await choosingPointerAction(selector, act, options, clicks);
+  } catch (error) {
+    // Playwright counts aria-disabled as disabled, though a page may keep such an element clickable.
+    if (clicks && !options.force && /: element is not enabled \(/.test(error.message)) {
+      error.message += '\nIt may be aria-disabled, which counts as disabled; --force clicks it anyway (help click).';
+    }
+    throw error;
+  }
+}
+
+async function choosingPointerAction(selector, act, options, clicks) {
   const TIMEOUT = 5000;
   const deadline = Date.now() + TIMEOUT;
   const left = () => Math.max(1000, deadline - Date.now());
@@ -426,13 +441,13 @@ function dateInputHolds(kind, value, what, selector) {
 
 const commands = {
   async click(args) {
-    const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--button=<button>] [--click-count=<n>] [--modifiers=<key>[,<key>]]', true);
+    const { selector, shown, options } = clickArgs(args, 'click <selector> [left|right|middle] [--button=<button>] [--click-count=<n>] [--modifiers=<key>[,<key>]] [--force]', true);
     const which = await pointerAction(selector, (on, sel, o) => (sel ? on.click(sel, o) : on.click(o)), options, options.clickCount || 1);
     out.log(`Clicked: ${shown}${which}`);
   },
 
   async dblclick(args) {
-    const { selector, shown, options } = clickArgs(args, 'dblclick <selector> [left|right|middle] [--button=<button>] [--modifiers=<key>[,<key>]]');
+    const { selector, shown, options } = clickArgs(args, 'dblclick <selector> [left|right|middle] [--button=<button>] [--modifiers=<key>[,<key>]] [--force]');
     const which = await pointerAction(selector, (on, sel, o) => (sel ? on.dblclick(sel, o) : on.dblclick(o)), options, 2);
     out.log(`Double-clicked: ${shown}${which}`);
   },

package/lib/help.js

@@ -216,6 +216,7 @@ afresh.`,
       ['--button=<button>', 'the button, after any selector: click #menu --button=right. Over send, the shell takes the quotes, so pw-repl send click \'#menu\' right clicks a selector "#menu right": use --button, or quote it twice (\'"#menu"\').'],
       ['--click-count=<n>', 'clicks this many times at once, as Playwright\'s clickCount: 2 is a double-click (as dblclick), 3 a triple-click, which selects a line of text or all of a field\'s. 1 to 3. Default: 1.'],
       ['--modifiers=<keys>', 'keys held down meanwhile, comma-separated: Alt, Control, ControlOrMeta, Meta, Shift.'],
+      ['--force', 'skips Playwright\'s actionability checks (enabled, stable, not covered), as Playwright\'s force. For an element marked aria-disabled, which Playwright counts as disabled, that a page keeps clickable (a greyed menu item that says why). Several matches are still chosen from as below; a covered ref or single match is clicked where it is, so what covers it gets the click.'],
     ],
     detail: `Several matches: hidden ones and ones covered by something else (a dialog's overlay) are passed over,
 and it says which it used: Clicked: text=Buy (match 3 of 4; ...), or names the first when it was the
@@ -223,8 +224,10 @@ one: (the first of 2 matches: <h1> Buy), as it may not be the one meant. If none
 says why for each and does nothing. A ref, or a single match, is clicked as it is, waiting up to 5s for
 it to be ready.
 
-Timed out after it began acting, it says what stopped it (e.g. <div class="overlay"> intercepts pointer
-events) and that the outcome is unknown; Playwright's full call log goes to the REPL's pane or log.`,
+Timed out, it says what stopped it, and Playwright's full call log goes to the REPL's pane or log. Stopped by
+one of Playwright's checks before the click is sent, it did nothing: the element is not visible, enabled
+or stable, or <div class="overlay"> intercepts pointer events (something covers it). Stopped after it was
+sent, as when the page stops answering, the outcome is unknown.`,
   },
   dblclick: {
     usage: 'dblclick <selector> [button]',
@@ -533,7 +536,7 @@ circle). That changes the page, so put it back afterwards, as it was if it had a
     summary: 'save a PNG of the viewport, --full page or an element',
     args: [
       ['[<ref>]', 'only that element, from a snapshot ref: screenshot e5.'],
-      ['[name]', 'saved as screenshot-<name>.png; letters, digits, underscores and hyphens. Default: a timestamp.'],
+      ['[name]', 'saved as screenshot-<name>.png; letters, digits, underscores and hyphens. Default: a timestamp. A word with a / or ending in .png, .jpg or .jpeg is a file instead, as --filename: x.png is the file x.png, not screenshot-x.png. At the prompt, a path with a space goes in --filename="<file>"; through pw-repl send, either works.'],
     ],
     options: [
       ['--full', 'the whole page, not only the viewport; --full-page too.'],
@@ -915,7 +918,7 @@ window.__done until it is set.`,
   },
   cdp: {
     usage: 'cdp [--all] <method> <JSON object>',
-    summary: 'send one CDP command through a temporary session',
+    summary: 'send one CDP command to the selected tab',
     args: [
       ['<method>', 'a CDP method: Network.getCookies.'],
       ['<JSON object>', 'its parameters: {} for none.'],
@@ -923,8 +926,21 @@ window.__done until it is set.`,
     options: [
       ['--all', 'the whole result, not capped.'],
     ],
-    detail: `The session is detached afterwards, so subscriptions and settings do not persist. Browser.close and
-Target.closeTarget are refused, and so is Page.handleJavaScriptDialog: dialog answers one.`,
+    detail: `A command goes through a temporary session, detached afterwards, so subscriptions and settings do not
+persist (input aside, below). Browser.close and Target.closeTarget are refused, and so is Page.handleJavaScriptDialog: dialog
+answers one.
+
+Input (Input.dispatchTouchEvent, dispatchMouseEvent, the synthesize gestures): through a session kept for
+the tab, so a sequence sent one call at a time stays one sequence (Chrome drops it when the session that
+began it detaches). End one before other commands (touchEnd, or touchCancel to drop it): left open, the
+next click lands mid-touch. Input.setIgnoreInputEvents and setInterceptDrags go through a temporary session,
+as they would otherwise stay on and break later clicks.
+
+Touch (under emulate mobile, for pointerType touch): touchStart and touchEnd sent this way make a tap, with
+click, and two in a row a dblclick; held, it is still a tap, with no contextmenu. Chrome takes a tap sent
+soon after another gesture as part of it, with no click: up to a few seconds after a drag (sleep 3s). The synthesize gestures
+(Input.synthesizeTapGesture, synthesizePinchGesture, synthesizeScrollGesture) send pointer and touch events
+but no click, dblclick or contextmenu.`,
   },
   clipboard: {
     usage: 'clipboard [--all] [--shared-clipboard]',

package/lib/inspect.js

@@ -5,7 +5,7 @@ const { state, withTimeout } = require('./state');
 const out = require('./output');
 const { printOutput } = out;
 const { devices } = require('playwright-core');
-const { toSelector, REF, unquote } = require('./syntax');
+const { toSelector, REF, SCREENSHOT_FILE, unquote } = require('./syntax');
 const { regexOf, COMMAND_TIMEOUT, BUSY_PAGE, TIME, parseDuration, durationText } = require('./util');
 const { tabState } = require('./tabstate');
 const { noteWritten } = require('./written');
@@ -316,7 +316,7 @@ const commands = {
   },
 
   async screenshot(args) {
-    const usage = 'Usage: screenshot [<ref>] [--full] [--delay|-d <time>] [name | --filename=<file>]\nNames may contain letters, digits, underscores, and hyphens.';
+    const usage = 'Usage: screenshot [<ref>] [--full] [--delay|-d <time>] [name | <file> | --filename=<file>]\nNames may contain letters, digits, underscores, and hyphens; a word with a / or ending in .png, .jpg or .jpeg is a file.';
     // 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 ' '; });
@@ -339,6 +339,11 @@ const commands = {
         if (delay === null || delay > SCREENSHOT_DELAY_MAX) throw new Error(`Usage: screenshot --delay <time> (ms, or 5s; at most ${durationText(SCREENSHOT_DELAY_MAX)})`);
         continue;
       }
+      if (SCREENSHOT_FILE.test(token)) {
+        if (file) throw new Error(usage);
+        file = token;
+        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);
@@ -599,6 +604,13 @@ const commands = {
     if (match[1] === 'Page.handleJavaScriptDialog') throw new Error(CDP_REFUSED);
     const params = JSON.parse(match[2]);
     if (!params || Array.isArray(params) || typeof params !== 'object') throw new Error('Parameters must be a JSON object');
+    // Input sent through the tab's kept session: Chrome drops a touch or mouse sequence when the session
+    // that began it detaches. Not Input's two switches, which would stay on and break later clicks.
+    if (/^Input\./.test(match[1]) && !['Input.setIgnoreInputEvents', 'Input.setInterceptDrags'].includes(match[1])) {
+      const kept = await keptSession(state.page);
+      printOutput(await withTimeout(kept.send(match[1], params), 'CDP operation', COMMAND_TIMEOUT), all);
+      return;
+    }
     const operation = async () => {
       const cdp = await state.page.context().newCDPSession(state.page);
       try {

package/lib/send.js

@@ -6,7 +6,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const client = require('./client');
-const { shellWords, variablesIn } = require('./syntax');
+const { shellWords, variablesIn, SCREENSHOT_FILE } = require('./syntax');
 
 // The prompt, after the modes on in the selected tab if any: (watch network:off) pw[serve]>
 const PROMPT = /^(?:\([^()]*\) )?pw(\[serve\])?>\s*$/;
@@ -139,7 +139,8 @@ function commandLine(words) {
     if (file) resolved = [...words.slice(0, at), `--file=${resolve(file)}`, ...rest];
   }
   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));
+    // A file as a word of its own is sent as --filename, so a space in it stays in it.
+    resolved = words.map((w, n) => (w.startsWith('--filename=') && w.length > 11 ? `--filename=${resolve(w.slice(11))}` : words[n - 1] === '--filename' ? resolve(w) : n && !w.startsWith('-') && SCREENSHOT_FILE.test(w) ? `--filename=${resolve(w)}` : w));
   }
   const quoted = requote ? resolved.map(w => (w === '' || /[\s"']/.test(w) ? doubleQuote(w) : w)) : resolved;
   // An option's value the shell kept whole stays whole too: --device='iPhone 15'.

package/lib/syntax.js

@@ -89,4 +89,7 @@ function expandVariables(line, values) {
   });
 }
 
-module.exports = { SELECTOR_FIRST, REF, toSelector, unescapeDouble, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };
+// A screenshot's file given as a word of its own: a name has neither a / nor an extension.
+const SCREENSHOT_FILE = /\/|\.(?:png|jpe?g)$/i;
+
+module.exports = { SELECTOR_FIRST, REF, SCREENSHOT_FILE, toSelector, unescapeDouble, unquote, shellWords, splitSelector, keyName, variablesIn, expandVariables };

package/lib/tabs.js

@@ -21,6 +21,12 @@ async function navigating(go) {
     for (let waited = 0; !find() && waited < 1000; waited += 50) await new Promise(resolve => setTimeout(resolve, 50));
     const navigation = find();
     if (!navigation) throw error;
+    // Chrome commits its error page just after the request fails: waited for, so info right after reads it.
+    // Capped at 1s, for a failure with no error page; a tab already on one matches at once, which info
+    // still reads right, from the log.
+    if (!stayedPut(navigation) && !/ERR_ABORTED/.test(`${navigation.status} ${navigation.failed}`)) {
+      for (let waited = 0; !state.page.url().startsWith('chrome-error://') && waited < 1000; waited += 50) await new Promise(resolve => setTimeout(resolve, 50));
+    }
     throw new Error(notLoaded(navigation));
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pw-repl",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Text REPL for driving an existing Chromium through Playwright over CDP",
   "keywords": [
     "playwright",