pw-repl 0.6.1 → 0.7.2

package/lib/help.js

@@ -38,14 +38,15 @@ Common tasks:
   see each step as I click          watch on --live
   watch a tab someone will open     watch on --next-tab [url-part]
   requests and console together     capture on, then capture off
+  a video of the page               record on, then record off
   break the backend on purpose      route <glob> <status> <json>, route <glob> abort, network off
   change or slow an API response    route <glob> patch <json>, route <glob> delay <secs>
   slow the whole network            network slow
   clean up                          modes off
 
-Modes (watch, capture, route, network off or slow, emulate) stay on until turned off; the prompt shows
-the selected tab's: (watch routes:1) pw>. tab, watch, capture, route, network, emulate and modes on
-their own show their state and what you can run next.
+Modes (watch, capture, record, route, network off or slow, emulate, viewport) stay on until turned off;
+the prompt shows the selected tab's: (watch routes:1) pw>. tab, watch, capture, record, route, network,
+emulate and modes on their own show their state and what you can run next.
 
 Topics (help <topic>):
   tabs      open, select, close, navigate        network   requests, bodies, console, fakes, network off
@@ -55,7 +56,9 @@ Topics (help <topic>):
 help <command> for usage and caveats (e.g. help route); help --all for everything.
 
 Know playwright-cli? Its command names work here too (tab-list, go-back, set-color-scheme, route
---status=...); help playwright-cli lists them.`);
+--status=...); help playwright-cli lists them.
+
+Recording video? help video says which way suits what you want.`);
 
 const TOPICS = {
   tabs: {
@@ -71,15 +74,15 @@ fill for selectors with spaces. mousemove and the other mouse commands act at a
   },
   inspect: {
     intro: `Output is capped; --all right after the command, or at the end, shows everything (text --all body).`,
-    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'viewport', 'emulate', 'wait', 'sleep'],
+    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'listeners', 'count', 'visible', 'links', 'inputs', 'screenshot', 'highlight', 'record', 'viewport', 'emulate', 'wait', 'sleep'],
   },
   network: {
     intro: `requests and console record all the time; a capture records only while it runs.`,
     commands: ['requests', 'body', 'console', 'capture', 'route', 'network'],
   },
   devtools: {
-    intro: `Cookie and storage listings omit values. eval, cdp, html, screenshots and URLs can still show
-sensitive data (cdp Network.getCookies shows cookie values).`,
+    intro: `Cookie and storage listings omit values. eval, cdp, html, screenshots, recordings and URLs can
+still show sensitive data (cdp Network.getCookies shows cookie values).`,
     commands: ['eval', 'cdp', 'cookies', 'storage'],
   },
   session: {
@@ -102,7 +105,7 @@ selected tab, if any: (watch network:off routes:2 capture) pw>. modes lists them
 
 Times (requests, console, watch) are local, with their UTC offset: 18:16:15.721-06:00.
 
-Dialogs are reported and never answered on their own; dialog answers one.`,
+Dialogs are reported and never answered on their own; dialog accept or dismiss answers one, from any client, whoever opened it.`,
     commands: ['modes', 'dialog', 'help', 'quit'],
   },
 };
@@ -219,7 +222,7 @@ out; --full shows it unchanged.
 case), each with the named elements around it. A hit with no named element around it prints without
 a path. A hit on text (a label) keeps the ref of the element holding it, so snapshot <that ref>
 shows what sits beside it, such as the value next to the label. --regex <pattern> is --grep by a
-regular expression: snapshot --regex "Total: \\d+".
+regular expression: snapshot --regex "Total: \\d+". Refs belong to the tab whose snapshot gave them.
 
 An element with no role or name of its own (a card that is only a div) is left out, with its ref;
 snapshot --full keeps it.
