@unotest/web 0.49.2 → 0.51.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.
@@ -1,20 +1,18 @@
1
- import { L as LocatorValue, o as DriverDownload, D as DriverContext, W as WebDriver, h as DriverPage } from '../interfaces-mlRtu8mL.js';
2
- export { p as LocatorStep, q as appendStep, r as describeLocator, s as isLocatorValue, t as rootedAt } from '../interfaces-mlRtu8mL.js';
1
+ import { L as LocatorValue, q as DriverDownload, D as DriverContext, W as WebDriver, i as DriverPage } from '../interfaces-BSGmF_Tv.js';
2
+ export { r as LocatorStep, s as appendStep, t as describeLocator, u as isLocatorValue, v as rootedAt } from '../interfaces-BSGmF_Tv.js';
3
3
  import { Matcher, RegexLiteral, JudgeRequest, JudgeVerdict, VisualFailureRecord, SoftFailureRecord, TeardownStateRecord, TeardownFailureRecord } from '@unotest/protocol';
4
- import { ExecutionWalker, ExecutionEvent, RunResult, RunOptions } from '@unotest/dsl/executor';
5
- export { ExecutionError, ExecutionEvent, RunOptions, RunResult } from '@unotest/dsl/executor';
4
+ import { ScenarioInterpreter, ScenarioEvent, RunResult, ScenarioRunOptions } from '@unotest/dsl/executor';
5
+ export { ExecutionError, ScenarioEvent as ExecutionEvent, ScenarioRunOptions as RunOptions, RunResult } from '@unotest/dsl/executor';
6
6
  import { SandboxConfig } from '../config/schema.js';
7
7
  import { UnotestError, RuntimeExecState } from '@unotest/core';
8
- export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-RrjB1n9R.js';
8
+ export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-CYRlmOLy.js';
9
9
  import 'zod';
10
10
  import '@unotest/dsl';
11
11
 
12
- /** Test/codegen convenience: build a RegexLiteral inline. The DSL
13
- * parser produces these for `/pattern/flags` literals at runtime;
14
- * builders take this shape so unit tests don't need to round-trip
15
- * through the lexer. Flag validation lives in `@unotest/dsl`'s
16
- * RegExpValue; this helper trusts its caller because TS already
17
- * constrains `flags: string`. */
12
+ /** Test/codegen convenience: build a RegexLiteral inline — the shape
13
+ * `coerceMatcher` turns a scenario's `/pattern/flags` into, so unit
14
+ * tests don't need to round-trip through the parser. Pattern and flags
15
+ * are the parser's to check; this helper trusts its caller. */
18
16
  declare function re(source: string, flags?: string): RegexLiteral;
19
17
  declare function locator(selector: string): LocatorValue;
