pw-repl 0.11.3 → 0.11.5

package/AGENTS.md

@@ -4,6 +4,9 @@ How to use the REPL is in the skill `bin/pw-repl.js skill` prints (from `skill/S
 its version and hash). Read it first. In this clone, `pw-repl` there means `bin/pw-repl.js` (from the
 folder this file is in) when it is not installed globally.
 
+If there is a local agent file (e.g. `AGENTS.LOCAL.md`) next to this file, read it too.
+They add to the rules in this file, and where the two differ, the local file wins.
+
 ## Contributing
 
 If you hit a limitation or write a workaround, consider adding the capability to the REPL instead.

package/lib/help.js

@@ -156,7 +156,7 @@ const COMMANDS = {
       ['<index>', 'selects by the number in your latest listing (each client has its own); numbers change when tabs open or close.'],
       ['<url-part>', 'selects the one tab whose URL contains it; refused if none or several do.'],
       ['new [url]', 'opens a tab behind the one in front, so it does not take the window from whoever is using it, and selects it. The URL is read as goto reads it.'],
-      ['close [url-part]', 'closes the selected tab, or the one matching url-part.'],
+      ['close [url-part]', 'closes the selected tab, or the one matching url-part; of several, the one you opened, if exactly one of them is, and refused otherwise.'],
     ],
     detail: `Closing the selected tab goes back to the previous tab if tab new opened it; otherwise no tab is
 selected, and commands that need one refuse until one is.
@@ -316,7 +316,8 @@ to the label.
 Passwords: a password field's value is shown as (a password: not shown), --full too, as is that of a
 field whose autocomplete is for a password, a one-time code or a card number; html and attrs show its
 value attribute so too. A field a Show password button made plain text, with no such autocomplete,
-shows its value.
+shows its value. Every other field shows what it holds (textbox "Name": Ada), and a select its chosen
+option: inputs lists the fields without what they hold.
 
 Output over 60 lines ends with a line count.`,
   },
@@ -341,7 +342,8 @@ Output over 60 lines ends with a line count.`,
 navigation, described by role and name as in snapshot, with up to 5 of the requests it caused under it,
 each with its status as in requests (body <#> for one), leaving out scripts and what requests hides. The
 REPL's own fill shows as type. A double-click shows as two clicks; hovering and moving the mouse are not
-recorded.
+recorded. When other elements are described alike (cards that repeat their buttons), the step says which
+one: (under "<its nearest heading>"), with n of N where the heading does not settle it.
 
 Privacy: what is typed is recorded, and watch and watch save show it, except in a password field: one
 that was ever type=password, or whose autocomplete is for a password, a one-time code or a card number.
@@ -380,7 +382,9 @@ off leaves the wait on.
 
 watch save: a submit is left out, since the click or Enter that caused it is there. So is a URL the app
 changed without loading a page (history.pushState or replaceState), as a comment: the step before it
-changes it again. A click on a label is the click it passes on to its control, and saved as that.
+changes it again. A click on a label that holds its control is the control's click, as it passes it on;
+one on a label that names its control with for= is the label's, since that can be a control anywhere
+(the first of a page's repeated ids), and a for= label on a checkbox toggles it rather than checks it.
 In an open shadow root, an element's selector is its host's, then its own; a closed one is out of reach.`,
   },
   text: { usage: 'text [--all] <selector>', summary: 'visible text of the first match' },
@@ -400,7 +404,15 @@ Playwright adds to window as it acts are left out, and it says how many.`,
   count: { usage: 'count <selector>', summary: 'number of matches' },
   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' },
+  inputs: {
+    usage: 'inputs [--all]',
+    summary: 'form controls, native and ARIA; values are omitted',
+    detail: `Each control as JSON: tag, role, type, name, id, label, placeholder, disabled (by its own attribute,
+a disabled fieldset around it, or aria-disabled), readonly, checked for a checkbox, radio or switch (true,
+false or "mixed"), and autocomplete. An ARIA control is an element with role checkbox, radio, switch, combobox, listbox, textbox,
+searchbox, slider or spinbutton, as Radix and the like draw them (a button that is a radio); its role
+says what it is, and type is a native control's own. What a field holds is never shown.`,
+  },
   highlight: {
     usage: 'highlight [<selector> | off] [options]',
     summary: 'draw a box over elements, for the user or a screenshot',

package/lib/inspect.js

@@ -15,6 +15,8 @@ const { waitForLoad, waitForRequest } = require('./requestlog');
 const { deviceMetrics, viewportMetrics, reapplyMetrics } = require('./emulation');
 
 const SCREENSHOT_DELAY_MAX = 60;
+// What inputs lists: native form controls, and elements that are one by their ARIA role.
+const INPUTS = ['input', 'select', 'textarea', ...['checkbox', 'radio', 'switch', 'combobox', 'listbox', 'textbox', 'searchbox', 'slider', 'spinbutton'].map(role => `[role=${role}]`)].join(', ');
 
 function nextScreenshotPath(name) {
   const filename = name ? `screenshot-${name}` : `screenshot-${Date.now()}`;
@@ -262,18 +264,46 @@ const commands = {
     printOutput(links, all);
   },
 
+  // Native controls and ARIA ones (a button with role=radio, as Radix draws them), each with what names
+  // it and, for a checkbox, radio or switch, whether it is checked: true, false or "mixed" for both.
   async inputs(_args, all) {
-    const inputs = await state.page.$$eval('input, select, textarea', els =>
-      els.map(e => ({
+    const inputs = await state.page.$$eval(INPUTS, els => {
+      const plain = text => (text || '').replace(/\s+/g, ' ').trim().slice(0, 60);
+      // A label's own words, without what the fields inside it hold.
+      const labelText = label => {
+        const copy = label.cloneNode(true);
+        copy.querySelectorAll('select, textarea, input, button').forEach(n => n.remove());
+        return copy.textContent;
+      };
+      const labelOf = e => {
+        const byIds = (e.getAttribute('aria-labelledby') || '').split(/\s+/).map(id => id && document.getElementById(id)).filter(Boolean);
+        if (byIds.length) return plain(byIds.map(n => n.textContent).join(' '));
+        return plain(e.getAttribute('aria-label')) || plain([...(e.labels || [])].map(labelText).join(' ')) || plain(e.getAttribute('title'));
+      };
+      const native = e => e.matches('input, select, textarea');
+      const checkedOf = e => {
+        if (native(e) && /^(?:checkbox|radio)$/.test(e.type)) return e.indeterminate ? 'mixed' : e.checked;
+        if (!/^(?:checkbox|radio|switch)$/.test(e.getAttribute('role'))) return undefined;
+        const state = e.getAttribute('aria-checked');
+        return state === 'mixed' ? 'mixed' : state === 'true';
+      };
+      return els.map(e => ({
         tag: e.tagName.toLowerCase(),
-        type: e.type || '',
-        name: e.name || '',
+        role: e.getAttribute('role') || '',
+        // A button's own type (submit) is not what kind of control it is: its role says that.
+        type: native(e) ? e.type : '',
+        name: e.getAttribute('name') || '',
         id: e.id || '',
-        placeholder: e.placeholder || '',
-        disabled: e.disabled,
-        autocomplete: e.autocomplete || ''
-      }))
-    );
+        label: labelOf(e),
+        placeholder: e.getAttribute('placeholder') || '',
+        // By its own attribute (a button that is a radio, as Radix does it), a disabled fieldset around it,
+        // or aria-disabled.
+        disabled: e.matches(':disabled') || e.getAttribute('aria-disabled') === 'true',
+        readonly: e.matches('input, textarea') ? e.readOnly : e.getAttribute('aria-readonly') === 'true',
+        checked: checkedOf(e),
+        autocomplete: native(e) ? e.autocomplete || '' : ''
+      }));
+    });
     if (!inputs.length) { out.log('No inputs found'); return; }
     printOutput(inputs, all);
   },

package/lib/tabs.js

@@ -164,11 +164,13 @@ const commands = {
       ensureDialogHandler(p);
       await keepDrawing(p);
     };
-    const byUrl = part => {
+    // Opened by this client, with tab new: the prompt's and nameless senders' are theirs together.
+    const mine = p => 'opened' in tabState(p) && tabState(p).owner === state.client;
+    const byUrl = (part, closing = false) => {
       const matches = all.filter(p => p.url().includes(part));
       if (matches.length === 1) return matches[0];
       if (!matches.length) throw new Error(`No tab URL contains "${part}"`);
-      throw new Error(`${matches.length} tabs match "${part}"; use a longer part:\n${matches.map(p => `  ${p.url()}`).join('\n')}`);
+      throw new Error(`${matches.length} tabs match "${part}"; use a longer part, or tab <index> from tab's listing${closing ? ', then tab close' : ''}:\n${matches.map(p => `  ${p.url()}${mine(p) ? '  (opened by you)' : ''}`).join('\n')}`);
     };
     if (/^\d+$/.test(subcommand)) {
       if (parts.length) throw new Error(usage);
@@ -196,7 +198,11 @@ const commands = {
       return listTabs();
     }
     if (subcommand === 'close') {
-      const target = parts.length ? byUrl(parts.join(' ')) : state.page;
+      const part = parts.join(' ');
+      const matches = part ? all.filter(p => p.url().includes(part)) : [];
+      // Of several, the one tab you opened is the one to close: the others may be someone else's.
+      const yours = matches.length > 1 && matches.filter(mine).length === 1 ? matches.find(mine) : null;
+      const target = yours || (part ? byUrl(part, true) : state.page);
       if (!target || target.isClosed() || !all.includes(target)) throw new Error('Selected tab is unavailable. Run tab again.');
       if (all.length <= 1) throw new Error('Refusing to close the last tab');
       const url = target.url();
@@ -208,7 +214,7 @@ const commands = {
         state.page = back && !back.isClosed() && 'opened' in tabState(back) ? back : null;
         state.previousPage = null;
       }
-      out.log(`Closed ${url}${wasSelected && !state.page ? '; no tab is selected now' : ''}`);
+      out.log(`Closed ${url}${yours ? `, the one you opened; ${matches.length - 1} other ${matches.length === 2 ? 'tab matches' : 'tabs match'} "${part}"` : ''}${wasSelected && !state.page ? '; no tab is selected now' : ''}`);
       if (recording) out.log(await endedByTabClose(recording));
       return listTabs();
     }

package/lib/watch.js

@@ -64,6 +64,30 @@ const WATCH_SCRIPT = `(() => {
       || el.getAttribute('placeholder') || el.getAttribute('title') || (typedInto(el) || hasEditable(el) ? '' : el.innerText));
   };
   const describe = el => { const name = nameOf(el); return roleOf(el) + (name ? ' ' + JSON.stringify(name) : ''); };
+  // Which of the elements described alike this one is: under its nearest heading, and n of N where that
+  // does not settle it (cards that repeat a heading). Empty when nothing else is described as it is.
+  const HEADING = 'h1,h2,h3,h4,h5,h6,[role=heading]';
+  const headingOf = el => {
+    for (let at = el.parentElement; at; at = at.parentElement) {
+      const heading = at.querySelector(HEADING);
+      if (heading && !heading.contains(el)) return clip(heading.innerText);
+    }
+    return '';
+  };
+  // Run before the page's own handlers, so only elements of its kind are compared: a page can have
+  // thousands of divs. One with no name is alike every other of its role, and n of N says nothing.
+  const contextOf = el => {
+    if (el.getRootNode() !== document || !nameOf(el)) return '';
+    const role = roleOf(el);
+    const me = describe(el);
+    const kind = el.hasAttribute('role') ? '[role]' : el.localName + ',[role]';
+    const alike = [...document.querySelectorAll(kind)].filter(other => other === el || (roleOf(other) === role && describe(other) === me));
+    if (alike.length < 2) return '';
+    const heading = headingOf(el);
+    const peers = heading ? alike.filter(other => headingOf(other) === heading) : alike;
+    const which = peers.length > 1 ? (peers.indexOf(el) + 1) + ' of ' + peers.length : '';
+    return [heading && 'under ' + JSON.stringify(heading), which].filter(Boolean).join(', ');
+  };
   // A field that was a password field while watched stays one when a "show password" button makes it
   // text; and some take secrets under another type. Their values never leave the page.
   const secrets = new WeakSet();
@@ -233,24 +257,34 @@ const WATCH_SCRIPT = `(() => {
     if (typeof window.__pwReplWatch !== 'function') return;
     let selector = null;
     try { selector = el ? selectorOf(el) : null; } catch {}
+    let context = '';
+    try { context = el ? contextOf(el) : ''; } catch {}
     const typed = (action === 'type' || action === 'fill') && el;
     const secret = typed && isSecret(el);
     const option = action === 'select' ? el.value : null;
-    window.__pwReplWatch(JSON.stringify({ action, target: el ? describe(el) : 'page', extra: extra || '', since: since || 0, selector, secret, value: typed && !secret ? valueOf(el) : null, option }));
+    window.__pwReplWatch(JSON.stringify({ action, target: el ? describe(el) : 'page', context, extra: extra || '', since: since || 0, selector, secret, value: typed && !secret ? valueOf(el) : null, option }));
   };
   // The element itself, not its component's host, when it is inside an open shadow root.
   const targetOf = e => (e.composedPath && e.composedPath()[0]) || e.target;
   // Enter in a form's field submits it with a click on its submit button, which is the Enter's doing:
   // recorded too, it would submit the form again when the steps run again.
   let enteredForm = null;
+  let labelled = null;
   document.addEventListener('click', e => {
     const t = targetOf(e);
     const el = t.closest ? (t.closest(INTERACTIVE) || t) : t;
     if (!el.matches || el.matches('input[type=checkbox],input[type=radio],select') || isPassword(el)) return;
     if (e.detail === 0 && enteredForm && el.form === enteredForm) return;
-    // A click on a label is passed on to its control as a click of its own, recorded as that (or as the
-    // check a checkbox's change records): recorded too, a checkbox would be toggled twice.
-    if (el.localName === 'label' && el.control) return;
+    // A click on a label is passed on to its control as a click of its own, in the same task; one of them
+    // is recorded, or a replay would toggle a checkbox twice. A label that holds its control passes it on
+    // inside what was clicked: the control's click is recorded (or the check its change records), and
+    // found by its role. A label's for= can name a control anywhere, even another card's where ids
+    // repeat: the label is what was clicked, and the passed-on click and its change are left out.
+    if (el.localName === 'label' && el.control) {
+      if (el.contains(el.control)) return;
+      labelled = el.control;
+      setTimeout(() => { labelled = null; });
+    } else if (el === labelled) return;
     send('click', el);
   }, true);
   // Typing is recorded once it pauses, not on change, so a typeahead's requests
@@ -295,7 +329,7 @@ const WATCH_SCRIPT = `(() => {
   }, true);
   document.addEventListener('change', e => {
     const el = targetOf(e);
-    if (!el.matches) return;
+    if (!el.matches || el === labelled) return;
     if (el.matches('input[type=checkbox],input[type=radio]')) return send(el.checked ? 'check' : 'uncheck', el);
     if (el.matches('select')) return send('select', el, JSON.stringify(clip(el.selectedOptions[0]?.text)));
     if (pending.has(el)) { flushTyping(el); typed.delete(el); return; }
@@ -460,7 +494,7 @@ async function startWatching(p, changes = false, live = false, values = true) {
       if (!created.on) return;
       const previous = created.events[created.events.length - 1];
       const t = Math.max(Date.now() - Math.min(Math.max(Number(since) || 0, 0), TYPING_BACKDATE_MAX), previous ? previous.t : 0);
-      const step = { seq: created.nextSeq++, t, action, target: clipText(target), extra: clipText(extra), selector: more.selector || null, secret: !!more.secret, url: more.url, loaded: !!more.loaded };
+      const step = { seq: created.nextSeq++, t, action, target: clipText(target), context: clipText(more.context || ''), extra: clipText(extra), selector: more.selector || null, secret: !!more.secret, url: more.url, loaded: !!more.loaded };
       if (typeof more.option === 'string') step.option = more.option;
       if (typeof more.value === 'string' && created.values) step.value = more.value;
       keep(created.events, step);
@@ -483,7 +517,7 @@ async function startWatching(p, changes = false, live = false, values = true) {
         try { event = JSON.parse(payload); } catch { return; }
         if (event && PAGE_ACTIONS.has(event.action)) {
           binding.record(event.action, String(event.target || ''), String(event.extra || ''), event.since,
-            { selector: typeof event.selector === 'string' ? event.selector : null, secret: !!event.secret, value: event.value, option: event.option });
+            { selector: typeof event.selector === 'string' ? event.selector : null, secret: !!event.secret, value: event.value, option: event.option, context: String(event.context || '') });
         }
       });
       // Calls are reported only to a session with Runtime on.
@@ -619,7 +653,7 @@ function requestsByStep(watch, p = state.page) {
 
 function stepLines(e, caused, note = '', withChanges = true) {
   const typed = e.secret ? ' (a password: not recorded)' : typeof e.value === 'string' ? ` ${JSON.stringify(clipText(e.value))}` : '';
-  const lines = [`${clock(e.t)} ${e.action} ${e.target}${typed}${e.extra ? ` ${e.extra}` : ''}${note}`];
+  const lines = [`${clock(e.t)} ${e.action} ${e.target}${e.context ? ` (${e.context})` : ''}${typed}${e.extra ? ` ${e.extra}` : ''}${note}`];
   const indent = ' '.repeat(clock(e.t).length + 1);
   for (const r of caused.slice(0, WATCH_REQUESTS_SHOWN)) lines.push(`${indent}#${r.id} ${r.method} ${r.status} ${r.url}`);
   if (caused.length > WATCH_REQUESTS_SHOWN) lines.push(`${indent}… ${caused.length - WATCH_REQUESTS_SHOWN} more (requests)`);
@@ -700,7 +734,7 @@ function savedCommands(watch, p) {
     if (e.action === 'submit' || changedAgain(i)) continue;
     if (routed && e.selector) lines.push(`wait ${sel(e.selector)} ${ROUTE_WAIT}`);
     routed = false;
-    lines.push(`# ${e.action} ${e.target}${e.extra ? ` ${e.extra}` : ''}`);
+    lines.push(`# ${e.action} ${e.target}${e.context ? ` (${e.context})` : ''}${e.extra ? ` ${e.extra}` : ''}`);
     if (!e.selector && !(e.action === 'press' && e.target === 'page')) { comment(e, 'no selector finds it alone: it is in a frame or a closed shadow root, or its place matches others too'); continue; }
     if (e.action === 'click' || e.action === 'check' || e.action === 'uncheck') lines.push(`${e.action} ${sel(e.selector)}`);
     else if (e.action === 'select' && typeof e.option !== 'string') comment(e, 'the option was not recorded');

package/package.json

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