gipity 1.1.16 → 1.1.19
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/README.md +58 -75
- package/dist/adopt-cwd.js +2 -13
- package/dist/api.js +26 -44
- package/dist/auth.js +1 -1
- package/dist/banner.js +3 -7
- package/dist/catalog.js +8 -7
- package/dist/commands/add.js +26 -9
- package/dist/commands/approval.js +1 -1
- package/dist/commands/ask.js +112 -0
- package/dist/commands/bug.js +5 -5
- package/dist/commands/build.js +10 -35
- package/dist/commands/credits.js +3 -3
- package/dist/commands/doctor.js +7 -8
- package/dist/commands/email.js +6 -56
- package/dist/commands/generate.js +4 -4
- package/dist/commands/init.js +40 -30
- package/dist/commands/key.js +1 -1
- package/dist/commands/load.js +2 -12
- package/dist/commands/logs.js +2 -2
- package/dist/commands/memory.js +5 -17
- package/dist/commands/notify.js +1 -1
- package/dist/commands/page-eval.js +55 -38
- package/dist/commands/page-inspect.js +6 -6
- package/dist/commands/page-screenshot.js +51 -54
- package/dist/commands/page-test.js +188 -14
- package/dist/commands/payments.js +2 -2
- package/dist/commands/project.js +66 -15
- package/dist/commands/realtime.js +96 -4
- package/dist/commands/records.js +4 -6
- package/dist/commands/sandbox.js +2 -3
- package/dist/commands/skill.js +50 -22
- package/dist/commands/status.js +7 -9
- package/dist/commands/test.js +2 -2
- package/dist/commands/token.js +4 -4
- package/dist/commands/workflow.js +45 -8
- package/dist/config.js +22 -6
- package/dist/flag-aliases.js +75 -18
- package/dist/help-skills.js +2 -2
- package/dist/hooks/capture-runner.js +5 -3
- package/dist/index.js +1616 -1498
- package/dist/knowledge.js +24 -21
- package/dist/login-flow.js +4 -4
- package/dist/net.js +91 -0
- package/dist/opencode-setup.js +2 -2
- package/dist/page-fixtures.js +3 -3
- package/dist/project-setup.js +2 -3
- package/dist/prompts.js +1 -1
- package/dist/realtime-bench.js +12040 -0
- package/dist/relay/agent-token.js +1 -1
- package/dist/relay/daemon.js +0 -1
- package/dist/relay/setup.js +13 -2
- package/dist/setup.js +11 -12
- package/dist/sync.js +3 -3
- package/dist/utils.js +1 -1
- package/package.json +10 -4
- package/dist/commands/agent.js +0 -251
- package/dist/commands/chat.js +0 -137
- package/dist/commands/claude.js +0 -1056
- package/dist/commands/plan.js +0 -93
|
@@ -43,7 +43,7 @@ function printAuthLine(auth) {
|
|
|
43
43
|
const who = getAuth()?.email;
|
|
44
44
|
console.log(auth.established
|
|
45
45
|
? `${label('Auth')} ${success('session established')}${who ? muted(` as ${who}`) : ''} ${muted('(what the page renders with it is app-defined)')}`
|
|
46
|
-
: `${warning('Auth: session NOT established')}${auth.detail ?
|
|
46
|
+
: `${warning('Auth: session NOT established')}${auth.detail ? `: ${auth.detail}` : ''} ${muted('(this is the anonymous view)')}`);
|
|
47
47
|
}
|
|
48
48
|
/** A failed pre-capture script still yields a screenshot - of the page it never
|
|
49
49
|
* touched. Silence there is the trap: the image looks plausible and the command
|
|
@@ -70,7 +70,7 @@ export function augmentSandboxTimeout(message) {
|
|
|
70
70
|
return message;
|
|
71
71
|
return (`${message}\n` +
|
|
72
72
|
`A pre-capture script was set (--action and/or the --wait-for gate), and its runtime is spent INSIDE ` +
|
|
73
|
-
`that same sandbox budget
|
|
73
|
+
`that same sandbox budget: a script that waits on slow work (a WASM/model download, a network fetch, ` +
|
|
74
74
|
`a long animation) can exhaust the budget on its own. Keep --action to the interaction itself (a click, ` +
|
|
75
75
|
`a keypress), let the page do the slow work on load, and absorb that with --wait <ms> or a tighter ` +
|
|
76
76
|
`--wait-for '<selector>' gate instead.`);
|
|
@@ -101,15 +101,16 @@ function dimSuffix(vp) {
|
|
|
101
101
|
const dpr = vp.deviceScaleFactor ?? 1;
|
|
102
102
|
return dpr === 1 ? `${vp.width}x${vp.height}` : `${vp.width}x${vp.height}@${dpr}`;
|
|
103
103
|
}
|
|
104
|
-
/** Default screenshot directory: `<project-root>/screenshots`, falling
|
|
105
|
-
* to `./screenshots` in one-off mode (no linked project).
|
|
106
|
-
*
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
|
|
104
|
+
/** Default screenshot directory: `<project-root>/tmp/screenshots`, falling
|
|
105
|
+
* back to `./tmp/screenshots` in one-off mode (no linked project). A
|
|
106
|
+
* verification capture is scratch: `tmp/` is the one place that never syncs
|
|
107
|
+
* and never deploys, so a shot of a signed-in, private view can't leak into
|
|
108
|
+
* the project and nothing needs cleaning up afterwards. A capture worth
|
|
109
|
+
* keeping is a deliberate `-o docs/<name>.png` (synced, never deployed).
|
|
110
|
+
* Timestamped filenames keep a run's shots in order. */
|
|
111
|
+
export function defaultScreenshotDir() {
|
|
111
112
|
const root = getProjectRoot();
|
|
112
|
-
return join(root ?? '.', 'screenshots');
|
|
113
|
+
return join(root ?? '.', 'tmp', 'screenshots');
|
|
113
114
|
}
|
|
114
115
|
/** `yyyy-mm-dd_hh-mm-ss` per the repo timestamp convention - sorts chronologically,
|
|
115
116
|
* filesystem-safe. One stamp per invocation; viewport suffixes keep multi-shot
|
|
@@ -200,6 +201,16 @@ function appendOption(value, previous = []) {
|
|
|
200
201
|
// which swallowed the script and errored with a redirect: when the guess is
|
|
201
202
|
// unambiguous, making it WORK beats making it a better error.)
|
|
202
203
|
const ACTION_ALIAS_FLAGS = ['--eval', '--js', '--javascript', '--script', '--code', '--exec'];
|
|
204
|
+
// Same accept-the-reflex-guess pattern for the output file: `--path` and `--out`
|
|
205
|
+
// are what agents type for "save it here" (commander answered `--path` with
|
|
206
|
+
// "Did you mean --auth?", which points nowhere useful). Working hidden aliases
|
|
207
|
+
// for -o/--output.
|
|
208
|
+
const OUTPUT_ALIAS_FLAGS = ['--path', '--out'];
|
|
209
|
+
/** True when `--file` names an image: the caller meant the OUTPUT file, but
|
|
210
|
+
* --file is the pre-capture SCRIPT. Caught before it is read as JavaScript. */
|
|
211
|
+
export function looksLikeImagePath(p) {
|
|
212
|
+
return /\.(png|jpe?g|webp|gif)$/i.test(p);
|
|
213
|
+
}
|
|
203
214
|
/** A capture is worthless if it fires before the app reaches the state you meant
|
|
204
215
|
* to photograph, and the only lever used to be a blind millisecond delay — so a
|
|
205
216
|
* camera/vision app got screenshotted with a guessed duration (`--wait 22000`).
|
|
@@ -214,7 +225,7 @@ export function buildWaitForGate(selector, timeoutMs) {
|
|
|
214
225
|
`while (Date.now() - __t0 < ${timeoutMs}) { ` +
|
|
215
226
|
`try { if (document.querySelector(${sel})) return; } catch (e) { throw new Error('wait-for: invalid selector ' + ${sel}); } ` +
|
|
216
227
|
`await new Promise((r) => setTimeout(r, 100)); } ` +
|
|
217
|
-
`throw new Error('wait-for: nothing matched ' + ${sel} + ' within ${timeoutMs}ms
|
|
228
|
+
`throw new Error('wait-for: nothing matched ' + ${sel} + ' within ${timeoutMs}ms: the page never reached that state (raise --wait-timeout, fix the selector, or check the app actually gets there headlessly)'); })();`);
|
|
218
229
|
}
|
|
219
230
|
/** Max ms the selector gate may wait. The gate runs inside the capture's sandbox
|
|
220
231
|
* exec budget (page load + delay + script + settle + render), and 15s is what
|
|
@@ -240,7 +251,7 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
240
251
|
// the single most common reason to screenshot, and agents routinely read the
|
|
241
252
|
// help through `--help | head -N` — buried below the timing flags, these two
|
|
242
253
|
// fell off the bottom and the run proceeded at desktop width.
|
|
243
|
-
.option('--device <names>', `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag). mobile/tablet emulate a real touch device
|
|
254
|
+
.option('--device <names>', `Device preset(s): ${Object.keys(DEVICE_PRESETS).join(', ')} (comma-separated or repeat flag). mobile/tablet emulate a real touch device (touch events, mobile user-agent, DPR) so touch-gated mobile UI actually renders.`, appendOption, [])
|
|
244
255
|
.option('--viewport <dims>', 'Raw viewport(s): WxH or WxH@dpr (comma-separated or repeat flag), e.g. --viewport 390x844 for a phone-sized window', appendOption, [])
|
|
245
256
|
// No commander default: a default here would make the value always set, so the
|
|
246
257
|
// merge below could not tell "caller chose a delay" from "nobody did" — which
|
|
@@ -251,12 +262,11 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
251
262
|
.option('--action <js>', 'Run JS in the page before capturing - e.g. click a button to enter a state ("document.getElementById(\'play\').click()"). Runs as an async function body, so const/await and app-relative import(\'./...\') work. Runs after the post-load delay, then settles again before the shot. If it throws, the capture still happens and the failure is reported.')
|
|
252
263
|
.option('--file <path>', 'Read the pre-capture script from a file instead of inline --action (mutually exclusive), or --file - to read it from stdin (pipe a heredoc: --file - <<\'EOF\' ... EOF) with no tmp file. For a multi-step driver - click through a flow, wait for it to render - then capture. Same async-function-body semantics as --action; same --file flag as page eval.')
|
|
253
264
|
.option('--full', 'Capture the full scrollable page (default: viewport only). Scrolls the page through first so scroll-reveal/fade-in-on-scroll (IntersectionObserver) sections render into the shot instead of capturing blank.')
|
|
254
|
-
.option('-o, --output <file>', 'Output path (default
|
|
265
|
+
.option('-o, --output <file>', 'Output path (default tmp/screenshots/ss-<host>-<timestamp>.png in the project: scratch, never synced or deployed). To keep a capture, write it under docs/ (-o docs/home.png: synced, never deployed). With several viewports it is a stem: -o tmp/shot.png --device desktop,mobile writes tmp/shot-desktop.png and tmp/shot-mobile.png.')
|
|
255
266
|
.option('--no-reload-between', 'Skip reload between viewports (faster, lower fidelity - only safe for static pages)')
|
|
256
|
-
.option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly. The video feed is a built-in test pattern
|
|
257
|
-
.option('--camera <path>', 'Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser\'s WEBCAM feed, then capture
|
|
258
|
-
.option('--auth', 'Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor
|
|
259
|
-
.option('--ephemeral', 'Skip the project screenshot history: do not persist this capture to Gipity (screenshots/ in the project). Local file is still written.')
|
|
267
|
+
.option('--fake-media', 'Grant a synthetic microphone + camera and auto-accept the getUserMedia prompt, so voice/camera apps render headlessly. The video feed is a built-in test pattern. To capture what the app does with a REAL frame (a hand, a face, an object), use --camera <path> instead.')
|
|
268
|
+
.option('--camera <path>', 'Play a local image or video (.png/.jpg/.webp/.mp4/.webm/.y4m/.mjpeg) as the browser\'s WEBCAM feed, then capture, so the shot shows the app reacting to a frame you chose (detected gesture, boxes, labels). Implies --fake-media.')
|
|
269
|
+
.option('--auth', 'Capture the page signed in as you (your Gipity account), so UI behind a Sign-in-with-Gipity login is shown. Only works for apps using Sign in with Gipity, hosted on *.gipity.ai. Without this flag the page loads as a genuinely anonymous, signed-out visitor: nothing carries over from earlier --auth runs.')
|
|
260
270
|
.option('--json', 'Output JSON metadata instead of a friendly summary')
|
|
261
271
|
.addOption(new Option('--post-load-delay <ms>', 'Alias for --wait').hideHelp())
|
|
262
272
|
// (--eval and the other JS-intent guesses are registered in one place from
|
|
@@ -277,7 +287,7 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
277
287
|
// so the next call uses it.
|
|
278
288
|
const aliasFlag = ACTION_ALIAS_FLAGS.find((f) => opts[f.slice(2)] !== undefined);
|
|
279
289
|
if (aliasFlag) {
|
|
280
|
-
console.error(muted(`Note: treating ${aliasFlag} as --action
|
|
290
|
+
console.error(muted(`Note: treating ${aliasFlag} as --action: it runs your JS in the page before the capture. --action is the canonical flag.`));
|
|
281
291
|
}
|
|
282
292
|
// The pre-capture script can come inline (--action / its JS-intent aliases) or
|
|
283
293
|
// from a file/stdin (--file, the same script-passing ergonomics as page eval).
|
|
@@ -290,6 +300,9 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
290
300
|
throw new Error('Pass either --file <path> or an inline --action script, not both');
|
|
291
301
|
}
|
|
292
302
|
let actionScript = inlineAction;
|
|
303
|
+
if (opts.file && looksLikeImagePath(opts.file)) {
|
|
304
|
+
throw new Error(`--file is the pre-capture SCRIPT (JavaScript to run before the shot), not the output image: save the PNG with -o ${opts.file}`);
|
|
305
|
+
}
|
|
293
306
|
if (opts.file) {
|
|
294
307
|
try {
|
|
295
308
|
actionScript = readScriptFile(opts.file);
|
|
@@ -310,7 +323,7 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
310
323
|
throw new Error('--wait must be a non-negative integer (ms)');
|
|
311
324
|
}
|
|
312
325
|
if (postLoadDelayMs > MAX_POST_LOAD_DELAY_MS) {
|
|
313
|
-
console.error(warning(`--wait ${postLoadDelayMs}ms exceeds the ${MAX_POST_LOAD_DELAY_MS}ms cap
|
|
326
|
+
console.error(warning(`--wait ${postLoadDelayMs}ms exceeds the ${MAX_POST_LOAD_DELAY_MS}ms cap: using ${MAX_POST_LOAD_DELAY_MS}ms. ` +
|
|
314
327
|
`Waiting longer is rarely the fix: gate on the state you want with --wait-for '<selector>' instead of guessing a duration.`));
|
|
315
328
|
postLoadDelayMs = MAX_POST_LOAD_DELAY_MS;
|
|
316
329
|
}
|
|
@@ -320,7 +333,7 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
320
333
|
}
|
|
321
334
|
const waitForTimeoutMs = Math.min(waitForTimeoutRaw, WAIT_FOR_MAX_MS);
|
|
322
335
|
if (waitForTimeoutRaw > WAIT_FOR_MAX_MS) {
|
|
323
|
-
console.error(warning(`--wait-timeout ${waitForTimeoutRaw}ms exceeds the ${WAIT_FOR_MAX_MS}ms the capture's browser budget covers
|
|
336
|
+
console.error(warning(`--wait-timeout ${waitForTimeoutRaw}ms exceeds the ${WAIT_FOR_MAX_MS}ms the capture's browser budget covers: using ${WAIT_FOR_MAX_MS}ms. ` +
|
|
324
337
|
`A state that takes longer than that to appear is not a screenshot problem: watch for it with ` +
|
|
325
338
|
`\`gipity page eval <url> --wait-for '<selector>' --wait-timeout 30000\` (a wider budget), then capture it.`));
|
|
326
339
|
}
|
|
@@ -342,7 +355,7 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
342
355
|
// pair is a mis-invocation worth one precise line, not a range error.
|
|
343
356
|
if (opts.width !== undefined || opts.height !== undefined) {
|
|
344
357
|
if (opts.width === undefined || opts.height === undefined) {
|
|
345
|
-
pageScreenshotCommand.error('error: --width and --height go together (both in px, equivalent to --viewport WxH)
|
|
358
|
+
pageScreenshotCommand.error('error: --width and --height go together (both in px, equivalent to --viewport WxH): ' +
|
|
346
359
|
'or use a preset like --device mobile for a real handset (touch events, mobile user-agent, DPR)');
|
|
347
360
|
}
|
|
348
361
|
if (!/^\d+$/.test(String(opts.width)) || !/^\d+$/.test(String(opts.height))) {
|
|
@@ -353,7 +366,7 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
353
366
|
// renders its desktop variant. Say so once, on the path where the caller
|
|
354
367
|
// was clearly after a phone.
|
|
355
368
|
if (parseInt(String(opts.width), 10) <= 500) {
|
|
356
|
-
console.error(muted('Tip: --device mobile emulates a real handset (touch events, mobile user-agent, DPR)
|
|
369
|
+
console.error(muted('Tip: --device mobile emulates a real handset (touch events, mobile user-agent, DPR): a raw viewport only resizes the window.'));
|
|
357
370
|
}
|
|
358
371
|
}
|
|
359
372
|
const customViewports = [
|
|
@@ -369,16 +382,12 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
369
382
|
// Server defaults to 1280×720 when viewports is omitted - don't send it in
|
|
370
383
|
// the no-flag case so the filename stays unsuffixed (no viewport segment).
|
|
371
384
|
const userSpecifiedViewports = customViewports.length > 0;
|
|
372
|
-
// Filenames are decided before the request so the server can persist the
|
|
373
|
-
// captures to the project VFS under the SAME names the local files get —
|
|
374
|
-
// the local screenshots/ dir and the VFS screenshot history stay 1:1 and
|
|
375
|
-
// sync reconciles them by content hash instead of duplicating.
|
|
376
385
|
const slug = slugFromUrl(url);
|
|
377
386
|
const ts = timestampSlug();
|
|
378
387
|
const shotName = (vp) => defaultFilename(slug, ts, vp && userSpecifiedViewports ? dimSuffix(vp) : undefined);
|
|
379
388
|
const names = userSpecifiedViewports ? customViewports.map(shotName) : [shotName()];
|
|
380
389
|
const projectGuid = getConfig()?.projectGuid;
|
|
381
|
-
const
|
|
390
|
+
const outputArg = opts.output ?? OUTPUT_ALIAS_FLAGS.map((f) => opts[f.slice(2)]).find(Boolean);
|
|
382
391
|
// The webcam frame is hosted in the project's public file store for the
|
|
383
392
|
// browser container to fetch, so it needs a linked project. Validate the
|
|
384
393
|
// file locally first — a bad file type costs one instant error, not an
|
|
@@ -387,7 +396,7 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
387
396
|
if (opts.camera) {
|
|
388
397
|
assertCameraFile(opts.camera);
|
|
389
398
|
if (!projectGuid)
|
|
390
|
-
throw new Error('--camera needs a linked project (the frame is hosted for the browser to fetch)
|
|
399
|
+
throw new Error('--camera needs a linked project (the frame is hosted for the browser to fetch): run `gipity link` first.');
|
|
391
400
|
console.log(muted(`Hosting camera feed ${opts.camera}...`));
|
|
392
401
|
camera = await uploadCameraFeed(projectGuid, opts.camera);
|
|
393
402
|
}
|
|
@@ -412,7 +421,6 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
412
421
|
...(camera ? { cameraUrl: camera.url } : {}),
|
|
413
422
|
...(opts.auth ? { auth: true } : {}),
|
|
414
423
|
...(preCapture ? { action: preCapture } : {}),
|
|
415
|
-
...(save ? { save } : {}),
|
|
416
424
|
};
|
|
417
425
|
// Load + render across viewports runs server-side and can take many
|
|
418
426
|
// seconds; animate the wait, then clear so the saved-files summary is the
|
|
@@ -439,7 +447,7 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
439
447
|
await deleteFixture(projectGuid, camera.guid);
|
|
440
448
|
}
|
|
441
449
|
catch (err) {
|
|
442
|
-
console.error(warning(`⚠ Could not auto-delete camera feed "${camera.name}" (${camera.guid})
|
|
450
|
+
console.error(warning(`⚠ Could not auto-delete camera feed "${camera.name}" (${camera.guid}): still hosted at ${camera.url}: ${err.message}`));
|
|
443
451
|
}
|
|
444
452
|
}
|
|
445
453
|
}
|
|
@@ -458,19 +466,19 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
458
466
|
const usedStems = new Set();
|
|
459
467
|
const outputPath = (i) => {
|
|
460
468
|
if (pngs.length === 1)
|
|
461
|
-
return
|
|
469
|
+
return outputArg;
|
|
462
470
|
let suffix = viewportLabels[i] ?? dimSuffix(meta.screenshots[i].viewport);
|
|
463
471
|
while (usedStems.has(suffix))
|
|
464
472
|
suffix += `-${i + 1}`;
|
|
465
473
|
usedStems.add(suffix);
|
|
466
|
-
return stemPath(
|
|
474
|
+
return stemPath(outputArg, suffix);
|
|
467
475
|
};
|
|
468
476
|
for (let i = 0; i < pngs.length; i++) {
|
|
469
|
-
const target =
|
|
477
|
+
const target = outputArg
|
|
470
478
|
? outputPath(i)
|
|
471
479
|
: join(dir, names[i] ?? shotName(meta.screenshots[i].viewport));
|
|
472
480
|
// Create the target's parent dir so a `-o` path under a not-yet-existing
|
|
473
|
-
// directory (e.g.
|
|
481
|
+
// directory (e.g. docs/shots/home.png) writes cleanly instead of
|
|
474
482
|
// failing with a raw ENOENT and forcing a manual `mkdir -p`.
|
|
475
483
|
mkdirSync(dirname(target), { recursive: true });
|
|
476
484
|
writeFileSync(target, pngs[i].buffer);
|
|
@@ -501,22 +509,10 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
501
509
|
size_bytes: s.screenshotSizeBytes,
|
|
502
510
|
full_page: meta.full,
|
|
503
511
|
phase: s.phase,
|
|
504
|
-
...(s.vfs ? { gipity: s.vfs } : {}),
|
|
505
512
|
})),
|
|
506
513
|
}));
|
|
507
514
|
return;
|
|
508
515
|
}
|
|
509
|
-
/** One-line VFS-history status for a screenshot ("saved to Gipity" or why not). */
|
|
510
|
-
const printVfsLine = (s) => {
|
|
511
|
-
if (!s.vfs)
|
|
512
|
-
return;
|
|
513
|
-
if ('error' in s.vfs) {
|
|
514
|
-
console.log(`${warning('⚠ Gipity save failed:')} ${s.vfs.error} ${muted('(local file is fine)')}`);
|
|
515
|
-
}
|
|
516
|
-
else {
|
|
517
|
-
console.log(`${label('Gipity history')} ${s.vfs.path} ${muted('(synced, not deployed)')}`);
|
|
518
|
-
}
|
|
519
|
-
};
|
|
520
516
|
if (meta.screenshots.length === 1) {
|
|
521
517
|
const s = meta.screenshots[0];
|
|
522
518
|
console.log(`${brand('Screenshot')} ${bold(url)}`);
|
|
@@ -537,7 +533,6 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
537
533
|
if (s.width && s.height)
|
|
538
534
|
console.log(`${label('Screenshot dims')} ${s.width} × ${s.height}`);
|
|
539
535
|
console.log(`${label('Screenshot file')} ${success(savedFiles[0])}`);
|
|
540
|
-
printVfsLine(s);
|
|
541
536
|
return;
|
|
542
537
|
}
|
|
543
538
|
console.log(`${brand('Loading')} ${bold(url)} ${muted(`once → ${meta.screenshots.length} viewports`)}`);
|
|
@@ -554,20 +549,21 @@ export const pageScreenshotCommand = new Command('screenshot')
|
|
|
554
549
|
for (let i = 0; i < meta.screenshots.length; i++) {
|
|
555
550
|
const s = meta.screenshots[i];
|
|
556
551
|
const dims = `${s.viewport.width}×${s.viewport.height}${s.viewport.deviceScaleFactor > 1 ? ` @${s.viewport.deviceScaleFactor}x` : ''}`;
|
|
557
|
-
const deviceTag = s.viewport.device ? muted(`
|
|
552
|
+
const deviceTag = s.viewport.device ? muted(` (${s.viewport.device}, touch)`) : '';
|
|
558
553
|
console.log(`\n${brand('@ ' + dims)}${deviceTag}`);
|
|
559
554
|
const sizePart = formatSize(s.screenshotSizeBytes) + (meta.full ? ' (full page)' : '');
|
|
560
555
|
console.log(`${label('Screenshot size')} ${sizePart}`);
|
|
561
556
|
if (s.width && s.height)
|
|
562
557
|
console.log(`${label('Screenshot dims')} ${s.width} × ${s.height}`);
|
|
563
558
|
console.log(`${label('Screenshot file')} ${success(savedFiles[i])}`);
|
|
564
|
-
printVfsLine(s);
|
|
565
559
|
}
|
|
566
560
|
}));
|
|
567
561
|
// Register the JS-intent guesses as hidden aliases for --action (value-taking,
|
|
568
562
|
// so they capture the script) — the action folds them into the pre-capture body.
|
|
569
563
|
for (const f of ACTION_ALIAS_FLAGS)
|
|
570
564
|
pageScreenshotCommand.addOption(new Option(`${f} <js>`, 'Alias for --action').hideHelp());
|
|
565
|
+
for (const f of OUTPUT_ALIAS_FLAGS)
|
|
566
|
+
pageScreenshotCommand.addOption(new Option(`${f} <file>`, 'Alias for -o/--output').hideHelp());
|
|
571
567
|
// `screenshot` captures the page AFTER load + settle (+ optional --wait-for gate
|
|
572
568
|
// and --action). There is no scroll-to-a-position lever (agents reach for
|
|
573
569
|
// --scroll and get an unknown-option detour) — but `--full` does walk the page
|
|
@@ -578,23 +574,24 @@ for (const f of ACTION_ALIAS_FLAGS)
|
|
|
578
574
|
// --full + crop covers off-screen regions; `page eval` reads data, no picture.
|
|
579
575
|
pageScreenshotCommand.addHelpText('after', `
|
|
580
576
|
Examples:
|
|
581
|
-
gipity page screenshot "https://dev.gipity.ai/me/app/"
|
|
577
|
+
gipity page screenshot "https://dev.gipity.ai/me/app/" # -> tmp/screenshots/ (scratch: never synced or deployed)
|
|
578
|
+
gipity page screenshot "https://dev.gipity.ai/me/app/" -o docs/home.png # keep it (docs/ syncs, never deploys)
|
|
582
579
|
gipity page screenshot "https://dev.gipity.ai/me/app/" --full # whole scrollable page (scroll-reveal sections triggered)
|
|
583
580
|
gipity page screenshot "https://dev.gipity.ai/me/app/" --device mobile,desktop
|
|
584
581
|
gipity page screenshot "https://dev.gipity.ai/me/app/" \\
|
|
585
582
|
--action "document.getElementById('play').click()" # capture an in-game frame
|
|
586
583
|
# Camera / vision app: play a real frame in as the webcam and shoot once the app
|
|
587
|
-
# says it's ready
|
|
584
|
+
# says it's ready: same --camera / --wait-for flags as 'page eval', no guessed delay:
|
|
588
585
|
gipity page screenshot "https://dev.gipity.ai/me/app/" --camera fist.png \\
|
|
589
586
|
--wait-for '[data-vision="ready"]'
|
|
590
587
|
|
|
591
588
|
Waiting for the page to reach a state before the shot?
|
|
592
589
|
--wait-for '<selector>' gates the capture on the app's own signal (deterministic).
|
|
593
|
-
Reach for --wait <ms> only when there is nothing to gate on
|
|
590
|
+
Reach for --wait <ms> only when there is nothing to gate on: a guessed duration
|
|
594
591
|
either shoots too early or wastes the difference.
|
|
595
592
|
|
|
596
593
|
Capturing a state that needs an interaction (start a game, open a menu, dismiss a modal)?
|
|
597
|
-
Use --action to run JS in the page before the shot
|
|
594
|
+
Use --action to run JS in the page before the shot: it fires after the wait
|
|
598
595
|
(and after any --wait-for gate), then settles again so the result has painted. For
|
|
599
596
|
a multi-step driver (click, wait, click) pipe it as a heredoc with --file - (same
|
|
600
597
|
as 'page eval') instead of cramming it into one inline string:
|
|
@@ -610,6 +607,6 @@ Capturing a state that needs an interaction (start a game, open a menu, dismiss
|
|
|
610
607
|
Capturing an off-screen region or reading element data?
|
|
611
608
|
• --full captures the ENTIRE scrollable page (then crop to the region).
|
|
612
609
|
• 'gipity page eval <url> "<expr>"' reads any (even off-screen) element's
|
|
613
|
-
data/state/rect without a picture
|
|
610
|
+
data/state/rect without a picture: e.g. read the chart's bar values
|
|
614
611
|
directly instead of screenshotting the slide.`);
|
|
615
612
|
//# sourceMappingURL=page-screenshot.js.map
|
|
@@ -18,6 +18,104 @@ async function inspectClient(url, waitMs, i) {
|
|
|
18
18
|
}
|
|
19
19
|
const MAX_HOLD_MS = 15_000; // keep each in-page await under the ~20s browser action timeout
|
|
20
20
|
const MIN_HOLD_MS = 1_000;
|
|
21
|
+
// ── lifecycle actions (--at) ───────────────────────────────────────────────
|
|
22
|
+
// Freeze, hide, or take one client offline partway through the hold window, so
|
|
23
|
+
// an app can test what its peers do when a phone locks (host handoff) instead
|
|
24
|
+
// of only a clean leave. The server applies them in the browser over CDP; the
|
|
25
|
+
// CLI parses and validates the specs and shows the timeline.
|
|
26
|
+
export const LIFECYCLE_ACTIONS = ['freeze', 'wake', 'hide', 'show', 'offline', 'online'];
|
|
27
|
+
/** Sample value recorded for an observe slot the page's JS never got to run
|
|
28
|
+
* (it was frozen, or blocked, when the sample was due). */
|
|
29
|
+
export const PAUSED_SAMPLE = '(paused)';
|
|
30
|
+
/** How late a sample may run before it counts as slept through. */
|
|
31
|
+
export const PAUSE_SLACK_MS = 1500;
|
|
32
|
+
const AT_SYNTAX = '"<label|index>:<action>@<ms>", e.g. --at host:freeze@5000';
|
|
33
|
+
/** Parse the repeatable --at specs into per-client step lists (index-aligned
|
|
34
|
+
* with `labels`, one entry per client). A target matches every client with
|
|
35
|
+
* that label (so `phone:hide@3000` hides every phone), else a 0-based index.
|
|
36
|
+
* Throws a caller-facing error on bad syntax, an unknown client or action, a
|
|
37
|
+
* time outside the hold window, or an impossible sequence (wake without a
|
|
38
|
+
* freeze, ...). The server re-checks the sequence; this is the early error. */
|
|
39
|
+
export function parseAtSpecs(specs, labels, holdMs) {
|
|
40
|
+
const perClient = labels.map(() => []);
|
|
41
|
+
for (const raw of specs) {
|
|
42
|
+
const m = /^\s*([^:@\s]+)\s*:\s*([A-Za-z]+)\s*@\s*(\d+)\s*(?:ms)?\s*$/.exec(raw);
|
|
43
|
+
if (!m)
|
|
44
|
+
throw new Error(`--at "${raw}": expected ${AT_SYNTAX}`);
|
|
45
|
+
const [, target, rawAction, rawMs] = m;
|
|
46
|
+
const action = rawAction.toLowerCase();
|
|
47
|
+
if (!LIFECYCLE_ACTIONS.includes(action)) {
|
|
48
|
+
throw new Error(`--at "${raw}": unknown action "${rawAction}". Use one of: ${LIFECYCLE_ACTIONS.join(', ')}`);
|
|
49
|
+
}
|
|
50
|
+
const atMs = parseInt(rawMs, 10);
|
|
51
|
+
if (atMs >= holdMs) {
|
|
52
|
+
throw new Error(`--at "${raw}": ${atMs}ms is past the end of the ${holdMs}ms --hold window. Actions must happen inside it (raise --hold, max ${MAX_HOLD_MS}ms, or move the action earlier).`);
|
|
53
|
+
}
|
|
54
|
+
let targets = labels.flatMap((l, i) => (l === target ? [i] : []));
|
|
55
|
+
if (targets.length === 0 && /^\d+$/.test(target) && Number(target) < labels.length)
|
|
56
|
+
targets = [Number(target)];
|
|
57
|
+
if (targets.length === 0) {
|
|
58
|
+
throw new Error(`--at "${raw}": no client "${target}". Use a label (${[...new Set(labels)].join(', ')}) or an index 0-${labels.length - 1}.`);
|
|
59
|
+
}
|
|
60
|
+
for (const i of targets)
|
|
61
|
+
perClient[i].push({ atMs, action });
|
|
62
|
+
}
|
|
63
|
+
perClient.forEach((steps, i) => {
|
|
64
|
+
steps.sort((a, b) => a.atMs - b.atMs);
|
|
65
|
+
const err = sequenceError(steps);
|
|
66
|
+
if (err)
|
|
67
|
+
throw new Error(`--at for client ${i} (${labels[i]}): ${err}`);
|
|
68
|
+
});
|
|
69
|
+
return perClient;
|
|
70
|
+
}
|
|
71
|
+
/** First impossible transition in a time-ordered step list, or null. Freeze
|
|
72
|
+
* already hides the page (as a locking phone does), so hide/freeze don't stack. */
|
|
73
|
+
function sequenceError(steps) {
|
|
74
|
+
const on = { frozen: false, hidden: false, offline: false };
|
|
75
|
+
for (const { action, atMs } of steps) {
|
|
76
|
+
const at = `${action}@${atMs}`;
|
|
77
|
+
if (action === 'freeze') {
|
|
78
|
+
if (on.frozen)
|
|
79
|
+
return `${at}: already frozen`;
|
|
80
|
+
if (on.hidden)
|
|
81
|
+
return `${at}: the page is hidden; show it first (freeze hides the page on its own)`;
|
|
82
|
+
on.frozen = true;
|
|
83
|
+
}
|
|
84
|
+
else if (action === 'wake') {
|
|
85
|
+
if (!on.frozen)
|
|
86
|
+
return `${at}: not frozen (wake undoes freeze)`;
|
|
87
|
+
on.frozen = false;
|
|
88
|
+
}
|
|
89
|
+
else if (action === 'hide') {
|
|
90
|
+
if (on.hidden || on.frozen)
|
|
91
|
+
return `${at}: already ${on.frozen ? 'frozen, which hides the page' : 'hidden'}`;
|
|
92
|
+
on.hidden = true;
|
|
93
|
+
}
|
|
94
|
+
else if (action === 'show') {
|
|
95
|
+
if (!on.hidden)
|
|
96
|
+
return `${at}: not hidden (show undoes hide)`;
|
|
97
|
+
on.hidden = false;
|
|
98
|
+
}
|
|
99
|
+
else if (action === 'offline') {
|
|
100
|
+
if (on.offline)
|
|
101
|
+
return `${at}: already offline`;
|
|
102
|
+
on.offline = true;
|
|
103
|
+
}
|
|
104
|
+
else {
|
|
105
|
+
if (!on.offline)
|
|
106
|
+
return `${at}: not offline (online undoes offline)`;
|
|
107
|
+
on.offline = false;
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
return null;
|
|
111
|
+
}
|
|
112
|
+
function fmtTimeline(events) {
|
|
113
|
+
return events.map((e) => {
|
|
114
|
+
const when = e.appliedMs === null ? `@${e.atMs}ms` : `+${(e.appliedMs / 1000).toFixed(1)}s`;
|
|
115
|
+
const note = e.error ? clrError(` (failed: ${e.error})`) : e.auto ? muted(' (auto, end of hold)') : '';
|
|
116
|
+
return `${e.action} ${when}${note}`;
|
|
117
|
+
}).join(' → ');
|
|
118
|
+
}
|
|
21
119
|
/** Splice per-client values into a user string (URL, --action, or --observe).
|
|
22
120
|
* `{{label}}` → the client's label, `{{i}}` → its 0-based index. Plain string
|
|
23
121
|
* replace (no regex) so the string's own characters are never treated as
|
|
@@ -43,12 +141,12 @@ function unknownTokens(...strings) {
|
|
|
43
141
|
function warnUnknownTokens(unknown) {
|
|
44
142
|
if (unknown.length === 0)
|
|
45
143
|
return;
|
|
46
|
-
console.error(warning(`⚠ Unrecognized placeholder ${unknown.join(', ')} left as-is
|
|
144
|
+
console.error(warning(`⚠ Unrecognized placeholder ${unknown.join(', ')} left as-is: only {{i}} (0-based client index) and {{label}} are substituted per client. Set per-client values with --labels and reference them as {{label}}.`));
|
|
47
145
|
}
|
|
48
146
|
/** Build the statement-body script one client runs: do the one-time action,
|
|
49
147
|
* then sample `observe` `samples` times across `holdMs`, stamping in-page
|
|
50
148
|
* start/end so the caller can confirm the clients overlapped. */
|
|
51
|
-
function buildHarness(action, observe, label, holdMs, samples) {
|
|
149
|
+
export function buildHarness(action, observe, label, holdMs, samples) {
|
|
52
150
|
const n = Math.max(2, samples);
|
|
53
151
|
const interval = Math.max(0, Math.floor(holdMs / (n - 1)));
|
|
54
152
|
const lines = [
|
|
@@ -58,11 +156,17 @@ function buildHarness(action, observe, label, holdMs, samples) {
|
|
|
58
156
|
if (action && action.trim()) {
|
|
59
157
|
lines.push(`try{ ${action} }catch(__e){ return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:[],actionError:String((__e&&__e.message)||__e)}; }`);
|
|
60
158
|
}
|
|
61
|
-
|
|
159
|
+
// Samples are due on a fixed schedule from the first one. A page that could
|
|
160
|
+
// not run when a sample was due (frozen by --at, or blocked) records
|
|
161
|
+
// PAUSED_SAMPLE for each slot it reached more than PAUSE_SLACK_MS late,
|
|
162
|
+
// instead of a stale reading taken the moment it resumes. The slack keeps a
|
|
163
|
+
// hidden page's throttled (about 1/s) timers from reading as paused. The
|
|
164
|
+
// last slot always takes a reading.
|
|
165
|
+
lines.push(`const __s=[]; const __ts=Date.now();`, `for(let __k=0;__k<${n};__k++){`, ` const __w=__ts+__k*${interval}-Date.now();`, ` if(__w>0) await new Promise(function(r){setTimeout(r,__w);});`, ` if(__k<${n - 1}&&Date.now()>__ts+__k*${interval}+${PAUSE_SLACK_MS}){ __s.push(${JSON.stringify(PAUSED_SAMPLE)}); continue; }`, ` let __v; try{ __v=(${observe}); }catch(__e){ __v='ObserveError: '+String((__e&&__e.message)||__e); }`, ` __s.push(__v);`, `}`, `return {label:__label,startedAt:__t0,endedAt:Date.now(),samples:__s};`);
|
|
62
166
|
return lines.join('\n');
|
|
63
167
|
}
|
|
64
168
|
/** Kick off and poll one client's eval job, then parse the harness payload. */
|
|
65
|
-
async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelector) {
|
|
169
|
+
async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelector, lifecycle) {
|
|
66
170
|
const base = { i, label, samples: [], startedAt: 0, endedAt: 0 };
|
|
67
171
|
try {
|
|
68
172
|
const kickoff = await post('/tools/browser/eval', {
|
|
@@ -71,6 +175,9 @@ async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelec
|
|
|
71
175
|
waitMs: settleMs,
|
|
72
176
|
waitForSelector: waitForSelector || undefined,
|
|
73
177
|
waitForTimeoutMs: waitForSelector ? 5000 : undefined,
|
|
178
|
+
// Timed from the start of the observe window; the server restores
|
|
179
|
+
// anything still applied at the end of the hold so the harness finishes.
|
|
180
|
+
lifecycle: lifecycle?.length ? { steps: lifecycle, untilMs: holdMs } : undefined,
|
|
74
181
|
});
|
|
75
182
|
// Server work ≈ nav + settle + the in-page hold; pollEvalResult adds 60s headroom.
|
|
76
183
|
const d = await pollEvalResult(kickoff.data.evalJobId, settleMs + holdMs);
|
|
@@ -88,13 +195,34 @@ async function observeClient(url, expr, i, label, settleMs, holdMs, waitForSelec
|
|
|
88
195
|
if (parsed.actionError) {
|
|
89
196
|
return { ...base, error: `action failed: ${parsed.actionError}` };
|
|
90
197
|
}
|
|
91
|
-
|
|
198
|
+
const startedAt = typeof parsed.startedAt === 'number' ? parsed.startedAt : 0;
|
|
199
|
+
const out = {
|
|
92
200
|
i,
|
|
93
201
|
label: typeof parsed.label === 'string' ? parsed.label : label,
|
|
94
202
|
samples: Array.isArray(parsed.samples) ? parsed.samples : [],
|
|
95
|
-
startedAt
|
|
203
|
+
startedAt,
|
|
96
204
|
endedAt: typeof parsed.endedAt === 'number' ? parsed.endedAt : 0,
|
|
97
205
|
};
|
|
206
|
+
if (lifecycle?.length) {
|
|
207
|
+
// A step that silently didn't happen would make "the handoff works" a
|
|
208
|
+
// false positive, so a missing or failed step fails the client.
|
|
209
|
+
const report = d.lifecycle;
|
|
210
|
+
out.lifecycle = (report?.events ?? []).map((e) => ({
|
|
211
|
+
action: e.action,
|
|
212
|
+
atMs: e.atMs,
|
|
213
|
+
appliedMs: typeof e.appliedAt === 'number' && startedAt > 0 ? e.appliedAt - startedAt : null,
|
|
214
|
+
...(e.auto ? { auto: true } : {}),
|
|
215
|
+
...(e.error ? { error: e.error } : {}),
|
|
216
|
+
}));
|
|
217
|
+
const failed = out.lifecycle.find((e) => e.error);
|
|
218
|
+
if (!report)
|
|
219
|
+
out.error = 'lifecycle actions were not applied (the server did not report them; it may need updating)';
|
|
220
|
+
else if (report.error)
|
|
221
|
+
out.error = `lifecycle actions failed: ${report.error}`;
|
|
222
|
+
else if (failed)
|
|
223
|
+
out.error = `lifecycle ${failed.action}@${failed.atMs} failed: ${failed.error}`;
|
|
224
|
+
}
|
|
225
|
+
return out;
|
|
98
226
|
}
|
|
99
227
|
catch (err) {
|
|
100
228
|
return { ...base, error: err instanceof Error ? err.message : String(err) };
|
|
@@ -111,6 +239,22 @@ function overlapMs(results) {
|
|
|
111
239
|
const end = Math.min(...live.map((r) => r.endedAt));
|
|
112
240
|
return Math.max(0, end - start);
|
|
113
241
|
}
|
|
242
|
+
/** One explanation for an --observe expression that threw, printed once under
|
|
243
|
+
* the client blocks. The bare `ObserveError: Cannot read properties of null`
|
|
244
|
+
* sample reads like a quirk of the harness, so it got waved off as "the observe
|
|
245
|
+
* context is different" when it was a real selector (or app) bug on the live
|
|
246
|
+
* page. Exported for tests. */
|
|
247
|
+
export function observeErrorHint(results) {
|
|
248
|
+
const thrown = results.flatMap((r) => r.samples)
|
|
249
|
+
.find((v) => typeof v === 'string' && v.startsWith('ObserveError:'));
|
|
250
|
+
if (!thrown)
|
|
251
|
+
return null;
|
|
252
|
+
const nullRead = /of null|of undefined/.test(thrown)
|
|
253
|
+
? ' "of null" means a querySelector in it matched nothing at that moment: the element is missing, renamed, or not rendered yet.'
|
|
254
|
+
: '';
|
|
255
|
+
return `ObserveError = your --observe expression threw. It runs against the live deployed page, the same DOM \`page eval\` sees, so this is the page's real state, not a harness quirk.${nullRead} ` +
|
|
256
|
+
"Check the selector with `gipity page eval <url> \"!!document.querySelector('<selector>')\"`, or gate the run on it with --wait-for '<selector>'.";
|
|
257
|
+
}
|
|
114
258
|
function fmtSamples(samples) {
|
|
115
259
|
if (samples.length === 0)
|
|
116
260
|
return muted('(no samples)');
|
|
@@ -124,7 +268,7 @@ async function runInteractive(url, observe, opts) {
|
|
|
124
268
|
if (rawHold > MAX_HOLD_MS) {
|
|
125
269
|
// Surface the clamp (to stderr, so --json stdout stays clean) instead of
|
|
126
270
|
// leaving the agent to infer it from the printed "hold Nms" line.
|
|
127
|
-
console.error(warning(`--hold ${rawHold}ms exceeds the ${MAX_HOLD_MS}ms per-client cap (each client samples inside one browser eval, bounded by the server's eval budget)
|
|
271
|
+
console.error(warning(`--hold ${rawHold}ms exceeds the ${MAX_HOLD_MS}ms per-client cap (each client samples inside one browser eval, bounded by the server's eval budget): using ${MAX_HOLD_MS}ms. ` +
|
|
128
272
|
`Co-launch every role in this one command (put {{label}}/{{i}} in the URL) so all clients overlap for the whole window; a separately-started background client overlaps only the sliver of its window that lines up.`));
|
|
129
273
|
}
|
|
130
274
|
const samples = Math.min(30, Math.max(2, parseInt(opts.samples, 10) || 6));
|
|
@@ -135,9 +279,13 @@ async function runInteractive(url, observe, opts) {
|
|
|
135
279
|
// (a natural guess like {{name}} or {{index}}) so it isn't sent literally to
|
|
136
280
|
// every client — the silent wrong-behavior trap of identical clients.
|
|
137
281
|
warnUnknownTokens(unknownTokens(url, opts.action, observe));
|
|
282
|
+
const atSpecs = opts.at ?? [];
|
|
283
|
+
const lifecycle = parseAtSpecs(atSpecs, Array.from({ length: clients }, (_, i) => labelFor(i)), hold);
|
|
138
284
|
if (!opts.json) {
|
|
139
285
|
console.log(`${brand('Page test')} ${muted('(interactive)')} ${bold(url)}`);
|
|
140
286
|
console.log(muted(`${clients} client(s), stagger ${stagger}s, hold ${hold}ms, ${samples} samples each`));
|
|
287
|
+
if (atSpecs.length)
|
|
288
|
+
console.log(muted(`lifecycle (ms into each client's hold): ${atSpecs.map((s) => s.trim()).join(', ')}`));
|
|
141
289
|
}
|
|
142
290
|
const runs = [];
|
|
143
291
|
for (let i = 0; i < clients; i++) {
|
|
@@ -150,7 +298,7 @@ async function runInteractive(url, observe, opts) {
|
|
|
150
298
|
// and the overlap check still confirms they coexisted.
|
|
151
299
|
const clientUrl = subst(url, labelFor(i), i);
|
|
152
300
|
const expr = buildHarness(opts.action ? subst(opts.action, labelFor(i), i) : undefined, subst(observe, labelFor(i), i), labelFor(i), hold, samples);
|
|
153
|
-
return observeClient(clientUrl, expr, i, labelFor(i), settle, hold, opts.waitFor);
|
|
301
|
+
return observeClient(clientUrl, expr, i, labelFor(i), settle, hold, opts.waitFor, lifecycle[i]);
|
|
154
302
|
})());
|
|
155
303
|
}
|
|
156
304
|
const results = (await Promise.all(runs)).sort((a, b) => a.i - b.i);
|
|
@@ -160,6 +308,7 @@ async function runInteractive(url, observe, opts) {
|
|
|
160
308
|
if (opts.json) {
|
|
161
309
|
console.log(JSON.stringify({
|
|
162
310
|
url, mode: 'interactive', clients, stagger, hold, samples,
|
|
311
|
+
...(atSpecs.length ? { at: atSpecs.map((s) => s.trim()) } : {}),
|
|
163
312
|
overlapMs: ovl, overlapped, results,
|
|
164
313
|
}));
|
|
165
314
|
if (errored.length > 0 || (clients > 1 && !overlapped))
|
|
@@ -168,24 +317,29 @@ async function runInteractive(url, observe, opts) {
|
|
|
168
317
|
}
|
|
169
318
|
for (const r of results) {
|
|
170
319
|
console.log(`\n${bold(`=== client ${r.i} (${r.label}) ===`)}`);
|
|
320
|
+
if (r.lifecycle?.length)
|
|
321
|
+
console.log(`${muted('timeline:')} ${fmtTimeline(r.lifecycle)}`);
|
|
171
322
|
if (r.error) {
|
|
172
323
|
console.log(clrError(`✗ ${r.error}`));
|
|
173
324
|
continue;
|
|
174
325
|
}
|
|
175
326
|
console.log(`${muted('samples:')} ${fmtSamples(r.samples)}`);
|
|
176
327
|
}
|
|
328
|
+
const observeHint = observeErrorHint(results);
|
|
329
|
+
if (observeHint)
|
|
330
|
+
console.log(`\n${warning(observeHint)}`);
|
|
177
331
|
console.log('');
|
|
178
332
|
if (errored.length > 0) {
|
|
179
333
|
console.log(clrError(`⚠ ${errored.length} client(s) failed (see above)`));
|
|
180
334
|
}
|
|
181
335
|
if (clients < 2) {
|
|
182
|
-
console.log(muted('Note: a single client cannot verify cross-client visibility
|
|
336
|
+
console.log(muted('Note: a single client cannot verify cross-client visibility: run with --clients 2+.'));
|
|
183
337
|
}
|
|
184
338
|
else if (overlapped) {
|
|
185
|
-
console.log(success(`✓ all clients overlapped for ~${(ovl / 1000).toFixed(1)}s
|
|
339
|
+
console.log(success(`✓ all clients overlapped for ~${(ovl / 1000).toFixed(1)}s: genuine concurrency, so the readings above are trustworthy`));
|
|
186
340
|
}
|
|
187
341
|
else {
|
|
188
|
-
console.log(clrError('⚠ clients did NOT overlap in time
|
|
342
|
+
console.log(clrError('⚠ clients did NOT overlap in time: each ran in isolation, so any shared-state reading here is a FALSE NEGATIVE, not proof the app is broken.'));
|
|
189
343
|
console.log(muted(' Likely causes: --stagger ≥ --hold, or more --clients than free browser slots (they queued). Lower --stagger / raise --hold / fewer --clients and retry.'));
|
|
190
344
|
}
|
|
191
345
|
if (errored.length > 0 || (clients > 1 && !overlapped))
|
|
@@ -272,13 +426,14 @@ export const pageTestCommand = new Command('test')
|
|
|
272
426
|
.option('--hold <ms>', `Interactive: total observe window per client (${MIN_HOLD_MS}-${MAX_HOLD_MS}ms)`, '8000')
|
|
273
427
|
.option('--samples <k>', 'Interactive: number of observations across the hold window (2-30)', '6')
|
|
274
428
|
.option('--wait-for <selector>', 'Interactive: wait for this CSS selector before running --action (deterministic readiness gate)')
|
|
429
|
+
.option('--at <spec>', `Interactive: lifecycle action on one client mid-run, "<label|index>:<action>@<ms>" (ms into that client's hold window). Actions: freeze|wake (locked phone: JS stops, socket stays open), hide|show (backgrounded tab), offline|online (network drop). Repeatable; anything still applied at the end of --hold is restored.`, (v, prev = []) => [...prev, v])
|
|
275
430
|
.option('--json', 'Output as JSON')
|
|
276
431
|
.addHelpText('after', `
|
|
277
432
|
Examples:
|
|
278
433
|
# Passive: load in 3 staggered clients, flag console errors
|
|
279
434
|
gipity page test "https://dev.gipity.ai/me/app/" --clients 3 --stagger 8
|
|
280
435
|
|
|
281
|
-
# Per-client URL params: each client joins under a distinct name (Bot0, Bot1,
|
|
436
|
+
# Per-client URL params: each client joins under a distinct name (Bot0, Bot1, ...)
|
|
282
437
|
gipity page test "https://dev.gipity.ai/me/app/?name=Bot{{i}}" --clients 2
|
|
283
438
|
|
|
284
439
|
# Interactive: two concurrent clients each join with a name, then watch the
|
|
@@ -290,11 +445,30 @@ Examples:
|
|
|
290
445
|
|
|
291
446
|
# Asymmetric roles in ONE invocation: {{label}} in the URL routes client 0 to
|
|
292
447
|
# host and client 1 to join. They overlap in time (verified), so the joiner
|
|
293
|
-
# observes the live state the host is driving
|
|
448
|
+
# observes the live state the host is driving: no background-process dance.
|
|
294
449
|
gipity page test "https://dev.gipity.ai/me/app/?test-action={{label}}" --clients 2 \\
|
|
295
450
|
--labels host,join \\
|
|
296
|
-
--observe "document.querySelector('[data-screen]')?.dataset.screen"
|
|
451
|
+
--observe "document.querySelector('[data-screen]')?.dataset.screen"
|
|
452
|
+
|
|
453
|
+
# Host handoff: lock the host's phone 5s in (its JS stops, its socket stays
|
|
454
|
+
# open, so nobody sees a leave) and watch who the phones think is host.
|
|
455
|
+
gipity page test "https://dev.gipity.ai/me/app/?role={{label}}" --clients 3 \\
|
|
456
|
+
--labels host,phone,phone --hold 15000 --at host:freeze@5000 --at host:wake@12000 \\
|
|
457
|
+
--observe "window.game?.hostId"
|
|
458
|
+
|
|
459
|
+
freeze: the page's JS stops (timers, rendering, message handlers) and it fires
|
|
460
|
+
visibilitychange (hidden) then freeze, like a phone locking. Its WebSocket stays
|
|
461
|
+
open, so the server sees no leave. On wake the page resumes and Chrome drops that
|
|
462
|
+
socket (close code 1006), so the app's reconnect path runs. Samples due while a
|
|
463
|
+
client was frozen read (paused).
|
|
464
|
+
hide: backgrounded tab (document.hidden, rAF stops, timers throttle to ~1/s); JS
|
|
465
|
+
and the socket keep running.
|
|
466
|
+
offline: navigator.onLine false, new requests fail, and an open WebSocket stalls
|
|
467
|
+
without closing; online delivers the held traffic.`)
|
|
297
468
|
.action((url, opts) => run('Page test', async () => {
|
|
469
|
+
if (opts.at?.length && !opts.observe) {
|
|
470
|
+
throw new Error('--at needs interactive mode: add --observe "<expr>" to watch what the other clients do while one is frozen, hidden, or offline');
|
|
471
|
+
}
|
|
298
472
|
if (opts.observe) {
|
|
299
473
|
await runInteractive(url, opts.observe, opts);
|
|
300
474
|
}
|