@unotest/web 0.52.1 → 0.53.0
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 +168 -3
- package/README.md +5 -3
- package/dist/config/schema.d.ts +11 -11
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +7 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +333 -92
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/v8/scenario-worker.js +1 -1
- package/dist/dsl/web-dsl-language-service.d.ts +11 -3
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +5 -2
- package/dist/inspection/page-inject.js +11 -0
- package/dist/{interfaces-BSGmF_Tv.d.ts → interfaces-BU-PQbt4.d.ts} +48 -2
- package/dist/{linter-CYRlmOLy.d.ts → linter-BpaIstU3.d.ts} +11 -1
- package/dist/mcp/server.js +1 -1
- package/dist/runner/cli.d.ts +1 -1
- package/dist/runner/cli.js +1 -1
- package/dist/runner/init/chrome-probe.js +1 -1
- package/dist/runner/init.js +1 -1
- package/dist/runner/install-chromium.js +1 -1
- package/dist/runner/prepare-fix.js +1 -1
- package/dist/runner/scaffold-workspace.js +1 -1
- package/dist/runner/serve-fixture.js +1 -1
- package/dist/runner/web-runner-adapter.js +1 -1
- package/guides/agent-integration.md +1 -1
- package/guides/dsl-reference.md +485 -40
- package/llms.txt +14 -9
- package/package.json +13 -8
- package/src/mcp/prompts/agent-test-author.md +3 -1
- package/types/unotest-dsl.d.ts +52 -17
package/dist/dsl/index.d.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
import { L as LocatorValue,
|
|
2
|
-
export {
|
|
1
|
+
import { L as LocatorValue, j as DriverPage, r as DriverDownload, D as DriverContext, W as WebDriver } from '../interfaces-BU-PQbt4.js';
|
|
2
|
+
export { s as LocatorStep, t as appendStep, u as describeLocator, v as isLocatorValue, w as rootedAt } from '../interfaces-BU-PQbt4.js';
|
|
3
3
|
import { Matcher, RegexLiteral, JudgeRequest, JudgeVerdict, VisualFailureRecord, SoftFailureRecord, TeardownStateRecord, TeardownFailureRecord } from '@unotest/protocol';
|
|
4
|
-
import { SandboxConfig } from '../config/schema.js';
|
|
4
|
+
import { Browser, SandboxConfig } from '../config/schema.js';
|
|
5
5
|
import { UnotestError, RuntimeExecState } from '@unotest/core';
|
|
6
6
|
import { ScenarioEvent, RunResult, ScenarioRunOptions } from '@unotest/dsl/executor';
|
|
7
7
|
export { ExecutionError, ScenarioEvent as ExecutionEvent, ScenarioRunOptions as RunOptions, RunResult } from '@unotest/dsl/executor';
|
|
8
|
-
export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-
|
|
8
|
+
export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-BpaIstU3.js';
|
|
9
9
|
import 'zod';
|
|
10
10
|
import '@unotest/dsl';
|
|
11
11
|
|
|
@@ -125,6 +125,61 @@ interface Logger {
|
|
|
125
125
|
child(prefix: string): Logger;
|
|
126
126
|
}
|
|
127
127
|
|
|
128
|
+
/** How deep a redaction goes. */
|
|
129
|
+
interface RedactOptions {
|
|
130
|
+
/** Fields (by key, at any depth) whose strings are left alone. */
|
|
131
|
+
keep?: readonly string[];
|
|
132
|
+
/** `"exact"` also masks NUMBERS whose decimal form is exactly a
|
|
133
|
+
* registered secret — a numeric one-time code reaching a field typed
|
|
134
|
+
* `number | string`.
|
|
135
|
+
*
|
|
136
|
+
* Off by default, and that is a decision rather than an oversight: in
|
|
137
|
+
* a page capture the numbers are the structure — coordinates, widths,
|
|
138
|
+
* counts, unit totals — and masking one turns a graph the grounder
|
|
139
|
+
* reads into a graph it cannot. The caller that has a field where a
|
|
140
|
+
* number can BE the secret asks for it there. */
|
|
141
|
+
numbers?: "exact";
|
|
142
|
+
}
|
|
143
|
+
declare class SecretRegistry {
|
|
144
|
+
private readonly byValue;
|
|
145
|
+
private ordered;
|
|
146
|
+
/** Register a secret. Empty values are ignored — they'd match everywhere
|
|
147
|
+
* and can't be meaningfully masked. */
|
|
148
|
+
register(name: string, value: string): void;
|
|
149
|
+
get size(): number;
|
|
150
|
+
/** Copy every registered secret into `target`. Used when a per-session
|
|
151
|
+
* env overlay (`.secrets.<env>`) must also be masked by the
|
|
152
|
+
* process-wide sinks (debug log, session recorder) that hold the
|
|
153
|
+
* server's own registry. */
|
|
154
|
+
mergeInto(target: SecretRegistry): void;
|
|
155
|
+
/** Replace every registered secret value occurring in `s` with
|
|
156
|
+
* `‹secret:NAME›`. Returns `s` unchanged when no secrets are registered. */
|
|
157
|
+
redactString(s: string): string;
|
|
158
|
+
/** `redactString` for a terminal screen: a value the terminal wrapped
|
|
159
|
+
* onto the next row is masked too, the screen keeping its rows. */
|
|
160
|
+
redactScreen(screen: string): string;
|
|
161
|
+
/** Deep-redact a JSON-ish structure: every string field is run through
|
|
162
|
+
* `redactString`. Returns a new value; the input is not mutated. No-op
|
|
163
|
+
* (returns the input as-is) when no secrets are registered.
|
|
164
|
+
*
|
|
165
|
+
* `keep` names fields (by key, at any depth) whose strings are left as
|
|
166
|
+
* they are: the runner's own identifiers — a scenario path, a test
|
|
167
|
+
* function name, a run id. They are not page content, and a secret
|
|
168
|
+
* whose value happens to be a word inside them (`LOGIN=admin` against
|
|
169
|
+
* `guard-admin.js`) would otherwise mask the identifier itself into
|
|
170
|
+
* something no tool can open. An explicit list, never a guess at what
|
|
171
|
+
* "looks like a path". */
|
|
172
|
+
redact<T>(data: T, opts?: RedactOptions): T;
|
|
173
|
+
private redactValue;
|
|
174
|
+
/** A number is masked only when its decimal form IS a secret, whole —
|
|
175
|
+
* never when a secret occurs inside it. A number has no text for a
|
|
176
|
+
* value to hide in: `447213` either is the one-time code or is a
|
|
177
|
+
* quantity, and substring matching would mask the `99` in every price
|
|
178
|
+
* on the page. Masking yields a STRING, which is why the caller opts
|
|
179
|
+
* in per field rather than getting it everywhere. */
|
|
180
|
+
private redactNumber;
|
|
181
|
+
}
|
|
182
|
+
|
|
128
183
|
/** Read-only lookup over external scenario variables. */
|
|
129
184
|
interface VariableStore {
|
|
130
185
|
has(name: string): boolean;
|
|
@@ -185,6 +240,11 @@ interface NoteRecord {
|
|
|
185
240
|
/** The value as text: strings as-is, everything else JSON. The sink
|
|
186
241
|
* applies the journal cap; the DSL layer does not know the limit. */
|
|
187
242
|
text: string;
|
|
243
|
+
/** Run-dir-relative file holding the whole text, when `text` is a cut
|
|
244
|
+
* of it. Set by the sink; the DSL layer never fills it. */
|
|
245
|
+
full?: string;
|
|
246
|
+
/** Characters of the whole text that `text` leaves out. */
|
|
247
|
+
omittedChars?: number;
|
|
188
248
|
}
|
|
189
249
|
/** The notes of the step block the run is in, as the sink recorded them
|
|
190
250
|
* (secrets masked). Read when a statement fails, so the failure carries
|
|
@@ -310,6 +370,16 @@ interface VisualSink {
|
|
|
310
370
|
failure(): VisualFailureRecord | null;
|
|
311
371
|
}
|
|
312
372
|
|
|
373
|
+
/** Says, once per run, that a snapshot taken on WebKit leaves out the
|
|
374
|
+
* backdrop blur the page asks for. Only a page that has one is worth the
|
|
375
|
+
* line; the engine is the run's `launch.browser`. */
|
|
376
|
+
declare class BackdropFilterNotice {
|
|
377
|
+
private readonly engine;
|
|
378
|
+
private readonly warn;
|
|
379
|
+
private said;
|
|
380
|
+
constructor(engine: Browser, warn: (line: string) => void);
|
|
381
|
+
check(page: Pick<DriverPage, "hasBackdropFilter">): Promise<void>;
|
|
382
|
+
}
|
|
313
383
|
/** What the assert needs besides the page — wired per run entry. */
|
|
314
384
|
interface VisualAssertDeps {
|
|
315
385
|
comparator: ImageComparator;
|
|
@@ -321,6 +391,7 @@ interface VisualAssertDeps {
|
|
|
321
391
|
attempt: number;
|
|
322
392
|
/** The names this run has given, to refuse two that became one file. */
|
|
323
393
|
names: BaselineNames;
|
|
394
|
+
backdrop?: BackdropFilterNotice;
|
|
324
395
|
}
|
|
325
396
|
|
|
326
397
|
type FrameFormat = "png" | "webp";
|
|
@@ -331,6 +402,11 @@ interface ScreenshotSink {
|
|
|
331
402
|
* holds webp is the kind of thing nobody notices until a tool tries
|
|
332
403
|
* to read it. Returns the project-relative path it landed at. */
|
|
333
404
|
save(name: string, bytes: Buffer, format: FrameFormat): Promise<string>;
|
|
405
|
+
/** Persist the text that stands in for a picture which could not be
|
|
406
|
+
* shown — a terminal screen with a secret on it, already masked. Filed
|
|
407
|
+
* in the same sequence as the pictures; the event says `redacted`.
|
|
408
|
+
* Returns the project-relative path it landed at. */
|
|
409
|
+
saveMaskedText(name: string, text: string): Promise<string>;
|
|
334
410
|
}
|
|
335
411
|
|
|
336
412
|
interface SavedDownload {
|
|
@@ -347,6 +423,26 @@ interface DownloadSink {
|
|
|
347
423
|
}
|
|
348
424
|
|
|
349
425
|
type ContextFactory = () => Promise<DriverContext>;
|
|
426
|
+
/** How the runner opens a context on a browser profile of its own
|
|
427
|
+
* (`newContext({profile})`). It owns what a directory name means: where a
|
|
428
|
+
* relative one starts, that it exists. */
|
|
429
|
+
interface ProfileContexts {
|
|
430
|
+
/** The directory as the browser will open it: absolute, made if it was
|
|
431
|
+
* missing, symlinks resolved — the form two names of one directory agree on. */
|
|
432
|
+
resolve(dir: string): string;
|
|
433
|
+
open(resolvedDir: string): Promise<DriverContext>;
|
|
434
|
+
/** Whether `resolvedDir` is the profile directory the run's own context
|
|
435
|
+
* sits on (a run on `launch.userDataDir`, or a browser per test). */
|
|
436
|
+
isRunProfile(resolvedDir: string): boolean;
|
|
437
|
+
}
|
|
438
|
+
/** How the runner opens a context in a browser it joins over CDP
|
|
439
|
+
* (`newContext({cdpEndpoint})`): a browser somebody else started, left
|
|
440
|
+
* running when the test ends. */
|
|
441
|
+
type RemoteContextFactory = (endpoint: string) => Promise<DriverContext>;
|
|
442
|
+
interface NewContextTarget {
|
|
443
|
+
profile?: string;
|
|
444
|
+
cdpEndpoint?: string;
|
|
445
|
+
}
|
|
350
446
|
/** A context that did not close — reported, never swallowed. */
|
|
351
447
|
interface ContextCloseFailure {
|
|
352
448
|
index: number;
|
|
@@ -355,19 +451,42 @@ interface ContextCloseFailure {
|
|
|
355
451
|
declare class ContextSet {
|
|
356
452
|
private readonly opts;
|
|
357
453
|
private readonly list;
|
|
454
|
+
private pendingFirst;
|
|
455
|
+
private readonly openFirst;
|
|
358
456
|
private activeIdx;
|
|
457
|
+
/** Profile directories opened by `open({profile})`, and the context on each. */
|
|
458
|
+
private readonly profileDirs;
|
|
459
|
+
/** Contexts opened in a browser joined over CDP, and the ones already
|
|
460
|
+
* closed — `closeRemote` closes the first early, `closeAll` skips the second. */
|
|
461
|
+
private readonly remoteIdx;
|
|
462
|
+
private readonly closedIdx;
|
|
359
463
|
/** Called with the new active index on every switch (open or select). */
|
|
360
464
|
private readonly listeners;
|
|
361
|
-
constructor(first: DriverContext, opts?: {
|
|
465
|
+
constructor(first: DriverContext | ContextFactory, opts?: {
|
|
362
466
|
open?: ContextFactory;
|
|
467
|
+
profiles?: ProfileContexts;
|
|
468
|
+
remote?: RemoteContextFactory;
|
|
363
469
|
max?: number;
|
|
364
470
|
});
|
|
471
|
+
/** Whether context 0 exists — false only for a lazy set nothing has needed yet. */
|
|
472
|
+
opened(): boolean;
|
|
473
|
+
/** Context 0, opened on the first call; calls made meanwhile share the
|
|
474
|
+
* one opening. A failed opening is not remembered: the next need tries again. */
|
|
475
|
+
ready(): Promise<DriverContext>;
|
|
365
476
|
active(): DriverContext;
|
|
366
477
|
activeIndex(): number;
|
|
367
478
|
size(): number;
|
|
368
479
|
all(): readonly DriverContext[];
|
|
369
|
-
/** Open one more context, make it active, return its index
|
|
370
|
-
|
|
480
|
+
/** Open one more context, make it active, return its index — on a
|
|
481
|
+
* browser profile of its own when `profile` names a directory, in a
|
|
482
|
+
* browser somebody else runs when `cdpEndpoint` names one. */
|
|
483
|
+
open(target?: NewContextTarget): Promise<number>;
|
|
484
|
+
private openRemote;
|
|
485
|
+
private openProfile;
|
|
486
|
+
/** Context 0 first, then room under the ceiling, then the new one —
|
|
487
|
+
* active from the moment it is in. */
|
|
488
|
+
private place;
|
|
489
|
+
private requireRoom;
|
|
371
490
|
select(index: unknown): void;
|
|
372
491
|
/** Put `next` in the active context's place — same index, so whatever is
|
|
373
492
|
* bound to the index (teardowns, the journal's context number) follows —
|
|
@@ -375,11 +494,82 @@ declare class ContextSet {
|
|
|
375
494
|
* active context is a different one now. */
|
|
376
495
|
replaceActive(next: DriverContext): Promise<void>;
|
|
377
496
|
onSwitch(listener: (index: number) => void): () => void;
|
|
378
|
-
/** Close every context, newest first; the failures come back. */
|
|
497
|
+
/** Close every context not closed yet, newest first; the failures come back. */
|
|
379
498
|
closeAll(): Promise<ContextCloseFailure[]>;
|
|
499
|
+
/** Close the contexts that live in other people's browsers, ahead of
|
|
500
|
+
* everything else: what they sit in can go away (a VM) before the
|
|
501
|
+
* test's own teardown is done, and a close then waits on a dead
|
|
502
|
+
* connection. `closeAll` leaves them alone afterwards. */
|
|
503
|
+
closeRemote(): Promise<ContextCloseFailure[]>;
|
|
504
|
+
private closeIndices;
|
|
380
505
|
private switchTo;
|
|
381
506
|
}
|
|
382
507
|
|
|
508
|
+
/** What a wait reads of the test's time budget. */
|
|
509
|
+
interface BudgetClock {
|
|
510
|
+
/** Milliseconds left; Infinity when the test has no budget. */
|
|
511
|
+
leftMs(): number;
|
|
512
|
+
/** The budget's setting and size, for a message. */
|
|
513
|
+
describe(): {
|
|
514
|
+
setting: string;
|
|
515
|
+
limitMs: number;
|
|
516
|
+
};
|
|
517
|
+
}
|
|
518
|
+
interface BudgetCut {
|
|
519
|
+
readonly askedMs: number;
|
|
520
|
+
readonly leftMs: number;
|
|
521
|
+
readonly setting: string;
|
|
522
|
+
readonly limitMs: number;
|
|
523
|
+
}
|
|
524
|
+
/** The clock a runtime holds for its whole life; the executor binds the
|
|
525
|
+
* run's budget to it while the run lasts. Unbound, there is no budget. */
|
|
526
|
+
declare class BindableBudgetClock implements BudgetClock {
|
|
527
|
+
private source;
|
|
528
|
+
bind(source: BudgetClock): void;
|
|
529
|
+
unbind(): void;
|
|
530
|
+
leftMs(): number;
|
|
531
|
+
describe(): {
|
|
532
|
+
setting: string;
|
|
533
|
+
limitMs: number;
|
|
534
|
+
};
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
type KeyModifier = 'Shift' | 'Control' | 'Alt' | 'Meta';
|
|
538
|
+
declare const NAMED_KEYS: readonly ["Enter", "Tab", "Space", "Backspace", "Escape", "Delete", "Home", "End", "PageUp", "PageDown", "ArrowLeft", "ArrowRight", "ArrowDown", "ArrowUp", "F1", "F2", "F3", "F4", "F5", "F6", "F7", "F8", "F9", "F10", "F11", "F12"];
|
|
539
|
+
type NamedKey = (typeof NAMED_KEYS)[number];
|
|
540
|
+
declare const US_KEY_CHARS: readonly ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "`", "-", "=", "[", "]", "\\", ";", "'", ",", ".", "/"];
|
|
541
|
+
type UsKeyChar = (typeof US_KEY_CHARS)[number];
|
|
542
|
+
type KeyTarget = {
|
|
543
|
+
readonly kind: 'named';
|
|
544
|
+
readonly name: NamedKey;
|
|
545
|
+
}
|
|
546
|
+
/** A key of a US keyboard, held with modifiers. */
|
|
547
|
+
| {
|
|
548
|
+
readonly kind: 'us';
|
|
549
|
+
readonly char: UsKeyChar;
|
|
550
|
+
}
|
|
551
|
+
/** A character alone: text. */
|
|
552
|
+
| {
|
|
553
|
+
readonly kind: 'char';
|
|
554
|
+
readonly char: string;
|
|
555
|
+
};
|
|
556
|
+
interface KeyChord {
|
|
557
|
+
readonly modifiers: readonly KeyModifier[];
|
|
558
|
+
readonly key: KeyTarget;
|
|
559
|
+
}
|
|
560
|
+
|
|
561
|
+
interface ScreenWaitOptions {
|
|
562
|
+
readonly timeoutMs: number;
|
|
563
|
+
/** Pass once the text is NOT on the screen. */
|
|
564
|
+
readonly not?: boolean;
|
|
565
|
+
/** Set when the budget of the test shortened `timeoutMs`. */
|
|
566
|
+
readonly cut?: BudgetCut;
|
|
567
|
+
}
|
|
568
|
+
/** What a wait saw: a regex gives the match array JS does (`[whole,
|
|
569
|
+
* group1, …]`, a group that took no part is null), a string the first
|
|
570
|
+
* screen row that holds it, `not` nothing. Taken from the masked screen. */
|
|
571
|
+
type ScreenMatch = readonly (string | null)[] | string | null;
|
|
572
|
+
|
|
383
573
|
interface CommandRun {
|
|
384
574
|
/** Fed to the program's stdin — a script travels here, never inside
|
|
385
575
|
* argv, so its text is not limited or quoted by any shell. */
|
|
@@ -390,55 +580,30 @@ interface CommandHost {
|
|
|
390
580
|
/** Where the terminal is, for a report: `this Mac`, `admin@192.168.64.38`.
|
|
391
581
|
* Never carries a credential. */
|
|
392
582
|
readonly name: string;
|
|
583
|
+
/** Who macOS asks for Screen Recording on this host — the app whose
|
|
584
|
+
* process runs `screencapture`, named for a message that tells the user
|
|
585
|
+
* where to allow it. */
|
|
586
|
+
permissionHolder(): string;
|
|
393
587
|
/** Run `argv` (no shell) and resolve with its stdout. A non-zero exit
|
|
394
588
|
* rejects with `TerminalHostError` carrying the program's stderr. */
|
|
395
589
|
run(argv: readonly string[], opts?: CommandRun): Promise<Buffer>;
|
|
396
590
|
}
|
|
397
591
|
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
/** Run JXA `source` — a script whose `run(argv)` takes `argv` — and
|
|
405
|
-
* resolve with what it returned, as `run` does. */
|
|
406
|
-
runJavaScript(source: string, argv?: readonly string[]): Promise<string>;
|
|
407
|
-
private osascript;
|
|
592
|
+
type StopSignal = 'HUP' | 'KILL';
|
|
593
|
+
interface StoppedProcess {
|
|
594
|
+
readonly pid: number;
|
|
595
|
+
readonly command: string;
|
|
596
|
+
/** The signal after which it was gone. */
|
|
597
|
+
readonly signal: StopSignal;
|
|
408
598
|
}
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
readonly name: string;
|
|
413
|
-
/** The process System Events reports as frontmost while it has focus. */
|
|
414
|
-
readonly processName: string;
|
|
415
|
-
/** Script: open a new window with a login shell; return its id. */
|
|
416
|
-
readonly openScript: string;
|
|
417
|
-
/** Statements: bring window `winId` to the front and the app forward. */
|
|
418
|
-
readonly focusStatements: string;
|
|
419
|
-
/** Script: return the visible text of window `winId`. */
|
|
420
|
-
readonly textScript: string;
|
|
421
|
-
/** Script: return the tty of the shell in window `winId`. */
|
|
422
|
-
readonly ttyScript: string;
|
|
423
|
-
/** Statements: set window `winId` to `cols` × `rows` (argv items 2, 3). */
|
|
424
|
-
readonly resizeStatements: string;
|
|
425
|
-
/** Statements: close window `winId`; its shell has already exited. */
|
|
426
|
-
readonly closeStatements: string;
|
|
427
|
-
/** The `screencapture` arguments that frame window `winId`. */
|
|
428
|
-
captureArgs(script: AppleScriptRunner, windowId: string): Promise<readonly string[]>;
|
|
599
|
+
interface SurvivingProcess {
|
|
600
|
+
readonly pid: number;
|
|
601
|
+
readonly command: string;
|
|
429
602
|
}
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
readonly
|
|
434
|
-
readonly code: number;
|
|
435
|
-
} | {
|
|
436
|
-
readonly kind: 'char';
|
|
437
|
-
readonly char: string;
|
|
438
|
-
};
|
|
439
|
-
interface KeyChord {
|
|
440
|
-
readonly modifiers: readonly KeyModifier[];
|
|
441
|
-
readonly key: KeyTarget;
|
|
603
|
+
/** What a window's end did to the processes of its tty. */
|
|
604
|
+
interface StopReport {
|
|
605
|
+
readonly killed: readonly StoppedProcess[];
|
|
606
|
+
readonly survived: readonly SurvivingProcess[];
|
|
442
607
|
}
|
|
443
608
|
|
|
444
609
|
interface TypeOptions {
|
|
@@ -446,46 +611,75 @@ interface TypeOptions {
|
|
|
446
611
|
* does not echo, such as a password. */
|
|
447
612
|
readonly echo: boolean;
|
|
448
613
|
}
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
614
|
+
/** The clipboard a terminal's programs share with the test. Its text is
|
|
615
|
+
* often a secret: nothing here repeats it in a message. */
|
|
616
|
+
interface TerminalClipboard {
|
|
617
|
+
read(): Promise<string>;
|
|
618
|
+
write(text: string): Promise<void>;
|
|
453
619
|
}
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
readonly
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
620
|
+
/** How a terminal's shell ended: its exit code and, when a signal ended
|
|
621
|
+
* it, the signal's name (`SIGTERM`). */
|
|
622
|
+
interface TerminalExit {
|
|
623
|
+
readonly exitCode: number;
|
|
624
|
+
readonly signal: string | null;
|
|
625
|
+
}
|
|
626
|
+
interface TerminalExitOptions {
|
|
627
|
+
readonly timeoutMs: number;
|
|
628
|
+
/** The exit code the shell must have ended with. */
|
|
629
|
+
readonly code?: number;
|
|
630
|
+
}
|
|
631
|
+
interface TerminalSession {
|
|
632
|
+
/** What a scenario opened: `Terminal`, `iTerm2`, `shell`. */
|
|
633
|
+
readonly appName: string;
|
|
634
|
+
/** Where it runs, for a report — never a credential. */
|
|
635
|
+
readonly hostName: string;
|
|
636
|
+
readonly clipboard: TerminalClipboard;
|
|
637
|
+
/** Send `text` line by line, Return between the lines; with `echo`, each
|
|
638
|
+
* line must show on the screen before the next goes. */
|
|
466
639
|
type(fnName: string, text: string, opts: TypeOptions): Promise<void>;
|
|
467
|
-
/** A
|
|
468
|
-
* a key such as `q` or `y` is often not echoed. */
|
|
640
|
+
/** A key by its name or chord; a character alone goes as text. */
|
|
469
641
|
press(fnName: string, chord: KeyChord): Promise<void>;
|
|
642
|
+
/** The screen as text (see screenText). */
|
|
470
643
|
text(): Promise<string>;
|
|
471
644
|
resize(cols: number, rows: number): Promise<void>;
|
|
472
|
-
/** A PNG of the
|
|
645
|
+
/** A PNG of the terminal as it is now. */
|
|
473
646
|
frame(): Promise<Buffer>;
|
|
474
647
|
/** Resolve once the screen shows `matcher` (or, with `not`, no longer
|
|
475
|
-
* does);
|
|
476
|
-
waitForText(fnName: string, matcher: Matcher, opts: ScreenWaitOptions): Promise<
|
|
648
|
+
* does); returns what it saw. */
|
|
649
|
+
waitForText(fnName: string, matcher: Matcher, opts: ScreenWaitOptions): Promise<ScreenMatch>;
|
|
477
650
|
assertText(fnName: string, matcher: Matcher, opts: ScreenWaitOptions): Promise<void>;
|
|
478
|
-
/**
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
/**
|
|
483
|
-
* it
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
651
|
+
/** Resolve once the shell has exited, with how it ended; at once when it
|
|
652
|
+
* already has. With `code`, any other code fails. A session that cannot
|
|
653
|
+
* see its shell's exit refuses. */
|
|
654
|
+
waitForExit(fnName: string, opts: TerminalExitOptions): Promise<TerminalExit>;
|
|
655
|
+
/** Stop the shell and everything that runs from it — HUP, then KILL for
|
|
656
|
+
* what ignored it — and close the terminal; the report names what was
|
|
657
|
+
* stopped and what no signal stopped. */
|
|
658
|
+
close(): Promise<StopReport>;
|
|
659
|
+
}
|
|
660
|
+
|
|
661
|
+
/** The secrets a terminal masks: `redactString` for a line of output,
|
|
662
|
+
* `redactScreen` for a whole screen, where a value may be wrapped. */
|
|
663
|
+
type TerminalSecrets = Pick<SecretRegistry, 'redactString' | 'redactScreen'>;
|
|
664
|
+
/** A frame of a window: its picture, or — a secret was on the screen —
|
|
665
|
+
* the screen text with the secret masked. */
|
|
666
|
+
type GuardedFrame = {
|
|
667
|
+
readonly kind: 'png';
|
|
668
|
+
readonly png: Buffer;
|
|
669
|
+
} | {
|
|
670
|
+
readonly kind: 'masked';
|
|
671
|
+
readonly text: string;
|
|
672
|
+
};
|
|
673
|
+
|
|
674
|
+
interface TerminalLaunch {
|
|
675
|
+
readonly env?: Readonly<Record<string, string>>;
|
|
676
|
+
readonly cwd?: string;
|
|
677
|
+
readonly shell?: string;
|
|
678
|
+
readonly cols?: number;
|
|
679
|
+
readonly rows?: number;
|
|
680
|
+
readonly term?: string;
|
|
681
|
+
readonly locale?: string;
|
|
682
|
+
readonly cleanProfile?: boolean;
|
|
489
683
|
}
|
|
490
684
|
|
|
491
685
|
/** The host of `openTerminal(app, {host})`: this Mac without one, the Mac
|
|
@@ -494,29 +688,61 @@ interface CommandHosts {
|
|
|
494
688
|
local(): CommandHost;
|
|
495
689
|
remote(destination: string): CommandHost;
|
|
496
690
|
}
|
|
691
|
+
interface OpenRequest {
|
|
692
|
+
readonly fnName: string;
|
|
693
|
+
/** `{host}` as the scenario gave it, unchecked: an opener that takes no
|
|
694
|
+
* host refuses it; one that does resolves it through `hosts`. */
|
|
695
|
+
readonly destination: string | undefined;
|
|
696
|
+
readonly hosts: CommandHosts;
|
|
697
|
+
readonly redactScreen: TerminalSecrets['redactScreen'];
|
|
698
|
+
/** How the shell of a pty terminal starts; absent when the scenario set
|
|
699
|
+
* none of the launch keys. */
|
|
700
|
+
readonly launch?: TerminalLaunch;
|
|
701
|
+
}
|
|
702
|
+
interface TerminalOpener {
|
|
703
|
+
/** The name a scenario opens it by: `openTerminal('iTerm2')`. */
|
|
704
|
+
readonly name: string;
|
|
705
|
+
open(req: OpenRequest): Promise<TerminalSession>;
|
|
706
|
+
}
|
|
707
|
+
|
|
497
708
|
interface TerminalSetDeps {
|
|
498
709
|
readonly hosts: CommandHosts;
|
|
499
|
-
|
|
710
|
+
/** What `openTerminal(name)` can open, by name. */
|
|
711
|
+
readonly openers: readonly TerminalOpener[];
|
|
712
|
+
/** The run's registered secrets: what a terminal's screen must never
|
|
713
|
+
* carry out of the run unmasked. */
|
|
714
|
+
readonly secrets: TerminalSecrets;
|
|
715
|
+
}
|
|
716
|
+
/** A window the set closed: which one, where, and what its end stopped. */
|
|
717
|
+
interface ClosedTerminal extends StopReport {
|
|
718
|
+
readonly index: number;
|
|
719
|
+
readonly host: string;
|
|
500
720
|
}
|
|
501
721
|
declare class TerminalSet {
|
|
502
722
|
private readonly deps;
|
|
503
723
|
private readonly sessions;
|
|
504
724
|
private activeIdx;
|
|
505
725
|
private readonly remotes;
|
|
726
|
+
private readonly frames;
|
|
506
727
|
constructor(deps: TerminalSetDeps);
|
|
507
|
-
/** Open a
|
|
508
|
-
* make it active, return its index. */
|
|
509
|
-
open(fnName: string,
|
|
728
|
+
/** Open a terminal by its opener's name on `destination` (this machine
|
|
729
|
+
* when absent), make it active, return its index. */
|
|
730
|
+
open(fnName: string, name: string, destination?: string, launch?: TerminalLaunch): Promise<number>;
|
|
510
731
|
select(fnName: string, index: number): void;
|
|
511
732
|
/** The window the terminal steps act on. */
|
|
512
733
|
active(fnName: string): TerminalSession;
|
|
513
734
|
/** The active window, or none — for a failure bundle, which must not
|
|
514
735
|
* fail over a test that never opened a terminal. */
|
|
515
736
|
current(): TerminalSession | undefined;
|
|
516
|
-
/**
|
|
517
|
-
|
|
737
|
+
/** A frame of `session` fit to leave the run: its picture, or its
|
|
738
|
+
* masked screen text when a secret is on the screen. */
|
|
739
|
+
frame(session: TerminalSession): Promise<GuardedFrame>;
|
|
740
|
+
/** The screen text of `session`, every secret on it masked. */
|
|
741
|
+
screen(session: TerminalSession): Promise<string>;
|
|
742
|
+
/** Close window `index`; a closed one stays closed, quietly (null). */
|
|
743
|
+
close(index: number): Promise<ClosedTerminal | null>;
|
|
518
744
|
/** `closeTerminal()`: the active window; refused when none is open. */
|
|
519
|
-
closeActive(fnName: string): Promise<
|
|
745
|
+
closeActive(fnName: string): Promise<ClosedTerminal | null>;
|
|
520
746
|
private remote;
|
|
521
747
|
private openAt;
|
|
522
748
|
}
|
|
@@ -696,11 +922,19 @@ type DslValue = DslPrimitive | DslObject | DslArray;
|
|
|
696
922
|
* context the runner opened — or one it SHARES with its host (a flow
|
|
697
923
|
* replayed in an MCP session switches the session's contexts). */
|
|
698
924
|
type RuntimeContexts = {
|
|
699
|
-
/** Context 0 — the one the runner opened for this entry
|
|
700
|
-
|
|
925
|
+
/** Context 0 — the one the runner opened for this entry, or the way
|
|
926
|
+
* to open it on the first need (a test that never uses a page
|
|
927
|
+
* never starts a browser). */
|
|
928
|
+
readonly context: DriverContext | ContextFactory;
|
|
701
929
|
/** Opens one more context with the entry's options (`newContext()`).
|
|
702
930
|
* Absent → the runtime cannot add one (an attached debug session). */
|
|
703
931
|
readonly openContext?: ContextFactory;
|
|
932
|
+
/** Opens a context on a browser profile of its own
|
|
933
|
+
* (`newContext({profile})`). Absent → it cannot be. */
|
|
934
|
+
readonly profiles?: ProfileContexts;
|
|
935
|
+
/** Opens a context in a browser joined over CDP
|
|
936
|
+
* (`newContext({cdpEndpoint})`). Absent → it cannot be. */
|
|
937
|
+
readonly remote?: RemoteContextFactory;
|
|
704
938
|
/** Ceiling on contexts per entry (`config.maxContexts`). */
|
|
705
939
|
readonly maxContexts?: number;
|
|
706
940
|
/** Opens the entry's context again with the same options on the real
|
|
@@ -797,6 +1031,9 @@ declare class TestRuntime {
|
|
|
797
1031
|
readonly testTimeout?: {
|
|
798
1032
|
ms?: number;
|
|
799
1033
|
};
|
|
1034
|
+
/** What is left of the test's time; the executor binds it for the run.
|
|
1035
|
+
* Unbound (explore, bare runtimes) there is no budget to wait within. */
|
|
1036
|
+
readonly budget: BindableBudgetClock;
|
|
800
1037
|
readonly annotations?: AnnotationSink;
|
|
801
1038
|
readonly stepNotes?: StepNotesReader;
|
|
802
1039
|
readonly visual?: VisualAssertDeps;
|
|
@@ -1054,8 +1291,12 @@ declare class TestRuntimeManager {
|
|
|
1054
1291
|
* is gone or has no context yet. */
|
|
1055
1292
|
pages(id: string): readonly DriverPage[];
|
|
1056
1293
|
/** The runtime's driver context (for capture artifacts — console/network).
|
|
1057
|
-
* Null when the runtime isn't registered
|
|
1294
|
+
* Null when the runtime isn't registered, or its test has not opened a
|
|
1295
|
+
* browser page. */
|
|
1058
1296
|
currentContext(id: string): DriverContext | null;
|
|
1297
|
+
/** Every browser context the runtime opened, in index order — the active
|
|
1298
|
+
* one is only one of them. Empty when the runtime isn't registered. */
|
|
1299
|
+
contexts(id: string): readonly DriverContext[];
|
|
1059
1300
|
list(): RuntimeSummary[];
|
|
1060
1301
|
/** A client acted on the runtime — a debug command arrived. A runtime
|
|
1061
1302
|
* paused on a failure gets its full TTL again: somebody is there. A read
|