@unotest/web 0.50.0 → 0.52.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
- import { ScenarioInterpreter, ScenarioEvent, RunResult, ScenarioRunOptions } from '@unotest/dsl/executor';
5
- export { ExecutionError, ScenarioEvent as ExecutionEvent, ScenarioRunOptions as RunOptions, RunResult } from '@unotest/dsl/executor';
6
4
  import { SandboxConfig } from '../config/schema.js';
7
5
  import { UnotestError, RuntimeExecState } from '@unotest/core';
8
- export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-Ci17V2Sr.js';
6
+ import { ScenarioEvent, RunResult, ScenarioRunOptions } from '@unotest/dsl/executor';
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-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,12 +815,18 @@ 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
493
827
  * by `setPage()` for multi-tab scenarios (Phase 2 Track A). */
494
828
  page(): DriverPage;
495
- /** User-function call depth — separate budget from maxSteps. */
829
+ /** User-function call depth — a budget of its own, apart from time. */
496
830
  enterCall(maxCallDepth: number): void;
497
831
  exitCall(): void;
498
832
  get callDepth(): number;
@@ -515,39 +849,6 @@ declare class TestRuntime {
515
849
  externalVarDenial(name: string): string | undefined;
516
850
  }
517
851
 
518
- type DslArgType = 'string' | 'number' | 'boolean' | 'locator' | 'object' | 'any';
519
- type DslReturnType = 'void' | 'string' | 'number' | 'boolean' | 'locator' | 'object' | 'any';
520
- type DslArg = DslValue | LocatorValue | unknown;
521
- interface DslFunction {
522
- name: string;
523
- argTypes: DslArgType[];
524
- returnType: DslReturnType;
525
- /** Some functions tolerate a trailing optional arg (e.g. waitFor timeoutMs). */
526
- minArgs?: number;
527
- /**
528
- * Implementation. The runtime is passed first; args follow in declaration
529
- * order. May return a primitive, a LocatorValue, an object, or a Promise of
530
- * any of these.
531
- */
532
- invoke(runtime: TestRuntime, ...args: DslArg[]): Promise<DslValue | LocatorValue | void> | DslValue | LocatorValue | void;
533
- }
534
- declare class FunctionRegistry {
535
- private readonly map;
536
- register(fn: DslFunction): void;
537
- has(name: string): boolean;
538
- get(name: string): DslFunction | undefined;
539
- names(): string[];
540
- /** The run-time half of the validator's `suggestForUnknown`: the walker
541
- * quotes it in "Unknown DSL function", from the same table. */
542
- suggestForUnknown(name: string): string | null;
543
- /** The run-time half of the validator's `suggestForLambdaArgument`. */
544
- suggestForLambdaArgument(name: string): string | null;
545
- }
546
-
547
- declare class AstExecutor extends ScenarioInterpreter<TestRuntime> {
548
- constructor(registry: FunctionRegistry);
549
- }
550
-
551
852
  type RuntimeState = RuntimeExecState;
