recovery-probe 1.1.0-preview.2 → 1.1.0-preview.4
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/CHANGELOG.md +13 -0
- package/README.md +2 -0
- package/dist/cli/net.d.mts +3 -0
- package/dist/cli/net.mjs +17 -2
- package/dist/cli/observe.mjs +19 -8
- package/dist/core/regexp.d.mts +2 -0
- package/dist/core/regexp.mjs +2 -0
- package/dist/core/region-read.d.mts +4 -1
- package/dist/core/region-read.mjs +12 -9
- package/dist/hook/probe.cjs +4 -21
- package/dist/hook/types.d.cts +7 -0
- package/dist/hook/window.cjs +39 -0
- package/dist/hook/window.d.cts +16 -0
- package/dist/reports/templates/observation.html +1 -0
- package/dist/targets/visibility.d.mts +3 -1
- package/dist/targets/visibility.mjs +34 -4
- package/dist/transports/ipc/inspector.d.mts +6 -1
- package/dist/transports/ipc/inspector.mjs +1 -0
- package/dist/workflows/observe/capture.mjs +9 -0
- package/dist/workflows/observe/config.d.mts +9 -0
- package/dist/workflows/observe/config.mjs +13 -0
- package/dist/workflows/observe/file-faults.mjs +4 -11
- package/dist/workflows/observe/files.d.mts +1 -1
- package/dist/workflows/observe/files.mjs +3 -7
- package/dist/workflows/observe/kit.d.mts +8 -0
- package/dist/workflows/observe/kit.mjs +42 -0
- package/dist/workflows/observe/network.d.mts +1 -1
- package/dist/workflows/observe/network.mjs +4 -11
- package/dist/workflows/observe/page-input.mjs +1 -0
- package/dist/workflows/observe/recorder.mjs +3 -6
- package/dist/workflows/observe/render.mjs +23 -11
- package/dist/workflows/observe/report.d.mts +45 -3
- package/dist/workflows/observe/report.mjs +19 -0
- package/dist/workflows/observe/requests.d.mts +13 -0
- package/dist/workflows/observe/requests.mjs +58 -0
- package/dist/workflows/observe/sample.d.mts +10 -0
- package/dist/workflows/observe/sample.mjs +38 -0
- package/dist/workflows/observe/session.d.mts +14 -0
- package/dist/workflows/observe/session.mjs +36 -6
- package/dist/workflows/observe/spans.d.mts +51 -0
- package/dist/workflows/observe/spans.mjs +115 -0
- package/dist/workflows/observe/step-runner.d.mts +2 -1
- package/dist/workflows/observe/step-runner.mjs +12 -5
- package/dist/workflows/observe/steps.d.mts +18 -0
- package/dist/workflows/observe/steps.mjs +31 -2
- package/dist/workflows/observe/summaries.d.mts +8 -1
- package/dist/workflows/observe/summaries.mjs +41 -0
- package/docs/ipc.md +1 -1
- package/docs/mcp-demo.md +31 -0
- package/docs/mcp.md +9 -5
- package/docs/net.md +1 -1
- package/docs/observe.md +33 -0
- package/examples/mcp-demo.mjs +117 -0
- package/package.json +7 -4
- package/server.json +33 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,19 @@ All notable changes to Recovery Probe are documented here. The project follows [
|
|
|
4
4
|
|
|
5
5
|
Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
|
|
6
6
|
|
|
7
|
+
## 1.1.0-preview.4 (2026-11-14)
|
|
8
|
+
|
|
9
|
+
- `net` warns on stderr when no connection has reached the proxy after 30 seconds, and its summary says so when none did, with the `HTTPS_PROXY` value to start the app with. Before, a proxy the app never used ran silently until it stopped.
|
|
10
|
+
- `observe --steps` can fail the page's own requests, such as its images or reads: `{ "requests": { "url": "**/images/**", "fault": "abort" } }`, or `"fault": "status"` with a status from 400 to 599. A later step replaces the rules, `"restore"` removes them, and the capture removes them when it ends. The report counts what each rule failed under `requests`. A rule that failed nothing adds `REQUEST_FAULT_NOT_TRIGGERED`, and rules that could not be removed add `REQUEST_FAULTS_NOT_RESTORED`.
|
|
11
|
+
- `observe` with `spans` lists the OpenTelemetry spans the page exports over OTLP/HTTP JSON during the capture: matching names, timings, status, the interval each started in, and the values of allowlisted attributes only. With `contentImages`, each span says how long before or after the content fully loaded it ended, so an app's own load-time measurement can be checked against the screen.
|
|
12
|
+
- `observe` with `contentImages` counts the images inside the content marker's elements, `<img>` elements and CSS background images, in every sample. Each interval records `contentLoaded`: when the content last became fully loaded, with every image loaded or failed, and stayed unchanged. The terminal and HTML report show it per interval.
|
|
13
|
+
|
|
14
|
+
## 1.1.0-preview.3 (2026-11-13)
|
|
15
|
+
|
|
16
|
+
- `observe` checks the target window when the capture starts and says when the page is hidden or draws no frames, the usual reason a click step times out. `restoreWindow` un-minimizes the window for the capture, and `keepRendering` (IPC) keeps a minimized or covered window drawing where it is by turning off its background throttling through the development hook. Both put the window back afterwards, and the report records it under `window`. The hook gains a `setBackgroundThrottling` control. `check`, `discover`, `action` and `refresh` now also warn about a hidden page, not only one that reports itself visible but draws nothing. These window messages now go to stderr, so `--json` output on stdout stays parseable.
|
|
17
|
+
- Add MCP Registry ownership and launch metadata with stable-only OIDC publication.
|
|
18
|
+
- Add a reproducible stdio MCP retry demonstration and clarify unattended setup and dependencies.
|
|
19
|
+
|
|
7
20
|
## 1.1.0-preview.2 (2026-10-28)
|
|
8
21
|
|
|
9
22
|
- Reject browser-origin WebSocket connections and untrusted Host headers on the Android CDP bridge before opening an upstream connection. Validate the network proxy control API's Host header to block DNS rebinding.
|
package/README.md
CHANGED
|
@@ -22,6 +22,8 @@ npx playwright install chromium
|
|
|
22
22
|
npx recovery-probe demo
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
+
The next preview, `1.1.0-preview.4`, adds content-image load timing, request fault steps, exported span observation, and idle proxy warnings. After publication, install it with `npm install --save-dev recovery-probe@next playwright`. Until then, use the [source installation instructions](CONTRIBUTING.md#install-an-unpublished-source-preview).
|
|
26
|
+
|
|
25
27
|
The demo runs two versions of a small app. Both load fine. Only the fixed one survives a 503, a dropped connection and a broken JSON response.
|
|
26
28
|
|
|
27
29
|
## Check your own app
|
package/dist/cli/net.d.mts
CHANGED
|
@@ -1 +1,4 @@
|
|
|
1
|
+
import type { NetworkFaultProxy } from '../transports/net/types.mjs';
|
|
1
2
|
export declare function netMain(args: string[]): Promise<void>;
|
|
3
|
+
/** Warns once when no connection reached the proxy within `delayMs`; returns a function that cancels it. */
|
|
4
|
+
export declare function warnIfIdle(proxy: Pick<NetworkFaultProxy, 'summary' | 'url'>, delayMs: number, warn?: (message: string) => void): () => void;
|
package/dist/cli/net.mjs
CHANGED
|
@@ -3,6 +3,8 @@ import { startNetworkFaultProxy } from '../transports/net/proxy.mjs';
|
|
|
3
3
|
import { validateNetworkRules } from '../transports/net/rules.mjs';
|
|
4
4
|
import { untilStopped } from './until-stopped.mjs';
|
|
5
5
|
import { integerOption, parseOptions, text } from './args.mjs';
|
|
6
|
+
// An app that is not running, or ignores HTTPS_PROXY, leaves the proxy silent.
|
|
7
|
+
const IDLE_WARNING_MS = 30_000;
|
|
6
8
|
const USAGE = 'recovery-probe net [--rules FILE] [--port N] [--duration MS] [--out FILE] [--json]';
|
|
7
9
|
const HELP = `${USAGE}
|
|
8
10
|
|
|
@@ -64,12 +66,14 @@ export async function netMain(args) {
|
|
|
64
66
|
control: true,
|
|
65
67
|
});
|
|
66
68
|
const printFaults = faultPrinter(proxy);
|
|
69
|
+
const stopIdleWarning = warnIfIdle(proxy, IDLE_WARNING_MS);
|
|
67
70
|
let watch;
|
|
68
71
|
if (!options.json) {
|
|
69
72
|
printStart(proxy, rules);
|
|
70
73
|
watch = setInterval(printFaults, 250);
|
|
71
74
|
}
|
|
72
75
|
await untilStopped(options.duration);
|
|
76
|
+
stopIdleWarning();
|
|
73
77
|
clearInterval(watch);
|
|
74
78
|
if (!options.json)
|
|
75
79
|
printFaults();
|
|
@@ -80,7 +84,7 @@ export async function netMain(args) {
|
|
|
80
84
|
if (options.json)
|
|
81
85
|
console.log(JSON.stringify(report, null, 2));
|
|
82
86
|
else
|
|
83
|
-
printSummary(report);
|
|
87
|
+
printSummary(report, proxy.url);
|
|
84
88
|
process.exitCode = report.ok ? 0 : 2;
|
|
85
89
|
}
|
|
86
90
|
async function readRules(path) {
|
|
@@ -89,6 +93,15 @@ async function readRules(path) {
|
|
|
89
93
|
const parsed = JSON.parse(await readFile(path, 'utf8'));
|
|
90
94
|
return validateNetworkRules(Array.isArray(parsed) ? parsed : parsed?.rules);
|
|
91
95
|
}
|
|
96
|
+
const startHint = (url) => `Is the app running, and was it started with HTTPS_PROXY=${url}?`;
|
|
97
|
+
/** Warns once when no connection reached the proxy within `delayMs`; returns a function that cancels it. */
|
|
98
|
+
export function warnIfIdle(proxy, delayMs, warn = (message) => console.error(message)) {
|
|
99
|
+
const timer = setTimeout(() => {
|
|
100
|
+
if (proxy.summary().connections === 0)
|
|
101
|
+
warn(`Recovery Probe: no connection has reached the proxy in ${delayMs / 1000} s. ${startHint(proxy.url)}`);
|
|
102
|
+
}, delayMs);
|
|
103
|
+
return () => clearTimeout(timer);
|
|
104
|
+
}
|
|
92
105
|
/** Prints the faulted connections since its last call. */
|
|
93
106
|
function faultPrinter(proxy) {
|
|
94
107
|
let printed = 0;
|
|
@@ -130,8 +143,10 @@ function netReport(proxy, rules) {
|
|
|
130
143
|
eventsDropped: summary.eventsDropped,
|
|
131
144
|
};
|
|
132
145
|
}
|
|
133
|
-
function printSummary(report) {
|
|
146
|
+
function printSummary(report, url) {
|
|
134
147
|
console.log(`\n${report.connections} connection(s) through the proxy`);
|
|
148
|
+
if (report.connections === 0)
|
|
149
|
+
console.log(`No connection reached the proxy. ${startHint(url)}`);
|
|
135
150
|
report.rules.forEach((rule, index) => console.log(` rule ${index + 1}: ${rule.fault} ${rule.host} faulted ${rule.applied} of ${rule.matching} matching`));
|
|
136
151
|
if (!report.ok)
|
|
137
152
|
console.log('\nFAULT_NOT_TRIGGERED: a rule faulted no connection. Check that the app uses HTTPS_PROXY and the host names.');
|
package/dist/cli/observe.mjs
CHANGED
|
@@ -4,7 +4,7 @@ import { resolve, join } from 'node:path';
|
|
|
4
4
|
import { createInterface } from 'node:readline';
|
|
5
5
|
import { observationConfig, } from '../workflows/observe/config.mjs';
|
|
6
6
|
import { connectNetworkSteps, observeSession, } from '../workflows/observe/session.mjs';
|
|
7
|
-
import { observationSummary, actionSummary, networkStepSummary, fileFaultSummary, } from '../workflows/observe/summaries.mjs';
|
|
7
|
+
import { observationSummary, actionSummary, networkStepSummary, requestStepSummary, fileFaultSummary, contentLoadedSummary, spanNotes, spanSummary, } from '../workflows/observe/summaries.mjs';
|
|
8
8
|
import { renderObservationReport } from '../workflows/observe/render.mjs';
|
|
9
9
|
import { comparisonDigest } from '../workflows/observe/comparisons.mjs';
|
|
10
10
|
import { observationSteps, } from '../workflows/observe/steps.mjs';
|
|
@@ -26,8 +26,9 @@ UNEXPECTED_ROW_STATE reports a tracked row shown in a state listed in rows.unexp
|
|
|
26
26
|
--steps runs an explicit, opt-in list of same-document navigations, clicks, waits,
|
|
27
27
|
expectations and interval marks during the capture. Steps act on the app: use a
|
|
28
28
|
test account. An expect step that sees nothing in time adds EXPECTATION_NOT_MET.
|
|
29
|
+
Request steps fail the page's own requests, such as its images, by URL glob;
|
|
29
30
|
--network names a running recovery-probe net, so network steps can fail the app's
|
|
30
|
-
own HTTPS connections
|
|
31
|
+
own HTTPS connections. Both are removed when the capture ends.
|
|
31
32
|
--files compares a directory's files at each interval and reports files the app
|
|
32
33
|
removed or shrank (LOCAL_FILES_REMOVED, a lead). Paths stay in a private files.json.
|
|
33
34
|
File steps remove, truncate or corrupt a file under it; a file the app has not
|
|
@@ -100,6 +101,7 @@ async function readInputs(options) {
|
|
|
100
101
|
const steps = options.steps
|
|
101
102
|
? await readConfig(options.steps, (list) => observationSteps(list, {
|
|
102
103
|
network: Boolean(options.network),
|
|
104
|
+
requests: true,
|
|
103
105
|
files: Boolean(options.files),
|
|
104
106
|
}))
|
|
105
107
|
: null;
|
|
@@ -171,6 +173,8 @@ async function writeObservation(directory, config, steps, { report, files }) {
|
|
|
171
173
|
function printObservation(report, config, directory) {
|
|
172
174
|
const lines = [
|
|
173
175
|
...report.intervals.map(intervalLine),
|
|
176
|
+
...(report.spans?.spans ?? []).map((span) => `Span ${spanSummary(span)}`),
|
|
177
|
+
...(report.spans ? spanNotes(report.spans) : []),
|
|
174
178
|
...report.findings.map(findingLine),
|
|
175
179
|
...(report.actionEffects ?? []).map(actionSummary),
|
|
176
180
|
...comparisonDigest(report),
|
|
@@ -184,9 +188,11 @@ function printObservation(report, config, directory) {
|
|
|
184
188
|
console.error(report.error);
|
|
185
189
|
console.log(`Capture: ${report.status} (not a health verdict)\nReport: ${join(directory, 'report.html')}`);
|
|
186
190
|
}
|
|
187
|
-
function intervalLine(
|
|
191
|
+
function intervalLine(interval) {
|
|
192
|
+
const { index, reads, findings } = interval;
|
|
188
193
|
const raised = findings.length ? '; ' + findings.join(', ') : '';
|
|
189
|
-
|
|
194
|
+
const loaded = contentLoadedSummary(interval);
|
|
195
|
+
return `Interval ${index}: ${reads?.calls ?? '?'} reads, ${reads?.successes ?? '?'} successes, ${reads?.errors ?? '?'} errors${loaded ? '; ' + loaded : ''}${raised}`;
|
|
190
196
|
}
|
|
191
197
|
function findingLine(finding) {
|
|
192
198
|
const code = NAMED_FINDINGS.includes(finding.code) ? `${finding.code} — ` : '';
|
|
@@ -195,10 +201,15 @@ function findingLine(finding) {
|
|
|
195
201
|
function printStepOutcomes(report) {
|
|
196
202
|
if (report.operator)
|
|
197
203
|
console.log(`Scripted steps: ${report.operator.status}${report.operator.error ? ' — ' + report.operator.error : ''}`);
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
if (report.network?.restoreError)
|
|
201
|
-
console.error(`Network faults were not removed: ${report.network.restoreError}. Stop recovery-probe net to restore the app's network.`);
|
|
204
|
+
printFaults(report.network, networkStepSummary, (error) => `Network faults were not removed: ${error}. Stop recovery-probe net to restore the app's network.`);
|
|
205
|
+
printFaults(report.requests, requestStepSummary, (error) => `Request faults were not removed: ${error}.`);
|
|
202
206
|
for (const record of report.fileFaults ?? [])
|
|
203
207
|
console.log(fileFaultSummary(record));
|
|
204
208
|
}
|
|
209
|
+
/** What each fault step did, and an error when its faults could not be removed. */
|
|
210
|
+
function printFaults(evidence, summary, unrestored) {
|
|
211
|
+
for (const record of evidence?.faults ?? [])
|
|
212
|
+
console.log(summary(record));
|
|
213
|
+
if (evidence?.restoreError)
|
|
214
|
+
console.error(unrestored(evidence.restoreError));
|
|
215
|
+
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { RecordedAction } from '../workflows/observe/kit.mjs';
|
|
1
|
+
import type { ContentImages, RecordedAction } from '../workflows/observe/kit.mjs';
|
|
2
2
|
import type { SelectorSpec } from './selector.mjs';
|
|
3
3
|
/** What an observation reads; a plain region selector reads the region alone. */
|
|
4
4
|
export interface ObservationReadInput {
|
|
@@ -6,6 +6,8 @@ export interface ObservationReadInput {
|
|
|
6
6
|
contentSelector: SelectorSpec;
|
|
7
7
|
detail?: string;
|
|
8
8
|
kitToken?: string;
|
|
9
|
+
/** Also counts the images inside the matched content. */
|
|
10
|
+
images?: boolean;
|
|
9
11
|
rows?: {
|
|
10
12
|
selector: SelectorSpec;
|
|
11
13
|
key?: SelectorSpec;
|
|
@@ -22,6 +24,7 @@ export interface RegionRead {
|
|
|
22
24
|
texts: string[];
|
|
23
25
|
truncated: boolean;
|
|
24
26
|
};
|
|
27
|
+
contentImages?: ContentImages;
|
|
25
28
|
rows?: {
|
|
26
29
|
truncated: boolean;
|
|
27
30
|
/** `marker` is the index of the first configured marker found in the row. */
|
|
@@ -52,18 +52,21 @@ export function readRegion(selector) {
|
|
|
52
52
|
const contentOf = (root, spec) => {
|
|
53
53
|
const matches = select(root, spec);
|
|
54
54
|
const texts = [];
|
|
55
|
+
const elements = [];
|
|
55
56
|
let remaining = 200000;
|
|
56
57
|
let truncated = matches.length > 1000;
|
|
57
58
|
for (const e of [...matches].slice(0, 1000)) {
|
|
58
59
|
if (!visible(e))
|
|
59
60
|
continue;
|
|
61
|
+
elements.push(e);
|
|
60
62
|
const text = innerText(e);
|
|
61
63
|
if (text.length > remaining)
|
|
62
64
|
truncated = true;
|
|
63
65
|
texts.push(text.slice(0, remaining));
|
|
64
66
|
remaining = Math.max(0, remaining - text.length);
|
|
65
67
|
}
|
|
66
|
-
|
|
68
|
+
// The elements stay in the page: only the texts are returned.
|
|
69
|
+
return { content: { texts, truncated }, elements };
|
|
67
70
|
};
|
|
68
71
|
// Row key and state text are returned transiently; Node hashes keys and keeps only allowlisted states.
|
|
69
72
|
const rowsOf = (root, r) => {
|
|
@@ -172,8 +175,7 @@ export function readRegion(selector) {
|
|
|
172
175
|
? {
|
|
173
176
|
presence: 'visible',
|
|
174
177
|
contentCount: observed.content.texts.length,
|
|
175
|
-
|
|
176
|
-
rows: observed.rows,
|
|
178
|
+
...observed,
|
|
177
179
|
}
|
|
178
180
|
: {}),
|
|
179
181
|
region: regionSelector
|
|
@@ -187,12 +189,11 @@ export function readRegion(selector) {
|
|
|
187
189
|
...indicatorsOf(root, text),
|
|
188
190
|
};
|
|
189
191
|
};
|
|
190
|
-
const contentRead = (
|
|
192
|
+
const contentRead = (observed) => ({
|
|
191
193
|
presence: 'visible',
|
|
192
|
-
contentCount: content.texts.length,
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
truncated: content.truncated,
|
|
194
|
+
contentCount: observed.content.texts.length,
|
|
195
|
+
...observed,
|
|
196
|
+
truncated: observed.content.truncated,
|
|
196
197
|
...page(),
|
|
197
198
|
});
|
|
198
199
|
const read = () => {
|
|
@@ -210,9 +211,11 @@ export function readRegion(selector) {
|
|
|
210
211
|
return structuralRead(root, regionSelector);
|
|
211
212
|
if (!visible(root))
|
|
212
213
|
return { presence: 'hidden', contentCount: 0, ...page() };
|
|
214
|
+
const { content, elements } = contentOf(root, observation.contentSelector);
|
|
213
215
|
const observed = {
|
|
214
|
-
content
|
|
216
|
+
content,
|
|
215
217
|
rows: observation.rows ? rowsOf(root, observation.rows) : undefined,
|
|
218
|
+
...(observation.images ? { contentImages: kit?.imagesIn(elements) } : {}),
|
|
216
219
|
};
|
|
217
220
|
return observation.detail === 'content'
|
|
218
221
|
? contentRead(observed)
|
package/dist/hook/probe.cjs
CHANGED
|
@@ -6,6 +6,7 @@ const checks_cjs_1 = require("./checks.cjs");
|
|
|
6
6
|
const pushes_cjs_1 = require("./pushes.cjs");
|
|
7
7
|
const state_cjs_1 = require("./state.cjs");
|
|
8
8
|
const stats_cjs_1 = require("./stats.cjs");
|
|
9
|
+
const window_cjs_1 = require("./window.cjs");
|
|
9
10
|
const installed = new WeakSet();
|
|
10
11
|
// No Electron import: use its public registration API, supplied by the development app.
|
|
11
12
|
function installIpcProbe(
|
|
@@ -30,6 +31,7 @@ class ProbeHook {
|
|
|
30
31
|
#registered = new Set();
|
|
31
32
|
#seenIds = new Set();
|
|
32
33
|
#pushes;
|
|
34
|
+
#windows;
|
|
33
35
|
#active = true;
|
|
34
36
|
#state = null;
|
|
35
37
|
#timer;
|
|
@@ -37,6 +39,7 @@ class ProbeHook {
|
|
|
37
39
|
this.#ipcMain = ipcMain;
|
|
38
40
|
this.#original = ipcMain.handle;
|
|
39
41
|
this.#sender = settings.sender;
|
|
42
|
+
this.#windows = (0, window_cjs_1.windowControls)(settings.sender);
|
|
40
43
|
this.#classify = settings.classify;
|
|
41
44
|
this.#allowed = new Set(settings.channels);
|
|
42
45
|
this.#allowedPushes = new Set(settings.pushChannels);
|
|
@@ -50,8 +53,7 @@ class ProbeHook {
|
|
|
50
53
|
identify: ((challenge) => this.identify(challenge)),
|
|
51
54
|
begin: (options) => this.begin(options),
|
|
52
55
|
snapshot: () => this.snapshot(),
|
|
53
|
-
|
|
54
|
-
setWindowMinimized: (minimized) => this.setWindowMinimized(minimized),
|
|
56
|
+
...this.#windows,
|
|
55
57
|
reset: (id) => this.reset(id),
|
|
56
58
|
dispose: () => this.dispose(),
|
|
57
59
|
};
|
|
@@ -114,19 +116,6 @@ class ProbeHook {
|
|
|
114
116
|
? JSON.parse(JSON.stringify({ ...state, capturedAt: Date.now() }))
|
|
115
117
|
: null;
|
|
116
118
|
}
|
|
117
|
-
windowState() {
|
|
118
|
-
return { minimized: this.#window().isMinimized() };
|
|
119
|
-
}
|
|
120
|
-
setWindowMinimized(minimized) {
|
|
121
|
-
if (typeof minimized !== 'boolean')
|
|
122
|
-
throw new Error('Expected boolean window state');
|
|
123
|
-
const window = this.#window();
|
|
124
|
-
if (minimized)
|
|
125
|
-
window.minimize();
|
|
126
|
-
else
|
|
127
|
-
window.restore();
|
|
128
|
-
return { minimized: window.isMinimized() };
|
|
129
|
-
}
|
|
130
119
|
reset(id) {
|
|
131
120
|
if (id !== undefined && this.#state && id !== this.#state.id)
|
|
132
121
|
throw new Error('Stale run ID');
|
|
@@ -149,12 +138,6 @@ class ProbeHook {
|
|
|
149
138
|
if (previous && Object.values(previous.channels).some((c) => c.pending))
|
|
150
139
|
throw new Error('Previous real calls are still pending; wait before beginning another run');
|
|
151
140
|
}
|
|
152
|
-
#window() {
|
|
153
|
-
const window = this.#sender()?.getOwnerBrowserWindow?.();
|
|
154
|
-
if (!window || window.isDestroyed())
|
|
155
|
-
throw new Error('Window control unavailable');
|
|
156
|
-
return window;
|
|
157
|
-
}
|
|
158
141
|
#disarm() {
|
|
159
142
|
clearTimeout(this.#timer);
|
|
160
143
|
this.#pushes.unwrap();
|
package/dist/hook/types.d.cts
CHANGED
|
@@ -5,6 +5,9 @@ export interface ProbeWebContents {
|
|
|
5
5
|
getURL(): string;
|
|
6
6
|
executeJavaScript(code: string): Promise<unknown>;
|
|
7
7
|
send?(channel: string, ...args: unknown[]): void;
|
|
8
|
+
/** Used for the opt-in control that keeps a minimized or covered window drawing frames. */
|
|
9
|
+
setBackgroundThrottling?(allowed: boolean): void;
|
|
10
|
+
getBackgroundThrottling?(): boolean;
|
|
8
11
|
/** Used for the opt-in window minimize/restore controls. */
|
|
9
12
|
getOwnerBrowserWindow?(): {
|
|
10
13
|
isDestroyed(): boolean;
|
|
@@ -109,6 +112,10 @@ export interface IpcProbe {
|
|
|
109
112
|
setWindowMinimized(minimized: boolean): {
|
|
110
113
|
minimized: boolean;
|
|
111
114
|
};
|
|
115
|
+
setBackgroundThrottling(allowed: boolean): {
|
|
116
|
+
allowed: boolean;
|
|
117
|
+
previous: boolean;
|
|
118
|
+
};
|
|
112
119
|
reset(id?: string): IpcSnapshot | null;
|
|
113
120
|
dispose(): void;
|
|
114
121
|
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.windowControls = windowControls;
|
|
4
|
+
function windowControls(sender) {
|
|
5
|
+
const window = () => {
|
|
6
|
+
const owner = sender()?.getOwnerBrowserWindow?.();
|
|
7
|
+
if (!owner || owner.isDestroyed())
|
|
8
|
+
throw new Error('Window control unavailable');
|
|
9
|
+
return owner;
|
|
10
|
+
};
|
|
11
|
+
return {
|
|
12
|
+
windowState: () => ({ minimized: window().isMinimized() }),
|
|
13
|
+
setWindowMinimized(minimized) {
|
|
14
|
+
if (typeof minimized !== 'boolean')
|
|
15
|
+
throw new Error('Expected boolean window state');
|
|
16
|
+
const owner = window();
|
|
17
|
+
if (minimized)
|
|
18
|
+
owner.minimize();
|
|
19
|
+
else
|
|
20
|
+
owner.restore();
|
|
21
|
+
return { minimized: owner.isMinimized() };
|
|
22
|
+
},
|
|
23
|
+
/** Throttled, a minimized or covered window draws no frames, so clicks wait forever. */
|
|
24
|
+
setBackgroundThrottling(allowed) {
|
|
25
|
+
if (typeof allowed !== 'boolean')
|
|
26
|
+
throw new Error('Expected boolean background throttling');
|
|
27
|
+
const contents = sender();
|
|
28
|
+
if (!contents?.setBackgroundThrottling || contents.isDestroyed())
|
|
29
|
+
throw new Error('Rendering control unavailable');
|
|
30
|
+
// Electron throttles by default; older versions cannot report it.
|
|
31
|
+
const previous = contents.getBackgroundThrottling?.() ?? true;
|
|
32
|
+
contents.setBackgroundThrottling(allowed);
|
|
33
|
+
return {
|
|
34
|
+
allowed: contents.getBackgroundThrottling?.() ?? allowed,
|
|
35
|
+
previous,
|
|
36
|
+
};
|
|
37
|
+
},
|
|
38
|
+
};
|
|
39
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { ProbeWebContents } from './types.cjs';
|
|
2
|
+
type Sender = () => ProbeWebContents | undefined | null;
|
|
3
|
+
export declare function windowControls(sender: Sender): {
|
|
4
|
+
windowState: () => {
|
|
5
|
+
minimized: boolean;
|
|
6
|
+
};
|
|
7
|
+
setWindowMinimized(minimized: boolean): {
|
|
8
|
+
minimized: boolean;
|
|
9
|
+
};
|
|
10
|
+
/** Throttled, a minimized or covered window draws no frames, so clicks wait forever. */
|
|
11
|
+
setBackgroundThrottling(allowed: boolean): {
|
|
12
|
+
allowed: boolean;
|
|
13
|
+
previous: boolean;
|
|
14
|
+
};
|
|
15
|
+
};
|
|
16
|
+
export {};
|
|
@@ -18,8 +18,10 @@ export interface WindowReport {
|
|
|
18
18
|
initial: WindowVisibility;
|
|
19
19
|
restoration?: Awaited<ReturnType<PreparedVisibility['revert']>>;
|
|
20
20
|
}
|
|
21
|
-
export declare function prepareVisibility(page: Page, { restoreWindow, control, announce, }?: {
|
|
21
|
+
export declare function prepareVisibility(page: Page, { restoreWindow, keepRendering, control, announce, }?: {
|
|
22
22
|
restoreWindow?: boolean;
|
|
23
|
+
/** Keeps a minimized or covered Electron window drawing frames, through the IPC hook. */
|
|
24
|
+
keepRendering?: boolean;
|
|
23
25
|
control?: IpcInspector;
|
|
24
26
|
announce?: (message: string) => void;
|
|
25
27
|
}): Promise<{
|
|
@@ -107,13 +107,43 @@ async function setWindowState(page, control, initial, state) {
|
|
|
107
107
|
await session.detach();
|
|
108
108
|
}
|
|
109
109
|
}
|
|
110
|
-
|
|
110
|
+
/** Warns when the page is hidden or draws no frames, which stalls clicks. */
|
|
111
|
+
function warnUnlessDrawing(window, announce) {
|
|
112
|
+
const draws = window.visibility === 'visible' &&
|
|
113
|
+
!(window.rendering && NOT_RENDERING[window.rendering]);
|
|
114
|
+
if (!draws)
|
|
115
|
+
announce(`Recovery Probe: ${window.diagnosis}. Clicks may time out, and the run may not match what a user sees.`);
|
|
116
|
+
}
|
|
117
|
+
/** Turns off the window's background throttling through the IPC hook; returns how to turn it back. */
|
|
118
|
+
async function keepDrawing(control, announce) {
|
|
119
|
+
if (!control)
|
|
120
|
+
throw new Error('keepRendering needs the IPC development hook');
|
|
121
|
+
const { previous } = await control
|
|
122
|
+
.call('setBackgroundThrottling', false)
|
|
123
|
+
.catch((error) => {
|
|
124
|
+
throw new Error(`keepRendering needs this version's development hook; restart the app so it loads it (${error.message})`);
|
|
125
|
+
});
|
|
126
|
+
announce('Recovery Probe: keeping the target window drawing frames while it is minimized or covered; its background throttling is restored afterwards.');
|
|
127
|
+
return async () => {
|
|
128
|
+
const { allowed } = await control.call('setBackgroundThrottling', previous);
|
|
129
|
+
if (allowed !== previous)
|
|
130
|
+
throw new Error('Background throttling restoration unverified');
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
export async function prepareVisibility(page, { restoreWindow = false, keepRendering = false, control,
|
|
134
|
+
// stderr, so a command's JSON on stdout stays parseable.
|
|
135
|
+
announce = (message) => console.error(message), } = {}) {
|
|
111
136
|
const initial = await windowVisibility(page, control);
|
|
112
|
-
|
|
113
|
-
|
|
137
|
+
const restoring = restoreWindow && initial.windowState === 'minimized';
|
|
138
|
+
if (!restoring && !keepRendering)
|
|
139
|
+
warnUnlessDrawing(initial, announce);
|
|
114
140
|
const set = (state) => setWindowState(page, control, initial, state);
|
|
141
|
+
const restoreDrawing = keepRendering
|
|
142
|
+
? await keepDrawing(control, announce)
|
|
143
|
+
: undefined;
|
|
115
144
|
let changed = false;
|
|
116
145
|
const revert = async () => {
|
|
146
|
+
await restoreDrawing?.();
|
|
117
147
|
if (!changed)
|
|
118
148
|
return { changed: false, restored: true };
|
|
119
149
|
await set(initial.windowState);
|
|
@@ -122,7 +152,7 @@ export async function prepareVisibility(page, { restoreWindow = false, control,
|
|
|
122
152
|
throw new Error('Window state restoration unverified');
|
|
123
153
|
return { changed: true, restored: true, final };
|
|
124
154
|
};
|
|
125
|
-
if (
|
|
155
|
+
if (restoring) {
|
|
126
156
|
announce('Recovery Probe: restoring the minimized target window for this run; its original state will be restored afterwards.');
|
|
127
157
|
changed = true; // An unsuccessful reply may still have executed.
|
|
128
158
|
await unminimize(page, control, set, revert);
|
|
@@ -10,9 +10,14 @@ export interface IpcInspector {
|
|
|
10
10
|
call(method: 'setWindowMinimized', minimized: boolean): Promise<{
|
|
11
11
|
minimized: boolean;
|
|
12
12
|
}>;
|
|
13
|
+
call(method: 'setBackgroundThrottling', allowed: boolean): Promise<{
|
|
14
|
+
allowed: boolean;
|
|
15
|
+
previous: boolean;
|
|
16
|
+
}>;
|
|
13
17
|
close(): void;
|
|
14
18
|
}
|
|
15
|
-
type ProbeControl =
|
|
19
|
+
type ProbeControl = (typeof CONTROLS)[number];
|
|
20
|
+
declare const CONTROLS: readonly ["identify", "begin", "snapshot", "reset", "windowState", "setWindowMinimized", "setBackgroundThrottling"];
|
|
16
21
|
export declare function connectIpcInspector(endpoint?: string): Promise<IpcInspector>;
|
|
17
22
|
/** Advanced protocol transport; only the documented probe control methods are allowed. */
|
|
18
23
|
export declare function callIpcInspector(send: (method: string, params: Record<string, unknown>) => Promise<unknown>, method: ProbeControl, argument?: unknown): Promise<any>;
|
|
@@ -4,6 +4,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
|
|
|
4
4
|
import { readRegion, } from '../../core/region-read.mjs';
|
|
5
5
|
import { summarizeRegion } from '../../core/screen.mjs';
|
|
6
6
|
import { observationConfig } from './config.mjs';
|
|
7
|
+
import { relateSpans, SpanRecorder } from './spans.mjs';
|
|
7
8
|
import { installObserverKit, removeObserverKit } from './kit.mjs';
|
|
8
9
|
import { pageReadInput, pageSelectors } from './page-input.mjs';
|
|
9
10
|
import { ObservationRecorder } from './recorder.mjs';
|
|
@@ -31,6 +32,7 @@ class Capture {
|
|
|
31
32
|
#readInput;
|
|
32
33
|
#operator = new OperatorRun();
|
|
33
34
|
#slowProbe;
|
|
35
|
+
#spans;
|
|
34
36
|
#started = 0;
|
|
35
37
|
/** Set once the adapter is reading; the capture has a clock from then on. */
|
|
36
38
|
#clock;
|
|
@@ -56,6 +58,9 @@ class Capture {
|
|
|
56
58
|
this.#slowProbe = config.slowReads
|
|
57
59
|
? new SlowReadProbe(page, config.slowReads, this.#kitToken)
|
|
58
60
|
: undefined;
|
|
61
|
+
this.#spans = config.spans
|
|
62
|
+
? new SpanRecorder(page, config.spans)
|
|
63
|
+
: undefined;
|
|
59
64
|
}
|
|
60
65
|
async run() {
|
|
61
66
|
const report = this.#recorder.report;
|
|
@@ -89,6 +94,7 @@ class Capture {
|
|
|
89
94
|
report.metadata.ipcHook = this.#adapter.metadata?.() ?? null;
|
|
90
95
|
this.#started = performance.now();
|
|
91
96
|
this.#clock = { elapsed: this.#elapsed, startedEpoch: Date.now() };
|
|
97
|
+
this.#spans?.start(this.#clock.startedEpoch);
|
|
92
98
|
this.#lastSnapshot = await this.#adapter.snapshot();
|
|
93
99
|
report.startedAt = this.#lastSnapshot.startedAt;
|
|
94
100
|
this.#recorder.openInterval(this.#lastSnapshot, this.#elapsed());
|
|
@@ -199,9 +205,12 @@ class Capture {
|
|
|
199
205
|
this.#page.off('domcontentloaded', this.#noteDocumentLoad);
|
|
200
206
|
const readLog = this.#adapter.readLog?.();
|
|
201
207
|
await this.#slowProbe?.stop();
|
|
208
|
+
if (this.#spans)
|
|
209
|
+
recorder.report.spans = this.#spans.stop();
|
|
202
210
|
await this.#removeKit();
|
|
203
211
|
await this.#stopAdapter();
|
|
204
212
|
recorder.conclude(this.#slowReadsEnd(readLog));
|
|
213
|
+
relateSpans(recorder.report);
|
|
205
214
|
}
|
|
206
215
|
#slowReadsEnd(readLog) {
|
|
207
216
|
const probe = this.#slowProbe;
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { type SelectorSpec } from '../../core/selector.mjs';
|
|
2
2
|
import type { ObservedActionConfig } from './kit.mjs';
|
|
3
3
|
import { type SlowReadsConfig } from './slow-reads/config.mjs';
|
|
4
|
+
import { type SpansConfig } from './spans.mjs';
|
|
4
5
|
export interface RowsConfig {
|
|
5
6
|
selector: SelectorSpec;
|
|
6
7
|
key?: SelectorSpec;
|
|
@@ -33,10 +34,18 @@ export interface ObservationConfig {
|
|
|
33
34
|
rows?: RowsConfig;
|
|
34
35
|
actions?: ObservedActionConfig[];
|
|
35
36
|
slowReads?: SlowReadsConfig;
|
|
37
|
+
/** Lists the spans the page exports over OTLP/HTTP JSON during the capture. */
|
|
38
|
+
spans?: SpansConfig;
|
|
36
39
|
lagThresholdMs: number;
|
|
37
40
|
minUnchangedReads: number;
|
|
38
41
|
detail: 'content' | 'region';
|
|
39
42
|
observationMs: number;
|
|
40
43
|
sampleMs: number;
|
|
44
|
+
/** Un-minimizes the target window for the capture and minimizes it again afterwards. */
|
|
45
|
+
restoreWindow: boolean;
|
|
46
|
+
/** Keeps a minimized or covered window drawing frames for the capture, through the IPC hook. */
|
|
47
|
+
keepRendering: boolean;
|
|
48
|
+
/** Counts the content as loaded only once the images inside it have loaded or failed. */
|
|
49
|
+
contentImages: boolean;
|
|
41
50
|
}
|
|
42
51
|
export declare function observationConfig(input: unknown): ObservationConfig;
|
|
@@ -2,6 +2,7 @@ import { ensure, ensureRanges, isIntegerIn, isNonEmptyString, isRecord, isUnique
|
|
|
2
2
|
import { selectorSpec } from '../../core/selector.mjs';
|
|
3
3
|
import { slowReadsConfig } from './slow-reads/config.mjs';
|
|
4
4
|
import { hasOnlyKeys, validateHttpTarget, validateIpcTarget, } from './target-config.mjs';
|
|
5
|
+
import { spansConfig } from './spans.mjs';
|
|
5
6
|
const NAME = /^[\w.-]{1,40}$/;
|
|
6
7
|
/** Every state label a row can have besides 'none' and 'other'. */
|
|
7
8
|
export const stateLabels = (r) => [
|
|
@@ -23,11 +24,15 @@ const DEFAULTS = {
|
|
|
23
24
|
rows: undefined,
|
|
24
25
|
actions: undefined,
|
|
25
26
|
slowReads: undefined,
|
|
27
|
+
spans: undefined,
|
|
26
28
|
lagThresholdMs: 2000,
|
|
27
29
|
minUnchangedReads: 2,
|
|
28
30
|
detail: 'content',
|
|
29
31
|
observationMs: 30000,
|
|
30
32
|
sampleMs: 100,
|
|
33
|
+
restoreWindow: false,
|
|
34
|
+
keepRendering: false,
|
|
35
|
+
contentImages: false,
|
|
31
36
|
};
|
|
32
37
|
const RANGES = [
|
|
33
38
|
['observationMs', 500, 600000],
|
|
@@ -51,12 +56,20 @@ export function observationConfig(input) {
|
|
|
51
56
|
c.actions = actionsConfig(c.actions);
|
|
52
57
|
if (c.slowReads !== undefined)
|
|
53
58
|
c.slowReads = slowReadsConfig(c.slowReads);
|
|
59
|
+
if (c.spans !== undefined)
|
|
60
|
+
c.spans = spansConfig(c.spans);
|
|
61
|
+
validateFlags(c);
|
|
54
62
|
if (c.transport === 'http')
|
|
55
63
|
validateHttpTarget(c);
|
|
56
64
|
else
|
|
57
65
|
validateIpcTarget(c);
|
|
58
66
|
return c;
|
|
59
67
|
}
|
|
68
|
+
function validateFlags(c) {
|
|
69
|
+
for (const key of ['restoreWindow', 'keepRendering', 'contentImages'])
|
|
70
|
+
ensure(typeof c[key] === 'boolean', `${key} must be boolean`);
|
|
71
|
+
ensure(!c.keepRendering || c.transport === 'ipc', 'keepRendering needs transport ipc and the development hook');
|
|
72
|
+
}
|
|
60
73
|
const isLoopbackDevtools = (url) => ['http:', 'ws:'].includes(url.protocol) &&
|
|
61
74
|
['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) &&
|
|
62
75
|
!url.username &&
|