@@ -284,6 +287,27 @@ says how many.`,
   visible: { usage: 'visible <selector>', summary: 'whether the first match is visible' },
   links: { usage: 'links [--all]', summary: 'links on the page (text and href)' },
   inputs: { usage: 'inputs [--all]', summary: 'form controls on the page; values are omitted' },
+  highlight: {
+    usage: 'highlight [<selector> [--style=<css>] | off]',
+    summary: 'draw a box over elements, for a person or a screenshot',
+    detail: `highlight <selector> draws Playwright's highlight over every match, as playwright-cli's does: a
+tinted box, labelled with its locator, that follows the element as the page scrolls or changes, and is
+in screenshots. --style=<css> adds CSS to the box, quoted if it has spaces; this circles e5 in blue:
+  highlight e5 --style="outline: 3px solid blue; border-radius: 50%"
+
+highlight on its own lists the selected tab's highlights. highlight --hide <selector> hides one, and
+highlight --hide or highlight off hides them all. A highlight is a mode of its tab: modes shows it,
+modes off hides it, and the REPL hides every one as it stops. Loading a new page drops them; a page that
+changes its route without loading keeps them.
+
+The box is drawn over the page, in an element of Playwright's own added to it (x-pw-glass); the page's
+own elements are not changed, and clicks and typing reach them as before. Playwright always labels the
+box, and the label can cover what is just below it. For a screenshot without one, eval can outline
+the element itself (with border-radius: 50% for a circle). That changes the page, so put it back
+afterwards, as it was if it had a style of its own:
+  eval document.querySelector("#rate-3").style.outline = "3px solid blue"
+  eval document.querySelector("#rate-3").style.outline = ""`,
+  },
   screenshot: {
     usage: 'screenshot [<ref>] [--full] [-d <secs>] [name]',
     summary: 'save a PNG of the viewport, --full page or an element',
@@ -299,7 +323,41 @@ phone shows: a page laid out wider than the phone (no viewport meta tag) comes o
 
 --delay counts down out loud first (maximum 60s), so someone can hold a hover or open a menu.`,
   },