552
853
  interface ActiveRuntime {
553
854
  id: string;
@@ -605,14 +906,16 @@ interface ActiveRuntime {
605
906
  /** The failure this run stopped at, kept from the moment the executor
606
907
  * paused on it.
607
908
  *
608
- * It exists because continuing is how a failure gets INSPECTED: with
609
- * `pauseOnFailure`, the walker holds at the error and, once resumed,
610
- * carries on with the next statement — so a run that broke can still
611
- * reach the end and report `completed`. It did not stop being broken
909
+ * With `pauseOnFailure` the executor holds at the error, and Continue
910
+ * finishes the test as failed. `verdict` still reads this field rather
911
+ * than trust the executor alone: a run did not stop being broken
612
912
  * because somebody looked at it, and the verdict must not depend on
613
913
  * whether anyone did. */
614
914
  pausedOnFailure: ActiveRuntime['lastFailure'];
615
915
  lastResult: RunResult | null;
916
+ /** What `abort` closed the generator with. A pump that was in flight
917
+ * reads the closed generator's end as this, not as a missing result. */
918
+ abortedWith?: RunResult;
616
919
  createdAt: number;
617
920
  /** Active TTL timer (only when state is paused-failure). */
618
921
  ttlTimer: NodeJS.Timeout | null;
@@ -657,6 +960,9 @@ interface RuntimeSnapshot {
657
960
  /** Rollback blocks that failed or never ran. */
658
961
  teardownFailures?: readonly TeardownFailureRecord[];
659
962
  }
963
+ /** A snapshot without `vars`: what a caller that does not show the
964
+ * scenario's variables reads, without paying for building them. */
965
+ type RuntimeStateSnapshot = Omit<RuntimeSnapshot, 'vars'>;
660
966
  interface TestRuntimeManagerDeps {
661
967
  logger: Logger;
662
968
  ttlMs: number;
@@ -728,7 +1034,17 @@ declare class TestRuntimeManager {
728
1034
  /** Snapshot a just-aborted (still-live) runtime into the tombstone map so a
729
1035
  * later inspect() reflects `aborted`. Bounded LRU; best-effort. */
730
1036
  private rememberTombstone;
1037
+ /** The whole snapshot, the scenario's variables included — built on
1038
+ * every call, so a caller that does not show them reads
1039
+ * `inspectState` instead. */
731
1040
  inspect(id: string): RuntimeSnapshot;
1041
+ /** `inspect` without `vars`: state, last event, failure and result,
1042
+ * without walking the scope. */
1043
+ inspectState(id: string): RuntimeStateSnapshot;
1044
+ /** The runtime was aborted (removed from `runtimes`) — its captured
1045
+ * terminal snapshot, so callers see `aborted`, not a "not found" throw. */
1046
+ private tombstone;
1047
+ private stateOf;
732
1048
  /** The live active page of a runtime — used by the locator picker to
733
1049
  * attach its overlay to the page held open during a debug pause.
734
1050
  * Returns null when the runtime is gone or has no page yet. */
@@ -752,6 +1068,35 @@ declare class TestRuntimeManager {
752
1068
  private requireActive;
753
1069
  }
754
1070
 
1071
+ type DslArgType = 'string' | 'number' | 'boolean' | 'locator' | 'object' | 'any';
1072
+ type DslReturnType = 'void' | 'string' | 'number' | 'boolean' | 'locator' | 'object' | 'any';
1073
+ type DslArg = DslValue | LocatorValue | unknown;
1074
+ interface DslFunction {
1075
+ name: string;
1076
+ argTypes: DslArgType[];
1077
+ returnType: DslReturnType;
1078
+ /** Some functions tolerate a trailing optional arg (e.g. waitFor timeoutMs). */
1079
+ minArgs?: number;
1080
+ /**
1081
+ * Implementation. The runtime is passed first; args follow in declaration
1082
+ * order. May return a primitive, a LocatorValue, an object, or a Promise of
1083
+ * any of these.
1084
+ */
1085
+ invoke(runtime: TestRuntime, ...args: DslArg[]): Promise<DslValue | LocatorValue | void> | DslValue | LocatorValue | void;
1086
+ }
1087
+ declare class FunctionRegistry {
1088
+ private readonly map;
1089
+ register(fn: DslFunction): void;
1090
+ has(name: string): boolean;
1091
+ get(name: string): DslFunction | undefined;
1092
+ names(): string[];
1093
+ /** The run-time half of the validator's `suggestForUnknown`: the walker
1094
+ * quotes it in "Unknown DSL function", from the same table. */
1095
+ suggestForUnknown(name: string): string | null;
1096
+ /** The run-time half of the validator's `suggestForLambdaArgument`. */
1097
+ suggestForLambdaArgument(name: string): string | null;
1098
+ }
1099
+
755
1100
  declare function buildDefaultRegistry(): FunctionRegistry;
756
1101
 
757
- export { AstExecutor, type DslArg, type DslArray, type DslFunction, type DslObject, type DslValue, FunctionRegistry, LocatorValue, TestRuntime, TestRuntimeManager, buildDefaultRegistry, chainGetByAltText, chainGetByLabel, chainGetByPlaceholder, chainGetByRole, chainGetByTestId, chainGetByText, chainGetByTitle, contentFrame, filter, first, getByAltText, getByLabel, getByPlaceholder, getByRole, getByTestId, getByText, getByTitle, last, locator, nth, randomNth, re };
1102
+ export { type DslArg, type DslArray, type DslFunction, type DslObject, type DslValue, FunctionRegistry, LocatorValue, TestRuntime, TestRuntimeManager, buildDefaultRegistry, chainGetByAltText, chainGetByLabel, chainGetByPlaceholder, chainGetByRole, chainGetByTestId, chainGetByText, chainGetByTitle, contentFrame, filter, first, getByAltText, getByLabel, getByPlaceholder, getByRole, getByTestId, getByText, getByTitle, last, locator, nth, randomNth, re };