@generativereality/browser-automation 0.4.9 → 0.4.11
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 +6 -0
- package/dist/index.js +178 -17
- package/package.json +4 -3
- package/scripts/launch-chrome.sh +15 -3
- package/skills/browser/SKILL.md +80 -5
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "browser-automation",
|
|
3
3
|
"description": "Daemonless, per-tab-isolated browser automation for Claude Code via the `browser-automation` CLI. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
4
|
-
"version": "0.4.
|
|
4
|
+
"version": "0.4.11",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "generativereality"
|
|
7
7
|
},
|
package/README.md
CHANGED
|
@@ -122,6 +122,12 @@ same one-action-per-snapshot rule as Playwright refs.
|
|
|
122
122
|
|
|
123
123
|
## Notes & limits
|
|
124
124
|
|
|
125
|
+
- **Values are plain POSIX argv.** A positional such as `fill`'s value may contain
|
|
126
|
+
anything — `--force`, a markdown `---` rule, newlines — as long as the shell
|
|
127
|
+
hands it over as one element (quote it). Only an element that *begins* with a
|
|
128
|
+
dash and looks like an option (`--force`, `-5`) is read as one; to pass such a
|
|
129
|
+
value literally, end option parsing with `--`: `fill -t <id> -- e3 "--force"`.
|
|
130
|
+
An unknown option is an error that names the offending element.
|
|
125
131
|
- Interactions are **JS-dispatched** (`element.click()`, native value setter +
|
|
126
132
|
`input`/`change`), which works on background tabs (native CDP mouse events do
|
|
127
133
|
not reliably reach a non-foreground tab in headed Chrome). Synthetic events are
|
package/dist/index.js
CHANGED
|
@@ -9,7 +9,7 @@ import { execFileSync, spawnSync } from "node:child_process";
|
|
|
9
9
|
import { fileURLToPath } from "node:url";
|
|
10
10
|
//#region package.json
|
|
11
11
|
var name = "@generativereality/browser-automation";
|
|
12
|
-
var version = "0.4.
|
|
12
|
+
var version = "0.4.11";
|
|
13
13
|
var description = "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.";
|
|
14
14
|
var package_default = {
|
|
15
15
|
name,
|
|
@@ -27,8 +27,9 @@ var package_default = {
|
|
|
27
27
|
"dev": "bun run ./src/index.ts",
|
|
28
28
|
"build": "tsdown",
|
|
29
29
|
"typecheck": "tsc --noEmit",
|
|
30
|
-
"check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build",
|
|
31
|
-
"
|
|
30
|
+
"check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
|
|
31
|
+
"test": "node --test \"test/**/*.test.mjs\"",
|
|
32
|
+
"release": "echo 'Releases publish from CI, not here. Bump package.json + .claude-plugin/plugin.json, commit onto master, then: git tag vX.Y.Z && git push origin vX.Y.Z — then approve the gated job in GitHub Actions. `npm publish` from a laptop 404s (granular token). See .github/workflows/release.yml.' >&2; exit 1",
|
|
32
33
|
"sync-plugin": "bash scripts/sync-plugin.sh",
|
|
33
34
|
"prepack": "npm run build"
|
|
34
35
|
},
|
|
@@ -66,6 +67,117 @@ var package_default = {
|
|
|
66
67
|
}
|
|
67
68
|
};
|
|
68
69
|
//#endregion
|
|
70
|
+
//#region src/core/argv.ts
|
|
71
|
+
var UsageError = class extends Error {
|
|
72
|
+
constructor(message) {
|
|
73
|
+
super(message);
|
|
74
|
+
this.name = "UsageError";
|
|
75
|
+
}
|
|
76
|
+
};
|
|
77
|
+
const COMMON = {
|
|
78
|
+
help: {
|
|
79
|
+
type: "boolean",
|
|
80
|
+
short: "h"
|
|
81
|
+
},
|
|
82
|
+
version: {
|
|
83
|
+
type: "boolean",
|
|
84
|
+
short: "v"
|
|
85
|
+
}
|
|
86
|
+
};
|
|
87
|
+
const PLACEHOLDER_PREFIX = "\0positional:";
|
|
88
|
+
function placeholder(i) {
|
|
89
|
+
return `${PLACEHOLDER_PREFIX}${i}`;
|
|
90
|
+
}
|
|
91
|
+
/** Map gunshi's positionals (which contain placeholders) back to the real values. */
|
|
92
|
+
function restorePositionals(positionals, real) {
|
|
93
|
+
return positionals.map((p) => {
|
|
94
|
+
if (!p.startsWith(PLACEHOLDER_PREFIX)) return p;
|
|
95
|
+
return real[Number(p.slice(12))] ?? p;
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
function isOptionShaped(arg) {
|
|
99
|
+
return /^--?[A-Za-z0-9]/.test(arg);
|
|
100
|
+
}
|
|
101
|
+
function separatorHint(sub, positionals, token) {
|
|
102
|
+
return `To pass it as a value, put '--' before the positionals: browser-automation ${sub} [options] -- ${[...positionals, token].map((p) => `'${p}'`).join(" ")}`;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Canonicalise everything after the subcommand.
|
|
106
|
+
*
|
|
107
|
+
* @param sub the subcommand name (argv[0])
|
|
108
|
+
* @param rest argv after the subcommand
|
|
109
|
+
* @param schema the command's declared args (gunshi's `args` table)
|
|
110
|
+
*/
|
|
111
|
+
function canonicalize(sub, rest, schema) {
|
|
112
|
+
const specs = {
|
|
113
|
+
...COMMON,
|
|
114
|
+
...schema
|
|
115
|
+
};
|
|
116
|
+
const byShort = /* @__PURE__ */ new Map();
|
|
117
|
+
for (const [name, spec] of Object.entries(specs)) if (spec.short) byShort.set(spec.short, name);
|
|
118
|
+
const options = [];
|
|
119
|
+
const positionals = [];
|
|
120
|
+
const unknown = (token) => {
|
|
121
|
+
throw new UsageError(`'${token}' is not an option of '${sub}'. ${separatorHint(sub, positionals, token)}`);
|
|
122
|
+
};
|
|
123
|
+
const takesValue = (name) => specs[name].type !== "boolean";
|
|
124
|
+
let i = 0;
|
|
125
|
+
let terminated = false;
|
|
126
|
+
while (i < rest.length) {
|
|
127
|
+
const arg = rest[i++];
|
|
128
|
+
if (!terminated && arg === "--") {
|
|
129
|
+
terminated = true;
|
|
130
|
+
continue;
|
|
131
|
+
}
|
|
132
|
+
if (terminated || !isOptionShaped(arg)) {
|
|
133
|
+
positionals.push(arg);
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
if (arg.startsWith("--")) {
|
|
137
|
+
const eq = arg.indexOf("=");
|
|
138
|
+
const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
|
|
139
|
+
if (!(name in specs) || specs[name].type === "positional") return unknown(arg);
|
|
140
|
+
if (!takesValue(name)) {
|
|
141
|
+
if (eq !== -1) throw new UsageError(`'--${name}' is a flag and takes no value (got '${arg}')`);
|
|
142
|
+
options.push(`--${name}`);
|
|
143
|
+
continue;
|
|
144
|
+
}
|
|
145
|
+
let value;
|
|
146
|
+
if (eq !== -1) value = arg.slice(eq + 1);
|
|
147
|
+
else if (i < rest.length) value = rest[i++];
|
|
148
|
+
else throw new UsageError(`'${arg}' needs a value`);
|
|
149
|
+
options.push(`--${name}=${value}`);
|
|
150
|
+
continue;
|
|
151
|
+
}
|
|
152
|
+
let j = 1;
|
|
153
|
+
while (j < arg.length) {
|
|
154
|
+
const short = arg[j++];
|
|
155
|
+
const name = byShort.get(short);
|
|
156
|
+
if (!name) return unknown(`-${short}`);
|
|
157
|
+
if (!takesValue(name)) {
|
|
158
|
+
options.push(`--${name}`);
|
|
159
|
+
continue;
|
|
160
|
+
}
|
|
161
|
+
let remainder = arg.slice(j);
|
|
162
|
+
if (remainder.startsWith("=")) remainder = remainder.slice(1);
|
|
163
|
+
let value;
|
|
164
|
+
if (remainder.length > 0) value = remainder;
|
|
165
|
+
else if (i < rest.length) value = rest[i++];
|
|
166
|
+
else throw new UsageError(`'-${short}' needs a value`);
|
|
167
|
+
options.push(`--${name}=${value}`);
|
|
168
|
+
break;
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
return {
|
|
172
|
+
argv: [
|
|
173
|
+
sub,
|
|
174
|
+
...options,
|
|
175
|
+
...positionals.map((_, k) => placeholder(k))
|
|
176
|
+
],
|
|
177
|
+
positionals
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
//#endregion
|
|
69
181
|
//#region src/core/session.ts
|
|
70
182
|
const DIR = join(homedir(), ".browser-automation", "sessions");
|
|
71
183
|
function file(name) {
|
|
@@ -249,22 +361,32 @@ async function forceForeground(s) {
|
|
|
249
361
|
await s.send("Page.setWebLifecycleState", { state: "active" }).catch(() => {});
|
|
250
362
|
}
|
|
251
363
|
/** Run `fn` against the browser-level endpoint (Target.* commands), then close. */
|
|
252
|
-
async function withBrowser(fn) {
|
|
253
|
-
const s = await connect(await browserWsUrl());
|
|
364
|
+
async function withBrowser(fn, timeout) {
|
|
365
|
+
const s = await connect(await browserWsUrl(), timeout === void 0 ? void 0 : { timeout });
|
|
254
366
|
try {
|
|
255
367
|
return await fn(s);
|
|
256
368
|
} finally {
|
|
257
369
|
s.close();
|
|
258
370
|
}
|
|
259
371
|
}
|
|
260
|
-
/**
|
|
261
|
-
|
|
372
|
+
/**
|
|
373
|
+
* Create a new tab in the BACKGROUND (never steals focus) -> returns targetId.
|
|
374
|
+
*
|
|
375
|
+
* `timeout` exists for the health probe. On a browser that has lost the ability
|
|
376
|
+
* to make renderers, `Target.createTarget` itself can hang rather than fail, so
|
|
377
|
+
* a caller that means to spend ~100ms deciding whether the browser works would
|
|
378
|
+
* otherwise sit on the default 30s — measured 2026-09-07, when this put a 30s
|
|
379
|
+
* stall in front of every `launch` on a wedged Chrome. Ordinary callers pass
|
|
380
|
+
* nothing and keep the generous default, which is right for them: a real tab
|
|
381
|
+
* opening slowly should still open.
|
|
382
|
+
*/
|
|
383
|
+
async function createTab(url = "about:blank", { timeout } = {}) {
|
|
262
384
|
return withBrowser(async (s) => {
|
|
263
385
|
return (await s.send("Target.createTarget", {
|
|
264
386
|
url,
|
|
265
387
|
background: true
|
|
266
|
-
})).targetId;
|
|
267
|
-
});
|
|
388
|
+
}, timeout)).targetId;
|
|
389
|
+
}, timeout);
|
|
268
390
|
}
|
|
269
391
|
async function closeTab(targetId) {
|
|
270
392
|
return withBrowser(async (s) => {
|
|
@@ -370,7 +492,7 @@ async function probeRenderer({ timeout = 5e3 } = {}) {
|
|
|
370
492
|
} catch {}
|
|
371
493
|
let targetId;
|
|
372
494
|
try {
|
|
373
|
-
targetId = await createTab("about:blank");
|
|
495
|
+
targetId = await createTab("about:blank", { timeout });
|
|
374
496
|
} catch (e) {
|
|
375
497
|
return {
|
|
376
498
|
ok: false,
|
|
@@ -504,7 +626,7 @@ function explainRendererFailure(h) {
|
|
|
504
626
|
];
|
|
505
627
|
if (rendezvous === false) lines.push(` root cause: the browser process (pid ${pid}) has lost its Mach bootstrap`, ` service "com.google.Chrome.MachPortRendezvousServer.${pid}".`, ` Chrome registers that name once, at startup; every child`, ` process looks it up to receive its shared memory. With the`, ` name gone, every renderer Chrome launches immediately exits.`, ` This is permanent for this browser process.`);
|
|
506
628
|
else if (rendezvous === true) lines.push(` note: the Mach rendezvous service for pid ${pid} IS still registered,`, ` so this is a different renderer failure from the one seen on`, ` 2026-08-22. Chrome's own log will say why:`, ` tail -50 ${chromeLogPath()}`);
|
|
507
|
-
lines.push(``, `This is a browser-level failure. It is NOT the site blocking automation, and`, `retrying, changing the URL, or adding a user agent will not help. Two tells:`, `same-origin navigations in tabs that already work keep working (they reuse a`, `renderer that already exists), and cross-origin ones fail with ERR_ABORTED`, `(site isolation needs a new renderer, which is the thing Chrome can't do).`, ``, `Recovery: restart Chrome. Nothing else clears it — closing tabs does not,`, `and plain \`launch\` will not either (it
|
|
629
|
+
lines.push(``, `This is a browser-level failure. It is NOT the site blocking automation, and`, `retrying, changing the URL, or adding a user agent will not help. Two tells:`, `same-origin navigations in tabs that already work keep working (they reuse a`, `renderer that already exists), and cross-origin ones fail with ERR_ABORTED`, `(site isolation needs a new renderer, which is the thing Chrome can't do).`, ``, `Recovery: restart Chrome. Nothing else clears it — closing tabs does not,`, `and plain \`launch\` will not either: it now DETECTS this (it runs this same`, `probe and fails), but it will never restart a browser other sessions may be`, `using without being told to. Restarting is always something you type.`, ``, ` browser-automation launch --restart # closes ALL tabs, then relaunches`, ``, `If other sessions are driving this Chrome, agree on the restart first — their`, `open tabs go with it. \`browser-automation list\` shows who holds what.`);
|
|
508
630
|
return lines.join("\n");
|
|
509
631
|
}
|
|
510
632
|
/**
|
|
@@ -2017,11 +2139,11 @@ function launchScriptPath() {
|
|
|
2017
2139
|
//#region src/commands/launch.ts
|
|
2018
2140
|
const launchCommand = define({
|
|
2019
2141
|
name: "launch",
|
|
2020
|
-
description: "Start (idempotent) this user's headed Chrome with the persistent profile",
|
|
2142
|
+
description: "Start (idempotent) this user's headed Chrome with the persistent profile, and verify it can still make renderers",
|
|
2021
2143
|
args: {
|
|
2022
2144
|
status: {
|
|
2023
2145
|
type: "boolean",
|
|
2024
|
-
description: "Only report whether the CDP browser is up (exit 0/1)"
|
|
2146
|
+
description: "Only report whether the CDP browser is up (exit 0/1) — reachability, not health"
|
|
2025
2147
|
},
|
|
2026
2148
|
restart: {
|
|
2027
2149
|
type: "boolean",
|
|
@@ -2040,7 +2162,21 @@ const launchCommand = define({
|
|
|
2040
2162
|
...ctx.values.status ? ["--status"] : [],
|
|
2041
2163
|
...ctx.values.restart ? ["--restart"] : []
|
|
2042
2164
|
]], { stdio: "inherit" });
|
|
2043
|
-
process.exit(r.status ?? 1);
|
|
2165
|
+
if (r.status !== 0 || ctx.values.status) process.exit(r.status ?? 1);
|
|
2166
|
+
const health = await probeRenderer().catch((e) => ({
|
|
2167
|
+
ok: false,
|
|
2168
|
+
ms: 0,
|
|
2169
|
+
pageTargets: 0,
|
|
2170
|
+
reason: String(e?.message ?? e)
|
|
2171
|
+
}));
|
|
2172
|
+
if (health.ok) {
|
|
2173
|
+
consola.success(`Renderer capacity: a new tab got a live renderer in ${health.ms}ms — this Chrome works.`);
|
|
2174
|
+
return;
|
|
2175
|
+
}
|
|
2176
|
+
consola.error("Chrome is up, but it cannot make renderers — this browser is unusable.\n");
|
|
2177
|
+
for (const line of explainRendererFailure(health).split("\n")) consola.log(line);
|
|
2178
|
+
consola.log(`\nChrome's own log: ${chromeLogPath()}`);
|
|
2179
|
+
process.exit(1);
|
|
2044
2180
|
}
|
|
2045
2181
|
});
|
|
2046
2182
|
//#endregion
|
|
@@ -2268,13 +2404,38 @@ const subCommands = new Map([
|
|
|
2268
2404
|
["prune", gcCommand],
|
|
2269
2405
|
["port", portCommand]
|
|
2270
2406
|
]);
|
|
2407
|
+
function withRealPositionals(cmd, real) {
|
|
2408
|
+
return {
|
|
2409
|
+
...cmd,
|
|
2410
|
+
async run(ctx) {
|
|
2411
|
+
return cmd.run?.({
|
|
2412
|
+
...ctx,
|
|
2413
|
+
positionals: restorePositionals(ctx.positionals, real)
|
|
2414
|
+
});
|
|
2415
|
+
}
|
|
2416
|
+
};
|
|
2417
|
+
}
|
|
2271
2418
|
async function run() {
|
|
2272
|
-
|
|
2419
|
+
let argv = process.argv.slice(2);
|
|
2420
|
+
let commands = subCommands;
|
|
2421
|
+
const sub = argv[0];
|
|
2422
|
+
const command = sub === void 0 ? void 0 : subCommands.get(sub);
|
|
2423
|
+
if (sub !== void 0 && command) {
|
|
2424
|
+
const canonical = canonicalize(sub, argv.slice(1), command.args ?? {});
|
|
2425
|
+
argv = canonical.argv;
|
|
2426
|
+
commands = new Map(subCommands);
|
|
2427
|
+
commands.set(sub, withRealPositionals(command, canonical.positionals));
|
|
2428
|
+
}
|
|
2429
|
+
await cli(argv, defaultCommand, {
|
|
2273
2430
|
name: "browser-automation",
|
|
2274
2431
|
version,
|
|
2275
2432
|
description,
|
|
2276
|
-
subCommands,
|
|
2277
|
-
renderHeader: null
|
|
2433
|
+
subCommands: commands,
|
|
2434
|
+
renderHeader: null,
|
|
2435
|
+
renderValidationErrors: async (_ctx, error) => {
|
|
2436
|
+
process.exitCode = 1;
|
|
2437
|
+
return error.errors.map((e) => e instanceof Error ? e.message : String(e)).join("\n");
|
|
2438
|
+
}
|
|
2278
2439
|
});
|
|
2279
2440
|
}
|
|
2280
2441
|
//#endregion
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.11",
|
|
4
4
|
"description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -16,8 +16,9 @@
|
|
|
16
16
|
"dev": "bun run ./src/index.ts",
|
|
17
17
|
"build": "tsdown",
|
|
18
18
|
"typecheck": "tsc --noEmit",
|
|
19
|
-
"check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build",
|
|
20
|
-
"
|
|
19
|
+
"check": "npm run typecheck && bash scripts/check-one-port.sh && npm run build && npm test",
|
|
20
|
+
"test": "node --test \"test/**/*.test.mjs\"",
|
|
21
|
+
"release": "echo 'Releases publish from CI, not here. Bump package.json + .claude-plugin/plugin.json, commit onto master, then: git tag vX.Y.Z && git push origin vX.Y.Z — then approve the gated job in GitHub Actions. `npm publish` from a laptop 404s (granular token). See .github/workflows/release.yml.' >&2; exit 1",
|
|
21
22
|
"sync-plugin": "bash scripts/sync-plugin.sh",
|
|
22
23
|
"prepack": "npm run build"
|
|
23
24
|
},
|
package/scripts/launch-chrome.sh
CHANGED
|
@@ -133,11 +133,23 @@ if [ "$RESTART" = "1" ] && is_up; then
|
|
|
133
133
|
sleep 1
|
|
134
134
|
fi
|
|
135
135
|
|
|
136
|
+
# A held port is the ONLY thing this branch establishes. It is emphatically not
|
|
137
|
+
# a health check: a Chrome that can no longer give a new tab a renderer keeps
|
|
138
|
+
# serving this port, answering /json/version and listing targets, while every
|
|
139
|
+
# goto fails. Only a round-trip through a renderer tells the two apart, and
|
|
140
|
+
# that lives in the CLI (src/core/renderer-health.ts) -- `browser-automation
|
|
141
|
+
# launch` runs it right after this script returns and prints the real verdict.
|
|
142
|
+
#
|
|
143
|
+
# This used to print a standing "use --restart if renderers are broken" hint
|
|
144
|
+
# here. It was correct advice and it did not work: printed on every launch,
|
|
145
|
+
# directly under the words "nothing to do", it read as boilerplate rather than
|
|
146
|
+
# as a diagnosis, and an operator burned many minutes on 25-30s `goto`s in
|
|
147
|
+
# 2026-09 without it registering. Advice that is always on screen carries no
|
|
148
|
+
# information. The verdict now appears only when it is true.
|
|
136
149
|
if is_up; then
|
|
137
|
-
echo "Already running on :${PORT} —
|
|
150
|
+
echo "Already running on :${PORT} — the port is held."
|
|
138
151
|
echo "Drive it with: browser-automation goto -s <session> <url>"
|
|
139
|
-
echo "(
|
|
140
|
-
echo " longer launch renderers — use: browser-automation launch --restart)"
|
|
152
|
+
echo "(Port held is not health. Check it works: browser-automation doctor)"
|
|
141
153
|
exit 0
|
|
142
154
|
fi
|
|
143
155
|
|
package/skills/browser/SKILL.md
CHANGED
|
@@ -56,12 +56,26 @@ file under `~/.browser-automation/sessions/`.
|
|
|
56
56
|
|
|
57
57
|
```bash
|
|
58
58
|
npm install -g @generativereality/browser-automation
|
|
59
|
-
browser-automation launch # start
|
|
60
|
-
browser-automation doctor # verify Node, Chrome, targets, sessions
|
|
59
|
+
browser-automation launch # start Chrome, and prove it can still make renderers
|
|
60
|
+
browser-automation doctor # verify Node, Chrome, renderer capacity, targets, sessions
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
`launch` is idempotent — safe to call when Chrome is already up.
|
|
64
|
-
|
|
63
|
+
`launch` is idempotent — safe to call when Chrome is already up. **It also
|
|
64
|
+
verifies the browser works**, which is a different question from whether one is
|
|
65
|
+
running: it ends with either
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
✔ Renderer capacity: a new tab got a live renderer in 47ms — this Chrome works.
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
or a non-zero exit and the full renderer-wedge diagnosis. That matters because a
|
|
72
|
+
held port, a `/json/version` that answers and a `list` full of targets are all
|
|
73
|
+
properties of the browser **process**, and the way a long-lived Chrome dies is
|
|
74
|
+
that it keeps all three while losing the ability to give any new tab a
|
|
75
|
+
**renderer** (see Gotchas). Older CLIs printed `nothing to do.` in exactly that
|
|
76
|
+
state — **if your `launch` ends without a `Renderer capacity:` line, you are on
|
|
77
|
+
one of those; run `doctor`, which is the same probe.** Override the profile path
|
|
78
|
+
with `BROWSER_AUTOMATION_PROFILE=...` and the CDP host with
|
|
65
79
|
`BROWSER_AUTOMATION_CDP=http://localhost:PORT` if needed.
|
|
66
80
|
|
|
67
81
|
## Commands
|
|
@@ -71,7 +85,7 @@ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, el
|
|
|
71
85
|
|
|
72
86
|
| Need | Command |
|
|
73
87
|
|---|---|
|
|
74
|
-
| Start
|
|
88
|
+
| Start the Chrome + verify it can make renderers | `browser-automation launch` |
|
|
75
89
|
| Diagnose setup (incl. renderer capacity) | `browser-automation doctor` |
|
|
76
90
|
| List sessions + every open tab (id, title, url) | `browser-automation list` |
|
|
77
91
|
| Open a background tab | `browser-automation new -s work [url]` |
|
|
@@ -134,6 +148,12 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
134
148
|
|
|
135
149
|
## Gotchas
|
|
136
150
|
|
|
151
|
+
- **Values may contain `--` freely.** `fill -s work e3 "see the --native flag"`
|
|
152
|
+
and a whole markdown brief with `---` rules go through as one quoted argv
|
|
153
|
+
element. Only a value that *begins* with a dash and is option-shaped
|
|
154
|
+
(`--force`, `-5`) needs the POSIX separator: `fill -s work -- e3 "--force"`.
|
|
155
|
+
An error naming the element (`'--force' is not an option of 'fill'`)
|
|
156
|
+
means exactly that — add `--`, do not re-quote.
|
|
137
157
|
- **Refs go stale after any DOM change**, not just navigation. Snapshot → use
|
|
138
158
|
those refs for one action → re-snapshot. "ref not found" means re-snapshot.
|
|
139
159
|
- **`isTrusted` / synthetic events.** Clicks and fills are JS-dispatched by
|
|
@@ -285,6 +305,26 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
285
305
|
right URL but an **empty title forever**; every `Runtime.evaluate` against it times out.
|
|
286
306
|
`Page.captureScreenshot` returns `Internal error`. The target shell exists; the renderer does not.
|
|
287
307
|
|
|
308
|
+
**It gets SLOW before it fails outright — that is the early warning.** Observed 2026-09-07 on a
|
|
309
|
+
Chrome that had been up 12 days: every `goto` took ~25–30s, and a batch of three blew a 120s
|
|
310
|
+
timeout, hours before anything failed hard. That was misread as "large files, slow browser" and
|
|
311
|
+
worked around with longer timeouts for many minutes; the actual fix was one `launch --restart`,
|
|
312
|
+
after which the same pages loaded instantly and 14 `file://` tabs opened in two quick batches.
|
|
313
|
+
**A `goto` that has quietly become slow is this, not your page.** Raise the timeout at most once,
|
|
314
|
+
then run `doctor`.
|
|
315
|
+
|
|
316
|
+
**Every cheap signal stays green, so do not take any of them as health.** On that same wedged
|
|
317
|
+
browser: `launch` said `Already running on :9223 — nothing to do.`, `curl :9223/json/version`
|
|
318
|
+
answered normally, and `list` cheerfully returned 10 targets — while `goto` exited 1 and `eval`
|
|
319
|
+
died with `CDP Runtime.evaluate timed out after 30000ms`. Port held, HTTP endpoint answering and
|
|
320
|
+
targets listed are all properties of the **browser** process; the thing that is broken is its
|
|
321
|
+
ability to start a **renderer**, and only a probe that runs code in one can see it.
|
|
322
|
+
**Since fixed:** `launch` now runs that probe itself and exits non-zero with the diagnosis
|
|
323
|
+
instead of reporting "nothing to do", so this particular green-across-the-board trap is closed.
|
|
324
|
+
It still will not restart for you — that stays something you type, because the tabs are not
|
|
325
|
+
only yours. On a CLI old enough to lack it, `doctor` is the same probe; nothing cheaper
|
|
326
|
+
substitutes for either.
|
|
327
|
+
|
|
288
328
|
**The mechanism** (macOS, from Chrome's own log at `$TMPDIR/chrome-<port>.log` — `launch --restart`
|
|
289
329
|
keeps the previous browser's log as `chrome-<port>.log.prev`, which is the one you want after a
|
|
290
330
|
restart):
|
|
@@ -348,6 +388,41 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
348
388
|
is a completely different client. Check the browser first: if `doctor` says renderer capacity is
|
|
349
389
|
fine and a boring cross-origin URL loads, *then* start suspecting the site.
|
|
350
390
|
|
|
391
|
+
- **A backgrounded tab may never paint at all — and `read`/`snapshot` will not tell you.** Distinct
|
|
392
|
+
from "still loading": `document.readyState` reaches `complete`, but the SPA never renders, so
|
|
393
|
+
`read` returns a stale shell (e.g. a bare "Loading") and `snapshot` lists none of the real
|
|
394
|
+
controls. The trap is that this looks exactly like *the page does not have that element*, and you
|
|
395
|
+
will go hunting for a different selector or conclude the flow changed. Measured 2026-09-02 on
|
|
396
|
+
Google's `accounts.google.com/v3/signin/challenge/pwd`: `readyState: "complete"`,
|
|
397
|
+
`body.innerText.length: 202` frozen on the previous step's text, and the password field present in
|
|
398
|
+
the DOM but `offsetParent === null` for as long as the tab stayed backgrounded.
|
|
399
|
+
**Diagnose** before changing your selector:
|
|
400
|
+
```bash
|
|
401
|
+
browser-automation eval -s x '({ready:document.readyState,vis:document.visibilityState,len:document.body.innerText.length})'
|
|
402
|
+
```
|
|
403
|
+
`visibilityState: "hidden"` with a **stuck `len`** is this, not a selector problem. Note the
|
|
404
|
+
stuck `len` is the whole tell: `hidden` on its own is the normal, healthy state of every
|
|
405
|
+
backgrounded tab — verified 2026-09-07, a background tab reporting `hidden` returned its real
|
|
406
|
+
painted text — so never read `hidden` alone as a diagnosis.
|
|
407
|
+
**Fix:** front the tab. There is no `activate` command — a `click --trusted` on any harmless
|
|
408
|
+
element (a wrapper `div` from the snapshot works; avoid submit buttons and links) brings the tab
|
|
409
|
+
to front and waits for it to be visible, and the page paints immediately. Same root cause as the
|
|
410
|
+
WebAuthn note above, different symptom: that one refuses, this one silently never renders.
|
|
411
|
+
|
|
412
|
+
**Do not confuse this with the renderer wedge above.** Both present to an operator as "the page
|
|
413
|
+
isn't there, but every tool says fine", and the fixes are opposite — one is a per-tab nudge, the
|
|
414
|
+
other closes every tab in the browser. What separates them:
|
|
415
|
+
|
|
416
|
+
| | backgrounded tab never paints | Chrome cannot make renderers |
|
|
417
|
+
|---|---|---|
|
|
418
|
+
| `goto` | succeeds, rc=0 (may be slow) | **rc=1**, or `Page.enable timed out` |
|
|
419
|
+
| `eval` | works, returns a result | **`Runtime.evaluate` times out at 30000ms** |
|
|
420
|
+
| scope | that one tab | **every** new tab / cross-origin nav |
|
|
421
|
+
| `doctor` | `✓ Renderer capacity` | names the wedge + pid |
|
|
422
|
+
| fix | `click --trusted` on the tab | `launch --restart` (**ask first**) |
|
|
423
|
+
|
|
424
|
+
`eval` is the fast discriminator: if it answers at all, the renderer is alive and you are in the
|
|
425
|
+
painting case. If it times out, stop poking the page and run `doctor`.
|
|
351
426
|
- **Page still loading.** `goto` waits for the load event, but SPAs render after.
|
|
352
427
|
If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
|
|
353
428
|
once a known element should be present.
|