-  viewport: { usage: 'viewport [WxH]', summary: 'show or set the viewport size' },
+  record: {
+    usage: 'record [on [file] [seconds] | off [file]]',
+    summary: 'record the selected tab\'s page to a video',
+    detail: `record on starts recording the selected tab, and record off stops it and saves the file: its
+path, length, size and bytes. record on its own, or record off when nothing is recording, says whether the
+selected tab is recording, and how your last recording ended (record off, its seconds, its tab closing
+or the REPL stopping) with what record off would have said. tab close says what became of a recording it ended. A REPL stopped with pw-repl stop cannot be asked: stop prints what became of each recording it ended, and of one that ended by itself that record has not shown since.
+
+record off <file> saves it under that name instead. The format is set by record on: a name that does not end as its file does, or cannot be used, is refused, and it goes on recording. --filename=<file> is file too, as playwright-cli
+writes it.
+
+The file's ending picks the format: record on clip.mp4 records an MP4, and record on clip.webm, or record on with no file, a WebM (there is no --mp4 or --webm). The file is absolute or relative to the folder pw-repl send runs in, quoted if it has spaces, and
+owner-only, as a screenshot is; it never replaces a file. Without one, it is recording-<timestamp>.webm where screenshot saves. With seconds,
+it stops by itself after them (at most 3600, which is also the default); commands run meanwhile. One recording per tab. Another client with the tab selected can stop it too, as it can any mode; both are then told whose it was.
+
+It brings the tab to the front of its window first, as screenshot does. It records the page only,
+from inside the browser, at the viewport's size in CSS pixels, scrollbars included, made even (an
+odd width or height loses a pixel), a phone's too under emulate mobile: a Pixel 7's is 412 wide, less
+sharp than the phone draws it. It has no pointer and no browser toolbars,
+and a tab behind another, hidden or headless keeps recording. Set the size first with viewport
+(1280x720 fills a 16:9 player); a page that changes size while recording is fitted into the first size.
+Chrome sends a frame as the page draws, and a still page keeps its real length.
+
+It needs ffmpeg: $PW_FFMPEG, and only it when it is set (the REPL's, not send's); otherwise Playwright's own (npx playwright-core install ffmpeg, in $PLAYWRIGHT_BROWSERS_PATH or ~/.cache/ms-playwright), then one on the PATH. Playwright's writes only WebM; an .mp4 needs a system ffmpeg, with H.264. record on fails at once, recording nothing, without an ffmpeg that can write its format. If ffmpeg exits while recording, the recording ends then, the pane says what was saved, and the next record off fails with it. ffmpeg writes in blocks, so what it has not written yet is lost: the last seconds, or at first all of it. WebM plays in browsers,
+GitHub, GitLab and Slack; MP4 plays everywhere. It takes about 15 MB a minute.
+
+For a video with the pointer, or of the person's screen, help video compares the other ways.`,
+  },
+  viewport: {
+    usage: 'viewport [WxH | off]',
+    summary: 'show, set or unset the viewport size',
+    detail: `viewport 1280x720 sets the selected tab's page to that size, until viewport off, modes off or the
+REPL exits. The window is not resized. viewport on its own shows the size, and whether it was set or is
+the window's. emulate mobile sets a phone's size instead, and each refuses while the other is on.`,
+  },
   emulate: {
     usage: 'emulate [<what> [off] | off]',
     summary: 'emulate a phone, dark mode, a locale or a timezone',
@@ -312,10 +370,12 @@ emulate locale <tag>     the language (Accept-Language, navigator.language) and
 emulate timezone <zone>  an IANA timezone, e.g. Asia/Tokyo
 emulate <what> off       stop one (dark or light off stops the color scheme); emulate off stops all
 
-Per tab, until turned off or the REPL exits. emulate on its own shows what is on.
+Per tab, until turned off or the REPL exits; emulate mobile <device> while another is on switches to it.
+emulate on its own shows what is on.
 
 The page sees the user agent, touch and navigator.languages from its next load: reload after
-turning mobile or locale on or off. Dark, light and timezone apply at once, but what the page
+turning mobile or locale on or off. Touch means the page sees a touch screen; click still clicks
+with the mouse, and sends no touch events. Dark, light and timezone apply at once, but what the page
 already drew with them (times, colors set by its script) changes only when it reloads.
 
 While mobile is on, viewport refuses: the device sets the size.`,
@@ -453,28 +513,31 @@ already happened (requests lists those).`,
     summary: 'send one CDP command through a temporary session',
     detail: `The session is detached afterwards, so subscriptions and settings do not persist.
 
-Browser.close and Target.closeTarget are refused.`,
+Browser.close and Target.closeTarget are refused, and so is Page.handleJavaScriptDialog: dialog answers one.`,
   },
   cookies: { usage: 'cookies [--all]', summary: 'cookie names, domains and flags; values are omitted' },
   storage: { usage: 'storage [--all]', summary: 'localStorage keys; values are omitted' },
   modes: {
     usage: 'modes [off [--mine]]',
     summary: 'the modes on in every tab; modes off turns them all off',
-    detail: `The modes are watch, network off or slow, route, capture and emulate. Each is turned on and off with
-its own command: watch on|off, network off|slow|on, route <glob> ... | route off <glob>|--all,
-capture on|off, emulate ... | emulate off.
+    detail: `The modes are watch, network off or slow, route, capture, record, emulate, viewport and highlight.
+Each is turned on and off with its own command: watch on|off, network off|slow|on, route <glob> ... |
+route off <glob>|--all, capture on|off, record on|off, emulate ... | emulate off, viewport <WxH> |
+viewport off, highlight <selector> | highlight off.
 
-modes off turns off every one in every tab; a capture it stops is kept for capture to show. With
+modes off turns off every one in every tab; a capture it stops is kept for capture to show, and a
+recording it stops is saved, as record off would. With
 clients (help session), modes says which client turned each on, and modes off --mine turns off only
 the sender's own.`,
   },
   dialog: {
     usage: 'dialog [accept [text] | dismiss]',
     summary: 'show, accept or dismiss an open alert, confirm or prompt',
-    detail: `While a dialog is open, its page and the commands that read it wait. dialog runs at once, ahead
-of them; it answers the selected tab's dialog, or the only one open. accept text answers a prompt.
+    detail: `While a dialog is open, its page and the commands that read it wait, a click that opened it included, until it is answered. Commands run one at a time, so every client's commands behind that one wait too, in any tab: in a shared REPL, answer a dialog you open. dialog runs at once, ahead
+of them; it answers the selected tab's dialog (marked *), or the only one open. accept text answers a prompt, and accept alone keeps its default, as OK in the browser does.
 
-With nobody at the browser (e.g. headless), it is the only way to answer one.`,
+An agent can answer any dialog, one it opened included; one the person answers in the browser is gone
+from dialog then. cdp cannot answer one: Chrome lets only a session that saw it open do so. With nobody at the browser (e.g. headless), it is the only way to answer one.`,
   },
   help: { usage: 'help [topic | command | --all]', summary: 'this help; --all prints every topic and command in full' },
   quit: {
@@ -510,6 +573,22 @@ function renderAll() {
   return [OVERVIEW, ...sections].join('\n\n');
 }
 
+// Not a command: the ways to record a video, since none is right for every use.
+const VIDEO = `There are three ways to record a video of a page, and each gives something up.
+
+record on (help record) records the selected tab's page from inside the browser: headless, hidden and
+background tabs too, with nothing to set up but ffmpeg. It has no pointer and no browser toolbars. For
+quick clips, and for an agent recording its own work.
+
+A screen recorder on the person's machine (OBS, ffmpeg -f x11grab, macOS screencapture -v) records their
+screen as they see it, pointer included, smooth and in real time. It records the screen or a window, not
+a tab: size the window, and crop off the toolbars, for just the page. Ask before starting one, or have
+them start it. It cannot see a headless browser: for a browser of the REPL's own, --launch --headed on
+a screen. For a polished video of a person's browser.
+
+Microsoft's playwright-cli (the npm package @playwright/cli; video-start and video-stop) records a
+browser of its own, not this one, which starts logged out. For a scripted flow in a clean browser.`;
+
 function render(topicOrCommand) {
   if (!topicOrCommand) return OVERVIEW;
   if (topicOrCommand === 'playwright-cli') {
@@ -530,6 +609,7 @@ Different on purpose, since the browser may be someone else's too:
   no snapshot after each command    a person reads the pane too; snapshot when you need one
   -s=<session>                      -c <name> is the nearest: a client with a selected tab of its own`);
   }
+  if (topicOrCommand === 'video') return wrap(VIDEO);
   if (topicOrCommand === '--all') return renderAll();
   if (Object.hasOwn(TOPICS, topicOrCommand)) {
     const topic = TOPICS[topicOrCommand];
@@ -538,6 +618,14 @@ Different on purpose, since the browser may be someone else's too:
     return Object.hasOwn(COMMANDS, topicOrCommand) ? `${text}\n\n${renderCommand(topicOrCommand)}` : text;
   }
   if (Object.hasOwn(COMMANDS, topicOrCommand)) return renderCommand(topicOrCommand);
+  // A playwright-cli name: what it runs here, with that command's help.
+  const cli = require('./cli-names').describe(topicOrCommand);
+  if (cli?.nearest) return wrap(`${topicOrCommand} is playwright-cli's; ${cli.nearest}`);
+  if (cli) {
+    const here = cli.as.split(/\s/)[0];
+    const intro = wrap(`${topicOrCommand} is playwright-cli's name for ${cli.as} here.`);
+    return Object.hasOwn(COMMANDS, here) ? `${intro}\n\n${renderCommand(here)}` : intro;
+  }
   return null;
 }
 

package/lib/inspect.js

@@ -9,9 +9,10 @@ const { toSelector, REF, unquote } = require('./syntax');
 const { regexOf, COMMAND_TIMEOUT } = require('./util');
 const { tabState } = require('./tabstate');
 const { keptSession } = require('./cdp');
+const { CDP_REFUSED } = require('./dialogs');
 const { onElement, soleSelector } = require('./elements');
 const { waitForLoad, waitForRequest } = require('./requestlog');
-const { deviceMetrics } = require('./emulation');
+const { deviceMetrics, viewportMetrics } = require('./emulation');
 
 const SCREENSHOT_DELAY_MAX = 60;
 
@@ -283,11 +284,12 @@ const commands = {
       }
     } finally {
       // Playwright's screenshot resets the screen size and pixel ratio it
-      // finds; an emulated phone's are set again.
-      if (device) {
+      // finds; an emulated phone's, or a viewport's, are set again.
+      const viewport = tabState(state.page).viewport;
+      if (device || viewport) {
         const session = await keptSession(state.page);
         await session.send('Emulation.clearDeviceMetricsOverride');
-        await deviceMetrics(session, device);
+        await (device ? deviceMetrics(session, device) : viewportMetrics(session, viewport));
       }
     }
     try {
@@ -428,6 +430,7 @@ const commands = {
     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.');
+    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');
     const operation = async () => {

package/lib/modes.js

@@ -5,9 +5,11 @@ const { hints } = require('./util');
 const { tabState } = require('./tabstate');
 const { unroute } = require('./routes');
 const { setNetwork } = require('./network');
-const { emulatedKinds, setEmulation } = require('./emulation');
+const { emulatedKinds, setEmulation, setViewport } = require('./emulation');
+const { recordingOf, finishRecording } = require('./record');
 const { currentCapture, endCapture } = require('./capture');
 const { nextTabWanted, waitingText, stopWaitingForNextTab, stopWatching } = require('./watch');
+const { hideHighlights } = require('./elements');
 
 // The modes turned on in a tab, in the order the prompt shows them.
 function activeModes(p) {
@@ -17,9 +19,14 @@ function activeModes(p) {
   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 viewport = tabState(p).viewport;
+  if (viewport) modes.push(`viewport:${viewport.width}x${viewport.height}`);
   const routes = tabState(p).routes?.size;
   if (routes) modes.push(`routes:${routes}`);
+  const highlights = tabState(p).highlights?.size;
+  if (highlights) modes.push(`highlight:${highlights}`);
   if (currentCapture()?.page === p) modes.push('capture');
+  if (recordingOf(p)) modes.push('record');
   return modes;
 }
 
@@ -47,7 +54,11 @@ function listModes() {
     const owners = modeOwners(p);
     if (owners.some(([owner]) => owner)) out.log(`      on by ${ownersText(owners)}`);
   }
-  out.log(hints([['modes off', 'turn them all off']]));
+  // With clients' modes among them, the sender's own first: modes off turns off everyone's.
+  const clients = on.some(([p]) => modeOwners(p).some(([owner]) => owner));
+  out.log(hints(clients && state.client
+    ? [['modes off --mine', 'turn off the ones you turned on'], ['modes off', 'turn them all off, everyone\'s']]
+    : [['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.
@@ -59,9 +70,14 @@ function modeOwners(p) {
   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']);
+  const viewport = tabState(p).viewport;
+  if (viewport) owners.push([viewport.owner ?? null, 'viewport']);
   for (const [glob, route] of tabState(p).routes || []) owners.push([route.owner ?? null, `route ${glob}`]);
+  for (const [selector, h] of tabState(p).highlights || []) owners.push([h.owner ?? null, `highlight ${selector}`]);
   const capture = currentCapture();
   if (capture?.page === p) owners.push([capture.owner ?? null, 'capture']);
+  const recording = recordingOf(p);
+  if (recording) owners.push([recording.owner ?? null, 'record']);
   return owners;
 }
 
@@ -92,7 +108,13 @@ async function allModesOff(mine = false) {
       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'); }
+      const hidden = await hideHighlights(p, mine);
+      if (hidden) done.push(`${hidden} highlight${hidden === 1 ? '' : 's'} hidden`);
+      // Before the page's size is reset, which the recording would otherwise end with.
+      const recording = recordingOf(p);
+      if (recording && ours(recording.owner)) done.push(`record off (${(await finishRecording(recording)).replace(/\n/g, '; ')})`);
       if ('emulation' in tabState(p) && ours(tabState(p).emulation.owner)) { await setEmulation(p, {}); done.push('emulate off'); }
+      if ('viewport' in tabState(p) && ours(tabState(p).viewport.owner)) { await setViewport(p, null); done.push('viewport off'); }
     } catch (error) {
       problem = error.message;
     }