@unotest/web 0.50.0 → 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,11 +1,11 @@
1
- import { L as LocatorValue, o as DriverDownload, D as DriverContext, W as WebDriver, h as DriverPage } from '../interfaces--zgFOUB6.js';
2
- export { p as LocatorStep, q as appendStep, r as describeLocator, s as isLocatorValue, t as rootedAt } from '../interfaces--zgFOUB6.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
4
  import { ScenarioInterpreter, ScenarioEvent, RunResult, ScenarioRunOptions } from '@unotest/dsl/executor';
5
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-Ci17V2Sr.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
 
@@ -150,6 +150,11 @@ interface VariableStore {
150
150
  * caller that reports a missing name asks this first, so the reader
151
151
  * learns whose the name is instead of hunting a typo. */
152
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;
153
158
  }
154
159
 
155
160
  interface Judge {
@@ -375,6 +380,312 @@ declare class ContextSet {
375
380
  private switchTo;
376
381
  }
377
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
+
378
689
  type DslPrimitive = string | number | boolean | null;
379
690
  type DslObject = {
380
691
  readonly [key: string]: DslValue;
@@ -455,12 +766,25 @@ interface TestRuntimeServices {
455
766
  * run entry by the runner; absent in ad-hoc / explore runtimes, where
456
767
  * the DSL function fails with a setup message. */
457
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;
458
780
  }
459
781
  declare class TestRuntime {
460
782
  readonly runId: string;
461
783
  readonly driver: WebDriver;
462
784
  /** Every browser context of this entry and which one is active. */
463
785
  readonly contexts: ContextSet;
786
+ /** Every terminal window of this entry and which one is active. */
787
+ readonly terminals?: TerminalSet;
464
788
  /** See `RuntimeContexts.openOnWindow`. */
465
789
  readonly openOnWindow?: ContextFactory;
466
790
  readonly logger: Logger;
@@ -476,6 +800,10 @@ declare class TestRuntime {
476
800
  readonly annotations?: AnnotationSink;
477
801
  readonly stepNotes?: StepNotesReader;
478
802
  readonly visual?: VisualAssertDeps;
803
+ /** The MCP servers this test started. */
804
+ readonly mcp: McpSessions;
805
+ readonly vms?: VmSet;
806
+ private readonly releases;
479
807
  private readonly variables;
480
808
  private readonly nowFn;
481
809
  private _callDepth;
@@ -487,6 +815,12 @@ declare class TestRuntime {
487
815
  * journal, the failure bundle and `assertScreenshot` carry it only then
488
816
  * (#197), so a one-context run writes exactly what it did before. */
489
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[]>;
490
824
  /** Current epoch ms — injectable for deterministic tests. */
491
825
  now(): number;
492
826
  /** The active DriverPage. Tracks DriverContext.activePage which is mutated
@@ -657,6 +991,9 @@ interface RuntimeSnapshot {
657
991
  /** Rollback blocks that failed or never ran. */
658
992
  teardownFailures?: readonly TeardownFailureRecord[];
659
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'>;
660
997
  interface TestRuntimeManagerDeps {
661
998
  logger: Logger;
662
999
  ttlMs: number;
@@ -728,7 +1065,17 @@ declare class TestRuntimeManager {
728
1065
  /** Snapshot a just-aborted (still-live) runtime into the tombstone map so a
729
1066
  * later inspect() reflects `aborted`. Bounded LRU; best-effort. */
730
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. */
731
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;
732
1079
  /** The live active page of a runtime — used by the locator picker to
733
1080
  * attach its overlay to the page held open during a debug pause.
734
1081
  * Returns null when the runtime is gone or has no page yet. */