@generativereality/browser-automation 0.6.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +29 -13
- package/dist/index.js +1713 -472
- package/package.json +7 -3
- package/scripts/windows-guest/README.md +40 -0
- package/scripts/windows-guest/cleanup.ps1 +5 -0
- package/scripts/windows-guest/rawpipe.mjs +16 -0
- package/scripts/windows-guest/run-in-session.ps1 +8 -0
- package/scripts/windows-guest/test.ps1 +59 -0
- package/skills/browser/SKILL.md +79 -43
- package/skills/browser/references/page-recipes.md +13 -22
- package/skills/browser/references/windows.md +7 -6
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.7.1",
|
|
4
|
+
"description": "Let many Claude Code sessions use your own signed-in Chrome at once, each in its own tab, without stealing your screen. Daemonless CLI over per-target CDP: persistent profile and extensions, no MCP server, nothing long-lived to crash.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"browser-automation": "dist/index.js"
|
|
@@ -28,7 +28,11 @@
|
|
|
28
28
|
"cdp",
|
|
29
29
|
"chrome-devtools-protocol",
|
|
30
30
|
"playwright-alternative",
|
|
31
|
-
"ai-agents"
|
|
31
|
+
"ai-agents",
|
|
32
|
+
"chrome",
|
|
33
|
+
"claude-code-plugin",
|
|
34
|
+
"parallel-agents",
|
|
35
|
+
"cli"
|
|
32
36
|
],
|
|
33
37
|
"author": "motin",
|
|
34
38
|
"license": "MIT",
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Testing the pipe broker on the Windows 11 ARM64 guest
|
|
2
|
+
|
|
3
|
+
What validated 0.7.0 on Windows (2026-10-27, Chrome 156, Node 22): the user's own Chrome
|
|
4
|
+
and a login context each on a randomly named pipe, no Chrome TCP listener, `launch`
|
|
5
|
+
refusing a Chrome still on the old port and `launch --restart` switching it over, and
|
|
6
|
+
the named pipe's ACL. The guest is the qemu VM in `~/VMs/win11` on mbp21; booting it,
|
|
7
|
+
console login and the shared-VM rules (snapshot before, revert after) are in the
|
|
8
|
+
`windows-dev` skill and in cctabs' `scripts/windows-guest/README.md`.
|
|
9
|
+
|
|
10
|
+
## ⛔ Do not point USERPROFILE at a test folder
|
|
11
|
+
|
|
12
|
+
With `USERPROFILE` changed, Chrome cannot find its app-data folder, takes the
|
|
13
|
+
`--user-data-dir` for its DEFAULT profile, and refuses DevTools on it ("DevTools remote
|
|
14
|
+
debugging requires a non-default data directory") — on the pipe AND on a port. `launch`
|
|
15
|
+
then times out, and a port Chrome never listens, so it cannot be quit cleanly. That cost
|
|
16
|
+
one full run. Isolate with `BROWSER_AUTOMATION_HOME` and `BROWSER_AUTOMATION_PROFILE`
|
|
17
|
+
instead (contexts still land in the real `~\.browser-automation\contexts`, which the
|
|
18
|
+
snapshot revert removes). `rawpipe.mjs` is the minimal check: real USERPROFILE answers,
|
|
19
|
+
an overridden one does not.
|
|
20
|
+
|
|
21
|
+
## Run
|
|
22
|
+
|
|
23
|
+
1. Stage the branch build on the Mac (no plain `npm pack`: `prepack` builds, which is fine
|
|
24
|
+
here, but the tarball's version is whatever package.json says):
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
W=<scratch>; npm run build && npm pack --ignore-scripts --pack-destination $W/stage
|
|
28
|
+
(cd $W/stage && echo '{"private":true}' > package.json && npm i --omit=dev --ignore-scripts ./generativereality-browser-automation-*.tgz)
|
|
29
|
+
tar czf $W/ba-stage.tgz -C $W/stage node_modules package.json
|
|
30
|
+
```
|
|
31
|
+
2. Copy `ba-stage.tgz` and these scripts to `C:\Users\dev\ba-test\`, unpack into `stage\`.
|
|
32
|
+
The guest's SSH shell is **PowerShell 5.1: no `&&`**, use `;`.
|
|
33
|
+
3. A console session must be logged in (`query user` shows `console … Active`): Chrome is
|
|
34
|
+
started in the desktop session by `run-in-session.ps1` (a one-off scheduled task).
|
|
35
|
+
4. `powershell -ExecutionPolicy Bypass -File run-in-session.ps1`, then wait for `DONE` in
|
|
36
|
+
`result.log`.
|
|
37
|
+
5. `cleanup.ps1` stops every process whose command line mentions `ba-test` and nothing else.
|
|
38
|
+
|
|
39
|
+
`Get-Acl` cannot read a named pipe's ACL (error 87); `test.ps1` reads it off a
|
|
40
|
+
`NamedPipeClientStream` connection instead.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
# Stop only what the ba-test run started: processes whose command line mentions ba-test.
|
|
2
|
+
$mine = Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -and $_.CommandLine -match 'ba-test' -and $_.ProcessId -ne $PID -and $_.CommandLine -notmatch 'cleanup\.ps1' }
|
|
3
|
+
foreach ($p in $mine) { "stop $($p.ProcessId) $($p.Name)"; Stop-Process -Id $p.ProcessId -Force -ErrorAction SilentlyContinue }
|
|
4
|
+
Start-Sleep 2
|
|
5
|
+
"left: " + @(Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'ba-test' -and $_.CommandLine -notmatch 'cleanup\.ps1' }).Count
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
// Minimal: does Chrome on Windows answer on --remote-debugging-pipe (fds 3/4)?
|
|
2
|
+
// node rawpipe.mjs <dir-for-a-temp-profile>. Run it once as is, and once with USERPROFILE
|
|
3
|
+
// pointed elsewhere to see Chrome refuse DevTools (see README).
|
|
4
|
+
import { spawn } from 'node:child_process'
|
|
5
|
+
import { mkdtempSync } from 'node:fs'
|
|
6
|
+
import { join } from 'node:path'
|
|
7
|
+
import { tmpdir } from 'node:os'
|
|
8
|
+
const chrome = process.env.LOCALAPPDATA + '\\Google\\Chrome\\Application\\chrome.exe'
|
|
9
|
+
const dir = mkdtempSync(join(process.argv[2] || tmpdir(), 'rawpipe-'))
|
|
10
|
+
const c = spawn(chrome, ['--remote-debugging-pipe', `--user-data-dir=${dir}`, '--headless=new', '--no-first-run', 'about:blank'], { stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'] })
|
|
11
|
+
let err = ''
|
|
12
|
+
c.stderr.on('data', (d) => { err += d })
|
|
13
|
+
c.stdout.on('data', () => {})
|
|
14
|
+
c.stdio[4].on('data', (d) => { console.log('REPLY', String(d).replace(/\0/g, '').slice(0, 160)); c.kill(); process.exit(0) })
|
|
15
|
+
setTimeout(() => c.stdio[3].write(JSON.stringify({ id: 1, method: 'Browser.getVersion' }) + '\0'), 3000)
|
|
16
|
+
setTimeout(() => { console.log('NO REPLY in 15s; stderr:', err.split('\n').slice(0, 5).join(' | ')); c.kill(); process.exit(1) }, 15000)
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Run test.ps1 in the logged-in desktop session (a GUI started over SSH is invisible).
|
|
2
|
+
$ProgressPreference = 'SilentlyContinue'
|
|
3
|
+
$name = 'ba-pipe-test'
|
|
4
|
+
$a = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument '-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File C:\Users\dev\ba-test\test.ps1'
|
|
5
|
+
$p = New-ScheduledTaskPrincipal -UserId 'dev' -LogonType Interactive
|
|
6
|
+
Register-ScheduledTask -TaskName $name -Action $a -Principal $p -Force | Out-Null
|
|
7
|
+
try { Start-ScheduledTask -TaskName $name } finally { Start-Sleep 2; Unregister-ScheduledTask -TaskName $name -Confirm:$false }
|
|
8
|
+
'started'
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# browser-automation pipe broker on Windows, run in the desktop session (scheduled task).
|
|
2
|
+
# The user's own Chrome lives under C:\Users\dev\ba-test (BROWSER_AUTOMATION_HOME, _PROFILE,
|
|
3
|
+
# a port of its own). USERPROFILE stays real: pointed elsewhere, Chrome refuses DevTools.
|
|
4
|
+
$ErrorActionPreference = 'Continue'
|
|
5
|
+
$T = 'C:\Users\dev\ba-test'
|
|
6
|
+
$log = "$T\result.log"
|
|
7
|
+
$env:BROWSER_AUTOMATION_HOME = "$T\home\.browser-automation"; $env:BROWSER_AUTOMATION_PROFILE = "$T\profile"
|
|
8
|
+
$env:BROWSER_AUTOMATION_PORT = '40123'; $env:NO_UPDATE_NOTIFIER = '1'; $env:NO_COLOR = '1'
|
|
9
|
+
Remove-Item Env:BROWSER_AUTOMATION_CDP -ErrorAction SilentlyContinue
|
|
10
|
+
Remove-Item Env:BAC_CONTEXT -ErrorAction SilentlyContinue
|
|
11
|
+
New-Item -ItemType Directory -Force "$T\home" | Out-Null
|
|
12
|
+
$node = 'C:\Users\dev\node\node.exe'
|
|
13
|
+
$ba = "$T\stage\node_modules\@generativereality\browser-automation\dist\index.js"
|
|
14
|
+
function BA { param([Parameter(ValueFromRemainingArguments = $true)]$a) "`n>>> ba $($a -join ' ')"; & $node $ba @a 2>&1 | ForEach-Object { "$_" }; "<<< exit $LASTEXITCODE" }
|
|
15
|
+
function ChromeListens {
|
|
16
|
+
$ids = @((Get-Process chrome -ErrorAction SilentlyContinue).Id)
|
|
17
|
+
$l = Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue | Where-Object { $ids -contains $_.OwningProcess }
|
|
18
|
+
"chrome processes: $($ids.Count); chrome TCP listeners: [" + (($l | ForEach-Object { "$($_.LocalAddress):$($_.LocalPort)" }) -join ', ') + "]"
|
|
19
|
+
}
|
|
20
|
+
function PipeAcl($stateFile) {
|
|
21
|
+
$s = (Get-Content $stateFile | ConvertFrom-Json).socket; "pipe: $s"
|
|
22
|
+
try {
|
|
23
|
+
$c = New-Object System.IO.Pipes.NamedPipeClientStream('.', $s.Substring('\\.\pipe\'.Length), [System.IO.Pipes.PipeDirection]::InOut)
|
|
24
|
+
$c.Connect(3000)
|
|
25
|
+
$c.GetAccessControl().Access | ForEach-Object { " $($_.IdentityReference) $($_.AccessControlType) $($_.PipeAccessRights)" }
|
|
26
|
+
$c.Dispose()
|
|
27
|
+
} catch { " acl: $_" }
|
|
28
|
+
}
|
|
29
|
+
& {
|
|
30
|
+
"=== 1. an old Chrome on the port, same profile"
|
|
31
|
+
$chrome = "$env:LOCALAPPDATA\Google\Chrome\Application\chrome.exe"
|
|
32
|
+
New-Item -ItemType Directory -Force "$T\profile" | Out-Null
|
|
33
|
+
Start-Process $chrome -ArgumentList "--remote-debugging-port=40123", "--user-data-dir=$T\profile", "--no-first-run", "--no-default-browser-check", "about:blank" | Out-Null
|
|
34
|
+
Start-Sleep 8
|
|
35
|
+
ChromeListens
|
|
36
|
+
BA launch
|
|
37
|
+
BA launch --restart
|
|
38
|
+
ChromeListens
|
|
39
|
+
"=== 2. own Chrome on the pipe"
|
|
40
|
+
Get-Content "$T\home\.browser-automation\broker.json"
|
|
41
|
+
BA launch --status
|
|
42
|
+
BA new -s t1 "data:text/html,<h1>pipe-ok</h1>"
|
|
43
|
+
BA eval -s t1 "document.querySelector('h1').textContent"
|
|
44
|
+
BA doctor
|
|
45
|
+
"=== 3. a login context"
|
|
46
|
+
BA new -s c1 --context bapipe "data:text/html,<h1>context-ok</h1>"
|
|
47
|
+
BA eval -s c1 "document.querySelector('h1').textContent"
|
|
48
|
+
Get-Content "C:\Users\dev\.browser-automation\contexts\bapipe\broker.json"
|
|
49
|
+
BA context
|
|
50
|
+
ChromeListens
|
|
51
|
+
"=== 4. pipe ACLs"
|
|
52
|
+
PipeAcl "$T\home\.browser-automation\broker.json"
|
|
53
|
+
PipeAcl "C:\Users\dev\.browser-automation\contexts\bapipe\broker.json"
|
|
54
|
+
"=== 5. stop the context"
|
|
55
|
+
BA context stop bapipe
|
|
56
|
+
Start-Sleep 6
|
|
57
|
+
BA context
|
|
58
|
+
"DONE"
|
|
59
|
+
} *>> $log
|
package/skills/browser/SKILL.md
CHANGED
|
@@ -14,14 +14,19 @@ file under `~/.browser-automation/sessions/`.
|
|
|
14
14
|
|
|
15
15
|
## The model — read this first
|
|
16
16
|
|
|
17
|
-
- **One shared headed Chrome per USER**
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
-
|
|
24
|
-
|
|
17
|
+
- **One shared headed Chrome per USER** with a persistent profile. Cookies,
|
|
18
|
+
logins, and **browser extensions (password managers, etc.) all persist** across
|
|
19
|
+
runs and across Claude Code restarts. The user can watch and complete
|
|
20
|
+
interactive auth in the same window.
|
|
21
|
+
- **No debugging port.** Chrome runs with `--remote-debugging-pipe`, held by a
|
|
22
|
+
small broker that `launch` starts, and the CLI reaches it through
|
|
23
|
+
`~/.browser-automation/cdp.sock` (macOS, Linux) or a randomly named pipe
|
|
24
|
+
(Windows) — only this OS user can open either. A debugging port has no
|
|
25
|
+
authentication, so with one open any program on the computer could drive the
|
|
26
|
+
signed-in browser. Login contexts get a broker each. Only `BROWSER_AUTOMATION_CDP` means a port.
|
|
27
|
+
- **Per-target CDP, not whole-browser.** Each command opens its own connection
|
|
28
|
+
bound to a single tab (over the socket, a CDP session the broker attaches for
|
|
29
|
+
that command and detaches after it). It never does Playwright-style "connect to the whole
|
|
25
30
|
browser and enumerate every target" — so a stuck iframe/worker or a pile of
|
|
26
31
|
open tabs can never wedge it (the failure that made `playwright-cli` time out).
|
|
27
32
|
- **Address any tab on demand.** Every page command picks its tab three ways
|
|
@@ -84,11 +89,10 @@ file under `~/.browser-automation/sessions/`.
|
|
|
84
89
|
attribute. Because each invocation is a fresh process, **re-snapshot after any
|
|
85
90
|
action that changes the DOM** — refs from an old snapshot go stale, exactly
|
|
86
91
|
like Playwright refs.
|
|
87
|
-
- **Clicks/fills are JS-dispatched** (
|
|
88
|
-
`input`/`change`
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
them (see Gotchas).
|
|
92
|
+
- **Clicks/fills are JS-dispatched** (a real click's pointer + mouse events, then
|
|
93
|
+
`element.click()`; native value setter + `input`/`change`). This works on
|
|
94
|
+
background tabs without taking focus, and drives Radix / headless-UI controls.
|
|
95
|
+
Trade-off: not `isTrusted`, so a few anti-bot / payment flows reject them (see Gotchas).
|
|
92
96
|
|
|
93
97
|
## Setup (per machine)
|
|
94
98
|
|
|
@@ -113,8 +117,15 @@ that it keeps all three while losing the ability to give any new tab a
|
|
|
113
117
|
**renderer** (see Gotchas, and [`references/renderer-health.md`](references/renderer-health.md)). Older CLIs printed `nothing to do.` in exactly that
|
|
114
118
|
state — **if your `launch` ends without a `Renderer capacity:` line, you are on
|
|
115
119
|
one of those; run `doctor`, which is the same probe.** Override the profile path
|
|
116
|
-
with `BROWSER_AUTOMATION_PROFILE
|
|
117
|
-
|
|
120
|
+
with `BROWSER_AUTOMATION_PROFILE=...`. `BROWSER_AUTOMATION_CDP=http://localhost:PORT`
|
|
121
|
+
drives a browser somebody else started on a port instead — which exposes it to
|
|
122
|
+
everything on the computer, so only for a browser that holds no logins.
|
|
123
|
+
|
|
124
|
+
**Moving off the port.** If this user's browser from an older CLI is still on the
|
|
125
|
+
port, `launch` stops and says so: `browser-automation launch --restart` quits it
|
|
126
|
+
(closing its tabs; logins are kept, and the profile moves out of Chrome's folder
|
|
127
|
+
as below) and starts it on the pipe. A browser on the port with a *different*
|
|
128
|
+
profile is left alone and only named.
|
|
118
129
|
|
|
119
130
|
**The profile lives in `~/.browser-automation/chrome-profile`** (`browser-automation
|
|
120
131
|
profile` prints it). Older CLIs kept it inside Chrome's own folder,
|
|
@@ -163,6 +174,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
163
174
|
| Adopt an open tab into a session | `browser-automation bind -s bank -m nordnet` |
|
|
164
175
|
| List interactive elements (refs) | `browser-automation snapshot -m op.fi` |
|
|
165
176
|
| Click by ref | `browser-automation click -m op.fi e7` |
|
|
177
|
+
| Press a key on a ref (listbox, menu, cmdk list) | `browser-automation key -s app e7 Enter` |
|
|
166
178
|
| Type into a field by ref | `browser-automation fill -s work e3 "value" [--submit]` |
|
|
167
179
|
| Read page text (or a selector) | `browser-automation read -m op.fi ['.balance']` |
|
|
168
180
|
| Evaluate JS in the tab (escape hatch) | `browser-automation eval -m op.fi 'document.title'` |
|
|
@@ -217,36 +229,56 @@ browser-automation read -s cf # later runs: already authenticate
|
|
|
217
229
|
|
|
218
230
|
There's no `state-save`/`state-load` to manage — the profile *is* the auth store.
|
|
219
231
|
|
|
220
|
-
### A second account
|
|
232
|
+
### A second account, or a project of its own — `--context <name>`
|
|
221
233
|
|
|
222
234
|
The profile holds ONE login per site. For a second account beside it (two
|
|
223
|
-
Cloudflare dashboards,
|
|
224
|
-
|
|
225
|
-
|
|
235
|
+
Cloudflare dashboards), or to keep a whole project's logins apart from the
|
|
236
|
+
user's (a client's Google Workspace, AWS), open the session in a named **login
|
|
237
|
+
context**: a separate Chrome with its own profile, pipe and window, started on
|
|
238
|
+
demand. The user's own Chrome is not touched.
|
|
226
239
|
|
|
227
240
|
```bash
|
|
228
241
|
browser-automation new -s cf2 --context cloudflare-2 https://dash.cloudflare.com
|
|
229
|
-
# FIRST time only:
|
|
230
|
-
# signs out of the first account and signs in to the other one
|
|
242
|
+
# FIRST time only: the user signs in to the account in the new (coloured) window
|
|
231
243
|
browser-automation read -s cf2 # follows the session's context — no flag
|
|
232
244
|
```
|
|
233
245
|
|
|
246
|
+
- **A project uses one context for all its sessions: set `BAC_CONTEXT`** in the
|
|
247
|
+
env of the project's Claude settings — e.g. `"env": {"BAC_CONTEXT": "gapminder"}`
|
|
248
|
+
in `.claude/settings.json`, or in a separate account's `$CLAUDE_CONFIG_DIR/settings.json`.
|
|
249
|
+
Then every NEW session, `-m`/`-t`, `list` and `doctor` use that Chrome with no
|
|
250
|
+
flag, and nothing of the project lands in the user's main profile. ⛔ If a
|
|
251
|
+
project should be separate and `BAC_CONTEXT` is not set, ask before working in
|
|
252
|
+
the main profile — a logout or sign-in there is the user's real account.
|
|
253
|
+
|
|
234
254
|
- **A session remembers its context**: later commands on `-s cf2` go to that
|
|
235
255
|
Chrome without `--context`. A session can't change context; use another `-s`.
|
|
236
256
|
- **It is a real profile** (`~/.browser-automation/contexts/<name>/chrome-profile`):
|
|
237
257
|
logins and extensions persist across restarts, like the main profile.
|
|
238
|
-
- **
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
profile
|
|
258
|
+
- **How a new context starts** — chosen once, when it is first made:
|
|
259
|
+
|
|
260
|
+
| | extensions (password manager…) | site logins, cookies | Chrome's own Google sign-in |
|
|
261
|
+
|---|---|---|---|
|
|
262
|
+
| default | ✅ copied, still signed in | ❌ none | ❌ signed out |
|
|
263
|
+
| `--full-copy` | ✅ | ✅ every one, personal too | ✅ — may become the DEFAULT Google account |
|
|
264
|
+
| `--empty-profile` | ❌ | ❌ | ❌ |
|
|
265
|
+
|
|
266
|
+
The source is the AUTOMATION profile, never the user's ordinary Chrome. With
|
|
267
|
+
`--full-copy`, Google pages pick the copied personal account and `?authuser=`
|
|
268
|
+
does not move them: open
|
|
269
|
+
`https://accounts.google.com/AccountChooser?Email=<work address>&continue=<url>`.
|
|
270
|
+
- **Each context's window has its own colour**, and its profile is named after
|
|
271
|
+
it, so the user can tell the Chromes apart (`context` names the colours).
|
|
272
|
+
Contexts made before 0.6.1 get theirs at their next start.
|
|
245
273
|
- **Starting it takes the screen once** — a cold Chrome launch comes to the
|
|
246
|
-
front (issue #25)
|
|
247
|
-
|
|
274
|
+
front (issue #25), and keys the user is typing can land in it. `goto`/`new`
|
|
275
|
+
start it when it isn't running; `context stop <name>` quits it; `context
|
|
276
|
+
forget <name> [--delete-profile]` removes it.
|
|
277
|
+
- **`context` lists every Chrome** — the user's own and each context's — with
|
|
278
|
+
port, pid, colour and sessions. `list` says which Chrome its tabs are in.
|
|
248
279
|
- `-m`/`-t`, `list`, `doctor`, `launch` act on the user's Chrome unless given
|
|
249
|
-
`--context <name>` (or `BAC_CONTEXT`).
|
|
280
|
+
`--context <name>` (or `BAC_CONTEXT`). A session always stays in the Chrome
|
|
281
|
+
it was opened in; only an explicit `--context` that disagrees is refused.
|
|
250
282
|
- ⛔ **Not a second Chrome profile in the main Chrome, not an incognito-style
|
|
251
283
|
CDP context.** A second profile becomes Chrome's default while its window is
|
|
252
284
|
open — every other session's new tab opens in it, logged out. A CDP
|
|
@@ -264,23 +296,27 @@ browser-automation read -s cf2 # follows the session's context
|
|
|
264
296
|
- **Refs go stale after any DOM change**, not just navigation. Snapshot → use
|
|
265
297
|
those refs for one action → re-snapshot. "ref not found" means re-snapshot.
|
|
266
298
|
- **`isTrusted` / synthetic events.** Clicks and fills are JS-dispatched by
|
|
267
|
-
default
|
|
268
|
-
|
|
299
|
+
default and need no focus. **Radix and headless-UI triggers, menu items and popovers
|
|
300
|
+
work with a plain `click`** (a Radix Select option is picked by keyboard; the CLI prints
|
|
301
|
+
`(keyboard)`); for keyboard-driven lists use `key [ref] Enter` / `ArrowDown` / `Escape`.
|
|
302
|
+
Only widgets that check `isTrusted` ignore this. **For those clicks, pass `--trusted`** — it dispatches a real CDP `Input.dispatchMouseEvent`, makes the
|
|
269
303
|
renderer treat the tab as focused+visible (CDP input no-ops on a backgrounded
|
|
270
304
|
tab; the person's window keeps showing its own tab) and waits for the element to be actionable (stable position +
|
|
271
305
|
unoccluded hit-test) before pressing. For fills, pass `--native` to drive
|
|
272
306
|
character insertion through CDP `Input.insertText`, which fires real
|
|
273
307
|
`beforeinput`/`input` events.
|
|
274
|
-
|
|
275
|
-
the
|
|
276
|
-
|
|
277
|
-
cases: LinkedIn artdeco dropdown
|
|
278
|
-
|
|
308
|
+
`--trusted` brings the tab's renderer to the foreground, so use it only when
|
|
309
|
+
the default click "succeeds" but nothing happens. The CLI prints `✔ clicked e7`
|
|
310
|
+
on a dispatched event regardless of whether the widget reacted, so a silent
|
|
311
|
+
no-op is the signature, not an error. Canonical cases: LinkedIn artdeco dropdown
|
|
312
|
+
items, and **framework-state form widgets whose inputs are `readonly` with
|
|
279
313
|
no `name`** (Viking Line's booking selectors — the visible fields are display
|
|
280
314
|
shells; the real state lives in the framework, so `fill` and DOM value-setting
|
|
281
315
|
do nothing at all).
|
|
282
|
-
- **There is NO way to send real keystrokes
|
|
283
|
-
`keydown`,
|
|
316
|
+
- **There is NO way to send real (trusted) keystrokes.** `key` dispatches an untrusted
|
|
317
|
+
`keydown`/`keyup`, enough for listboxes, menus and cmdk lists, but it types nothing into a
|
|
318
|
+
text field. `fill --native` never fires `keydown`, so a combobox that filters on keystrokes
|
|
319
|
+
stays empty. ⛔ **Do not hand-roll a
|
|
284
320
|
raw-CDP trusted click** — `--trusted` already waits for actionability; check
|
|
285
321
|
`browser-automation click --help` before building anything. A form can also swallow a
|
|
286
322
|
dispatched click and fall through to a native POST (a raw `{"message":"Not Found"}` page,
|
|
@@ -364,7 +400,7 @@ browser-automation read -s cf2 # follows the session's context
|
|
|
364
400
|
on the tab first, and capture the **viewport**, not `--full` (with
|
|
365
401
|
`captureBeyondViewport` they composite at their pre-capture width, narrow and
|
|
366
402
|
clipped). A blank region on a page with no cross-origin iframes is a real finding.
|
|
367
|
-
- **Controls that ignore `click`** (
|
|
403
|
+
- **Controls that ignore `click`** (`click` vs `--trusted`), hidden
|
|
368
404
|
dialogs, stalled infinite scroll, React composers and GitHub image attachments:
|
|
369
405
|
**[`references/page-recipes.md`](references/page-recipes.md)**.
|
|
370
406
|
- **This needs the operator's machine, awake.** The shared headed Chrome and its
|
|
@@ -449,8 +485,8 @@ code lives, how to validate with `node dist/index.js`, and the PR steps:
|
|
|
449
485
|
- **The Chrome on the port is on a profile you did not expect** → someone worked
|
|
450
486
|
around a launch failure by hand (`BROWSER_AUTOMATION_PROFILE`, a typed
|
|
451
487
|
`--user-data-dir`), and that instance has few or no logins. Read the live
|
|
452
|
-
browser's profile before trusting a drive:
|
|
453
|
-
`
|
|
488
|
+
browser's profile before trusting a drive: the `profile` field of
|
|
489
|
+
`~/.browser-automation/broker.json` (a context's is in `contexts/<name>/`). The
|
|
454
490
|
shared profile is `~/.browser-automation/chrome-profile`. ⚠️ Do not just kill it;
|
|
455
491
|
it may be the operator's live browser. Ask, then `launch`.
|
|
456
492
|
- **Chrome was restarted** → nothing to do; the next `goto` recreates the
|
|
@@ -10,28 +10,19 @@ clicks and needed `click --trusted`, while a link-styled **Withdraw** anchor was
|
|
|
10
10
|
reverse: `Input.dispatchMouseEvent` at its centre silently did nothing, and `el.click()`
|
|
11
11
|
opened the confirm dialog every time. Try both before concluding a control is broken.
|
|
12
12
|
|
|
13
|
-
## Radix menus open on `pointerdown`
|
|
14
|
-
|
|
15
|
-
A Radix `DropdownMenu`
|
|
16
|
-
`
|
|
17
|
-
`
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
b.click();
|
|
27
|
-
return [...document.querySelectorAll("[role=menuitem]")].map(x => x.textContent.trim()).join(" | ");
|
|
28
|
-
})()'
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
⚠️ **Do not fire `click` and then this sequence.** Two activations toggle the menu open
|
|
32
|
-
and shut again, which looks identical to it never opening. Once it is open, the menu
|
|
33
|
-
items and dialog buttons take an ordinary `click [ref]` after a re-snapshot; only the
|
|
34
|
-
trigger needs pointer events.
|
|
13
|
+
## Radix menus open on `pointerdown`: a plain `click` handles it
|
|
14
|
+
|
|
15
|
+
A Radix `DropdownMenu` trigger, a row "⋯" trigger or a Select trigger acts on
|
|
16
|
+
`pointerdown`, not on `click`. The default `click` sends `pointerdown` and the rest of a
|
|
17
|
+
real click's events before `click`, so it opens them without taking focus, and the items
|
|
18
|
+
take a plain `click` after a re-snapshot. A Radix Select option is picked by keyboard
|
|
19
|
+
(focus + Enter), because Select ignores a `pointerup` that comes right after the
|
|
20
|
+
`pointerdown` that opened it; `click` does this by itself and prints `(keyboard)`.
|
|
21
|
+
|
|
22
|
+
Older CLIs sent only `element.click()`, so the trigger stayed shut and the snapshot had no
|
|
23
|
+
`[role=menuitem]` in it. ⚠️ With those, never send `click` and then a hand-rolled pointer
|
|
24
|
+
sequence: two activations toggle the menu open and shut again, which looks identical to
|
|
25
|
+
it never opening.
|
|
35
26
|
|
|
36
27
|
## Dialogs: filter by visibility, not by role
|
|
37
28
|
|
|
@@ -21,16 +21,17 @@ With **zero open tabs**, `list` prints the full saved-session list — every row
|
|
|
21
21
|
describes a saved session whose tab is gone, not the browser's health. The tell is the
|
|
22
22
|
`# open tabs (0)` line at the **end** of the output, easy to miss under a long listing.
|
|
23
23
|
|
|
24
|
-
⭐ **Ask
|
|
24
|
+
⭐ **Ask `launch --status` instead.** It answers in one call (exit 0 = up):
|
|
25
25
|
|
|
26
26
|
```powershell
|
|
27
|
-
|
|
27
|
+
& "$env:APPDATA\npm\browser-automation.cmd" launch --status # Chrome is up on the pipe (\\.\pipe\browser-automation-…)
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
A stale session list plus a
|
|
31
|
-
(`new -s [name] [url]`), not relaunch the browser.
|
|
32
|
-
on
|
|
33
|
-
|
|
30
|
+
A stale session list plus a browser that is up means **open a tab**
|
|
31
|
+
(`new -s [name] [url]`), not relaunch the browser. Since 0.7.0 Chrome on Windows
|
|
32
|
+
listens on no port: `http://127.0.0.1:9223/json/version` answering means a Chrome
|
|
33
|
+
from before the move, which anything on the computer can drive —
|
|
34
|
+
`launch --restart` switches it over.
|
|
34
35
|
|
|
35
36
|
## `|`, `&` and parentheses break through the `.cmd` shim
|
|
36
37
|
|