20
18
  declare function getByRole(role: string, options?: {
@@ -119,6 +117,11 @@ interface Logger {
119
117
  error(msg: string, ...rest: unknown[]): void;
120
118
  debug(msg: string, ...rest: unknown[]): void;
121
119
  step(msg: string, ...rest: unknown[]): void;
120
+ /** An error line under a word of its own instead of `error` — a test
121
+ * result reads `failed` or `errored`, the words of the run's summary.
122
+ * Optional so a test's logger literal need not grow it; `labeledError`
123
+ * is how a caller prints one. */
124
+ labeled?(label: string, msg: string, ...rest: unknown[]): void;
122
125
  child(prefix: string): Logger;
123
126
  }
124
127
 
@@ -141,6 +144,17 @@ interface VariableStore {
141
144
  * cannot tell (test fakes) leaves it out, and a caller that must not
142
145
  * hand a secret out then refuses rather than guess. */
143
146
  isSecret?(name: string): boolean;
147
+ /** Why `name` is refused although the environment may hold it — the
148
+ * runner's own credential (`withOwnSecretsDenied`,
149
+ * config/own-secrets-deny.ts). Optional like `describeSources`; a
150
+ * caller that reports a missing name asks this first, so the reader
151
+ * learns whose the name is instead of hunting a typo. */
152
+ denial?(name: string): string | undefined;
153
+ /** The file that declares `name` without giving it a value (a `.example`
154
+ * twin), when no layer and no shell has one. Optional like `denial`: a
155
+ * store that cannot tell leaves it out, and the caller then reports the
156
+ * name as undeclared. */
157
+ declaredOnlyIn?(name: string): string | undefined;
144
158
  }
145
159
 
146
160
  interface Judge {
@@ -366,6 +380,312 @@ declare class ContextSet {
366
380
  private switchTo;
367
381
  }
368
382
 
383
+ interface CommandRun {
384
+ /** Fed to the program's stdin — a script travels here, never inside
385
+ * argv, so its text is not limited or quoted by any shell. */
386
+ readonly stdin?: string;
387
+ readonly timeoutMs?: number;
388
+ }
389
+ interface CommandHost {
390
+ /** Where the terminal is, for a report: `this Mac`, `admin@192.168.64.38`.
391
+ * Never carries a credential. */
392
+ readonly name: string;
393
+ /** Run `argv` (no shell) and resolve with its stdout. A non-zero exit
394
+ * rejects with `TerminalHostError` carrying the program's stderr. */
395
+ run(argv: readonly string[], opts?: CommandRun): Promise<Buffer>;
396
+ }
397
+
398
+ declare class AppleScriptRunner {
399
+ private readonly host;
400
+ constructor(host: CommandHost);
401
+ /** Run `body` inside `on run argv … end run`; resolve with what it
402
+ * returned, as text, without the newline osascript adds. */
403
+ run(body: string, argv?: readonly string[]): Promise<string>;
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;
408
+ }
409
+
410
+ interface TerminalApp {
411
+ /** The name a scenario opens it by: `openTerminal('iTerm2')`. */
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[]>;
429
+ }
430
+
431
+ type KeyModifier = 'Shift' | 'Control' | 'Alt' | 'Meta';
432
+ type KeyTarget = {
433
+ readonly kind: 'code';
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;
442
+ }
443
+
444
+ interface TypeOptions {
445
+ /** Wait for the screen to show each line — off for input a program
446
+ * does not echo, such as a password. */
447
+ readonly echo: boolean;
448
+ }
449
+ interface ScreenWaitOptions {
450
+ readonly timeoutMs: number;
451
+ /** Pass once the text is NOT on the screen. */
452
+ readonly not?: boolean;
453
+ }
454
+ declare class TerminalSession {
455
+ private readonly host;
456
+ readonly app: TerminalApp;
457
+ readonly windowId: string;
458
+ private readonly script;
459
+ private constructor();
460
+ /** Where the window is, for a report — never a credential. */
461
+ get hostName(): string;
462
+ static open(host: CommandHost, app: TerminalApp): Promise<TerminalSession>;
463
+ /** Paste `text` line by line, Return between the lines; with `echo`,
464
+ * each line must show on the screen before the next goes. The user's
465
+ * pasteboard is theirs again when this returns or throws. */
466
+ type(fnName: string, text: string, opts: TypeOptions): Promise<void>;
467
+ /** A character alone is text: it goes as `type` sends it, unchecked —
468
+ * a key such as `q` or `y` is often not echoed. */
469
+ press(fnName: string, chord: KeyChord): Promise<void>;
470
+ text(): Promise<string>;
471
+ resize(cols: number, rows: number): Promise<void>;
472
+ /** A PNG of the window as it is on screen now. */
473
+ frame(): Promise<Buffer>;
474
+ /** Resolve once the screen shows `matcher` (or, with `not`, no longer
475
+ * does); a string occurs anywhere on it, a regex is tested against it. */
476
+ waitForText(fnName: string, matcher: Matcher, opts: ScreenWaitOptions): Promise<void>;
477
+ assertText(fnName: string, matcher: Matcher, opts: ScreenWaitOptions): Promise<void>;
478
+ /** Stop the shell (and whatever runs in it) and close the window. */
479
+ close(): Promise<void>;
480
+ private screenMatches;
481
+ private windowScript;
482
+ /** Paste one line — the pasting script checks the front again before
483
+ * it pastes — then wait for the screen to show it. */
484
+ private pasteLine;
485
+ /** Bring the window to the front and run `statement` (System Events key
486
+ * presses) while it is there; nothing when it is not. */
487
+ private sendKeys;
488
+ private expectSent;
489
+ }
490
+
491
+ /** The host of `openTerminal(app, {host})`: this Mac without one, the Mac
492
+ * at `user@address` with one. */
493
+ interface CommandHosts {
494
+ local(): CommandHost;
495
+ remote(destination: string): CommandHost;
496
+ }
497
+ interface TerminalSetDeps {
498
+ readonly hosts: CommandHosts;
499
+ readonly apps: readonly TerminalApp[];
500
+ }
501
+ declare class TerminalSet {
502
+ private readonly deps;
503
+ private readonly sessions;
504
+ private activeIdx;
505
+ private readonly remotes;
506
+ constructor(deps: TerminalSetDeps);
507
+ /** Open a window of `appName` on `destination` (this Mac when absent),
508
+ * make it active, return its index. */
509
+ open(fnName: string, appName: string, destination?: string): Promise<number>;
510
+ select(fnName: string, index: number): void;
511
+ /** The window the terminal steps act on. */
512
+ active(fnName: string): TerminalSession;
513
+ /** The active window, or none — for a failure bundle, which must not
514
+ * fail over a test that never opened a terminal. */
515
+ current(): TerminalSession | undefined;
516
+ /** Close window `index`; a closed one stays closed, quietly. */
517
+ close(index: number): Promise<void>;
518
+ /** `closeTerminal()`: the active window; refused when none is open. */
519
+ closeActive(fnName: string): Promise<void>;
520
+ private remote;
521
+ private openAt;
522
+ }
523
+
524
+ interface VmHost {
525
+ /** Whether VMs can run on this machine at all: the tool is installed
526
+ * and answers. Never throws. */
527
+ available(): Promise<boolean>;
528
+ /** A new VM `name` from the image `image`. */
529
+ clone(image: string, name: string): Promise<void>;
530
+ /** Boot `name` without a window. Resolves once it is starting; a boot
531
+ * that fails surfaces from the next `ip`. */
532
+ run(name: string): Promise<void>;
533
+ /** The address of a booted VM, waiting up to `waitSeconds` for it. */
534
+ ip(name: string, waitSeconds: number): Promise<string>;
535
+ stop(name: string): Promise<void>;
536
+ delete(name: string): Promise<void>;
537
+ }
538
+
539
+ interface VmSetDeps {
540
+ host: VmHost;
541
+ /** The id that tells this test's VMs apart (8 hex in production). */
542
+ newId: () => string;
543
+ }
544
+ declare class VmSet {
545
+ private readonly deps;
546
+ private id;
547
+ private clones;
548
+ /** Cloned and not deleted, in order. */
549
+ private readonly owned;
550
+ private readonly booted;
551
+ private releaseScheduled;
552
+ constructor(deps: VmSetDeps);
553
+ available(): Promise<boolean>;
554
+ clone(image: string): Promise<string>;
555
+ /** Boot `name` and wait for its address. */
556
+ run(name: string, waitSeconds: number): Promise<string>;
557
+ ip(name: string, waitSeconds: number): Promise<string>;
558
+ stop(name: string): Promise<void>;
559
+ /** A running VM is stopped first: the tool deletes only stopped ones. */
560
+ delete(name: string): Promise<void>;
561
+ /** Hands `releaseAll` to the test's teardowns, once per set: a test
562
+ * that clones nothing leaves no teardown behind. */
563
+ scheduleRelease(addTeardown: (fn: () => Promise<void>) => void): void;
564
+ /** Every VM the test still owns, stopped and deleted, red test or
565
+ * green. One that fails does not keep the others: the failures come
566
+ * back for the log. */
567
+ releaseAll(): Promise<Array<{
568
+ name: string;
569
+ error: unknown;
570
+ }>>;
571
+ private own;
572
+ }
573
+
574
+ interface McpServerSpec {
575
+ command: string;
576
+ args: readonly string[];
577
+ /** The child's whole environment, already assembled by the caller. */
578
+ env: Readonly<Record<string, string>>;
579
+ /** Absolute working directory of the child. */
580
+ cwd: string;
581
+ }
582
+ type McpWireDirection = 'sent' | 'received';
583
+ interface McpWireMessage {
584
+ direction: McpWireDirection;
585
+ /** The JSON-RPC message as it crossed the wire. */
586
+ message: Readonly<Record<string, unknown>>;
587
+ }
588
+ interface McpConnectionEvents {
589
+ onMessage(wire: McpWireMessage): void;
590
+ /** The server went away: exited, or closed its end of the pipe. */
591
+ onClose(): void;
592
+ }
593
+ interface McpConnection {
594
+ /** `tools/call`; resolves with the result as the server sent it. */
595
+ callTool(tool: string, args: Readonly<Record<string, unknown>>, timeoutMs: number): Promise<Record<string, unknown>>;
596
+ /** The tail of what the server wrote to stderr — a crash says why there. */
597
+ stderrTail(): string;
598
+ close(): Promise<void>;
599
+ }
600
+ interface McpConnector {
601
+ /** Start the server and finish the `initialize` handshake within
602
+ * `timeoutMs`. */
603
+ connect(spec: McpServerSpec, events: McpConnectionEvents, timeoutMs: number): Promise<McpConnection>;
604
+ }
605
+
606
+ type JsonScalar = string | number | boolean | null;
607
+ interface FilterEntry {
608
+ /** Dot path split into segments: `user.id` → ['user', 'id']. */
609
+ path: string[];
610
+ label: string;
611
+ expected: JsonScalar;
612
+ }
613
+ interface JsonFilter {
614
+ entries: FilterEntry[];
615
+ describe(): string;
616
+ }
617
+
618
+ /** Where the session reports calls, results and notifications — the
619
+ * run's journal. Must not throw: reporting never fails a step. */
620
+ interface McpJournal {
621
+ record(label: string, text: string): Promise<void>;
622
+ }
623
+ interface McpWaitSpec {
624
+ method: string;
625
+ /** Scalars at dot paths of `params`, as waitForJsonLine reads them. */
626
+ filter?: JsonFilter;
627
+ /** The filter as the scenario wrote it, for the failure to quote. */
628
+ filterText?: string;
629
+ timeoutMs: number;
630
+ }
631
+ declare class McpSession {
632
+ /** How the journal and the errors name this server. */
633
+ readonly label: string;
634
+ private readonly journal;
635
+ private connection;
636
+ private last;
637
+ private readonly pending;
638
+ private readonly waiters;
639
+ private closed;
640
+ private stopping;
641
+ private constructor();
642
+ static start(connector: McpConnector, spec: McpServerSpec, label: string, journal: McpJournal, timeoutMs: number): Promise<McpSession>;
643
+ get isClosed(): boolean;
644
+ call(tool: string, args: Readonly<Record<string, unknown>>, opts: {
645
+ timeoutMs: number;
646
+ allowError: boolean;
647
+ }): Promise<Record<string, unknown>>;
648
+ waitNotification(spec: McpWaitSpec): Promise<Record<string, unknown>>;
649
+ stop(): Promise<void>;
650
+ private open;
651
+ private observe;
652
+ private deliver;
653
+ private onClose;
654
+ private callFault;
655
+ private waitTimedOut;
656
+ private stderr;
657
+ }
658
+
659
+ /** What the scenario holds: plain data, so it prints and journals like any
660
+ * other value. The session lives here, behind the id. */
661
+ interface McpHandle {
662
+ readonly kind: 'mcp';
663
+ readonly id: string;
664
+ readonly command: string;
665
+ }
666
+ interface McpSessionsDeps {
667
+ connector: McpConnector;
668
+ journal: McpJournal;
669
+ }
670
+ declare class McpSessions {
671
+ private readonly deps;
672
+ private readonly sessions;
673
+ private started;
674
+ constructor(deps: McpSessionsDeps);
675
+ /** `ownEnv`: the names the scenario set on top of the inherited
676
+ * environment — the journal names them, never their values. */
677
+ start(spec: McpServerSpec, opts: {
678
+ timeoutMs: number;
679
+ ownEnv: readonly string[];
680
+ }): Promise<McpHandle>;
681
+ /** The session behind a handle the scenario passed in. */
682
+ get(fnName: string, handle: unknown): McpSession;
683
+ stop(fnName: string, handle: unknown): Promise<void>;
684
+ /** Stops the server if the scenario has not — what mcpStart leaves to
685
+ * the end of the test. */
686
+ release(handle: McpHandle): Promise<void>;
687
+ }
688
+
369
689
  type DslPrimitive = string | number | boolean | null;
370
690
  type DslObject = {
371
691
  readonly [key: string]: DslValue;
@@ -446,12 +766,25 @@ interface TestRuntimeServices {
446
766
  * run entry by the runner; absent in ad-hoc / explore runtimes, where
447
767
  * the DSL function fails with a setup message. */
448
768
  readonly visual?: VisualAssertDeps;
769
+ /** The terminal windows of this test entry — a fresh set per entry from
770
+ * the runner; absent in explore / ad-hoc runtimes, where the terminal
771
+ * steps refuse with a setup message. */
772
+ readonly terminals?: TerminalSet;
773
+ /** The VMs of this test entry (`vmClone` …) — a fresh set per entry
774
+ * from the runner; absent in explore / ad-hoc runtimes, where the vm*
775
+ * steps refuse with a setup message. */
776
+ readonly vms?: VmSet;
777
+ /** How `mcpStart` starts a server. Absent → stdio over the MCP SDK;
778
+ * tests hand in a fake. */
779
+ readonly mcpConnector?: McpConnector;
449
780
  }
450
781
  declare class TestRuntime {
451
782
  readonly runId: string;
452
783
  readonly driver: WebDriver;
453
784
  /** Every browser context of this entry and which one is active. */
454
785
  readonly contexts: ContextSet;
786
+ /** Every terminal window of this entry and which one is active. */
787
+ readonly terminals?: TerminalSet;
455
788
  /** See `RuntimeContexts.openOnWindow`. */
456
789
  readonly openOnWindow?: ContextFactory;
457
790
  readonly logger: Logger;
@@ -467,9 +800,12 @@ declare class TestRuntime {
467
800
  readonly annotations?: AnnotationSink;
468
801
  readonly stepNotes?: StepNotesReader;
469
802
  readonly visual?: VisualAssertDeps;
803
+ /** The MCP servers this test started. */
804
+ readonly mcp: McpSessions;
805
+ readonly vms?: VmSet;
806
+ private readonly releases;
470
807
  private readonly variables;
471
808
  private readonly nowFn;
472
- private readonly scope;
473
809
  private _callDepth;
474
810
  constructor(deps: TestRuntimeDeps);
475
811
  /** The ACTIVE context — what every DSL function acts on. `setContext`
@@ -479,14 +815,17 @@ declare class TestRuntime {
479
815
  * journal, the failure bundle and `assertScreenshot` carry it only then
480
816
  * (#197), so a one-context run writes exactly what it did before. */
481
817
  reportedContextIndex(): number | undefined;
818
+ /** Release something the test acquired (a server, a window) when the
819
+ * test ends, red or green — the runner calls `runTeardowns`. */
820
+ addTeardown(fn: () => Promise<void>): void;
821
+ /** Runs what `addTeardown` registered, newest first, each one even if
822
+ * another failed. Returns what the failed ones threw. */
823
+ runTeardowns(): Promise<unknown[]>;
482
824
  /** Current epoch ms — injectable for deterministic tests. */
483
825
  now(): number;
484
826
  /** The active DriverPage. Tracks DriverContext.activePage which is mutated
485
827
  * by `setPage()` for multi-tab scenarios (Phase 2 Track A). */
486
828
  page(): DriverPage;
487
- /** Variable scope stack — push/pop on user-function call boundaries. */
488
- pushScope(): void;
489
- popScope(): void;
490
829
  /** User-function call depth — separate budget from maxSteps. */
491
830
  enterCall(maxCallDepth: number): void;
492
831
  exitCall(): void;
@@ -496,9 +835,7 @@ declare class TestRuntime {
496
835
  * NOT a separate injected field: a field the two runtime-building
497
836
  * sites could forget to pass is a rule that switches itself off. */
498
837
  get hostPolicy(): HostPolicy | undefined;
499
- setVar(name: string, value: DslValue): void;
500
838
  getVar(name: string): DslValue;
501
- hasVar(name: string): boolean;
502
839
  /** Direct external-variable lookup (`unotest/.env` / `.secrets`), no
503
840
  * scope fallback, no throw. Used by shell() to resolve the
504
841
  * `sandbox.exportSecrets` allowlist into subprocess env. */
@@ -506,8 +843,10 @@ declare class TestRuntime {
506
843
  /** Whether external variable `name` is a secret; undefined when the
507
844
  * variable store cannot tell. Used by `env()`, which never hands one out. */
508
845
  externalVarIsSecret(name: string): boolean | undefined;
509
- /** Snapshot for `inspect_runtime` MCP tool. */
510
- snapshotVars(): Record<string, DslValue>;
846
+ /** Why external variable `name` is refused to scenarios (the runner's
847
+ * own credential), or undefined. Used by shell(), whose child must not
848
+ * inherit what getVar refuses. */
849
+ externalVarDenial(name: string): string | undefined;
511
850
  }
512
851
 
513
852
  type DslArgType = 'string' | 'number' | 'boolean' | 'locator' | 'object' | 'any';
@@ -539,7 +878,7 @@ declare class FunctionRegistry {
539
878
  suggestForLambdaArgument(name: string): string | null;
540
879
  }
541
880
 
542
- declare class AstExecutor extends ExecutionWalker<TestRuntime> {
881
+ declare class AstExecutor extends ScenarioInterpreter<TestRuntime> {
543
882
  constructor(registry: FunctionRegistry);
544
883
  }
545
884
 
@@ -549,9 +888,11 @@ interface ActiveRuntime {
549
888
  scenarioName: string;
550
889
  testFn: string;
551
890
  testRuntime: TestRuntime;
552
- generator: AsyncGenerator<ExecutionEvent, RunResult>;
891
+ generator: AsyncGenerator<ScenarioEvent, RunResult>;
892
+ /** The variables visible where the run stands (`inspectScope`). */
893
+ scope: () => Record<string, unknown>;
553
894
  state: RuntimeState;
554
- lastEvent: ExecutionEvent | null;
895
+ lastEvent: ScenarioEvent | null;
555
896
  /**
556
897
  * The most recent failure event. Distinct from `lastEvent` because the
557
898
  * immediately-following `paused` event would otherwise overwrite it —
@@ -582,6 +923,8 @@ interface ActiveRuntime {
582
923
  notes?: readonly NoteRecord[];
583
924
  error: {
584
925
  message: string;
926
+ name?: string;
927
+ checkFailure?: true;
585
928
  stack?: string;
586
929
  details?: unknown;
587
930
  };
@@ -639,7 +982,7 @@ interface RuntimeSnapshot {
639
982
  vars: Record<string, unknown>;
640
983
  /** Active page index in the DriverContext (web-specific, vs. mobile's deviceSlot). */
641
984
  activePageIndex: number | null;
642
- lastEvent: ExecutionEvent | null;
985
+ lastEvent: ScenarioEvent | null;
643
986
  lastFailure: ActiveRuntime['lastFailure'];
644
987
  softFailures: readonly SoftFailureRecord[];
645
988
  lastResult: RunResult | null;
@@ -648,6 +991,9 @@ interface RuntimeSnapshot {
648
991
  /** Rollback blocks that failed or never ran. */
649
992
  teardownFailures?: readonly TeardownFailureRecord[];
650
993
  }
994
+ /** A snapshot without `vars`: what a caller that does not show the
995
+ * scenario's variables reads, without paying for building them. */
996
+ type RuntimeStateSnapshot = Omit<RuntimeSnapshot, 'vars'>;
651
997
  interface TestRuntimeManagerDeps {
652
998
  logger: Logger;
653
999
  ttlMs: number;
@@ -679,8 +1025,12 @@ declare class TestRuntimeManager {
679
1025
  scenarioName: string;
680
1026
  testFn: string;
681
1027
  testRuntime: TestRuntime;
682
- generator: AsyncGenerator<ExecutionEvent, RunResult>;
683
- runOptions: RunOptions;
1028
+ generator: AsyncGenerator<ScenarioEvent, RunResult>;
1029
+ /** The interpreter's `inspectScope` — what `inspect()` reports as
1030
+ * `vars`. The scenario's variables live in the interpreter, not in
1031
+ * the runtime. */
1032
+ scope: () => Record<string, unknown>;
1033
+ runOptions: ScenarioRunOptions;
684
1034
  /** Last thing this runtime gets to do when it is aborted, awaited
685
1035
  * inside `abort()`. It exists because an abort on a PAUSE never comes
686
1036
  * back through the orchestrator: the CLI kills the process right
@@ -692,7 +1042,7 @@ declare class TestRuntimeManager {
692
1042
  * runtime.json) while it plays. */
693
1043
  teardown?: TeardownProgress;
694
1044
  }): string;
695
- pump(id: string): Promise<ExecutionEvent | RunResult>;
1045
+ pump(id: string): Promise<ScenarioEvent | RunResult>;
696
1046
  /** The run's verdict — the executor's own, corrected for the one thing
697
1047
  * it cannot see: that a failure it paused on was resumed rather than
698
1048
  * fixed.
@@ -705,8 +1055,8 @@ declare class TestRuntimeManager {
705
1055
  private verdict;
706
1056
  /** The run's final verdict, rollback included — see `pump`. */
707
1057
  finish(id: string, result: RunResult): void;
708
- step(id: string): Promise<ExecutionEvent | RunResult>;
709
- resume(id: string): Promise<ExecutionEvent | RunResult>;
1058
+ step(id: string): Promise<ScenarioEvent | RunResult>;
1059
+ resume(id: string): Promise<ScenarioEvent | RunResult>;
710
1060
  abort(id: string): Promise<void>;
711
1061
  private abortOnce;
712
1062
  /** The second Stop: give up on the rest of the run's rollback pass. The
@@ -715,7 +1065,17 @@ declare class TestRuntimeManager {
715
1065
  /** Snapshot a just-aborted (still-live) runtime into the tombstone map so a
716
1066
  * later inspect() reflects `aborted`. Bounded LRU; best-effort. */
717
1067
  private rememberTombstone;
1068
+ /** The whole snapshot, the scenario's variables included — built on
1069
+ * every call, so a caller that does not show them reads
1070
+ * `inspectState` instead. */
718
1071
  inspect(id: string): RuntimeSnapshot;
1072
+ /** `inspect` without `vars`: state, last event, failure and result,
1073
+ * without walking the scope. */
1074
+ inspectState(id: string): RuntimeStateSnapshot;
1075
+ /** The runtime was aborted (removed from `runtimes`) — its captured
1076
+ * terminal snapshot, so callers see `aborted`, not a "not found" throw. */
1077
+ private tombstone;
1078
+ private stateOf;
719
1079
  /** The live active page of a runtime — used by the locator picker to
720
1080
  * attach its overlay to the page held open during a debug pause.
721
1081
  * Returns null when the runtime is gone or has no page yet. */