@unotest/web 0.55.0 → 0.57.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.
Files changed (49) hide show
  1. package/.claude/skills/write-e2e-test/SKILL.md +44 -7
  2. package/.claude/skills/write-e2e-test-ground/SKILL.md +20 -5
  3. package/CHANGELOG.md +250 -3
  4. package/README.md +7 -6
  5. package/bin/unotest-web.js +13 -0
  6. package/dist/config/schema.d.ts +29 -23
  7. package/dist/config/schema.js +1 -1
  8. package/dist/driver/index.d.ts +16 -2
  9. package/dist/driver/index.js +1 -1
  10. package/dist/dsl/index.d.ts +74 -94
  11. package/dist/dsl/index.js +1 -1
  12. package/dist/dsl/v8/scenario-worker.js +1 -1
  13. package/dist/dsl/web-dsl-language-service.d.ts +30 -3
  14. package/dist/dsl/web-dsl-language-service.js +1 -1
  15. package/dist/inspection/page-inject.d.ts +63 -7
  16. package/dist/inspection/page-inject.js +199 -19
  17. package/dist/{interfaces-CNvyInrY.d.ts → interfaces-DDp6Chwx.d.ts} +167 -10
  18. package/dist/{linter-BpaIstU3.d.ts → linter-q4UNIeGI.d.ts} +20 -0
  19. package/dist/mcp/server.js +1 -1
  20. package/dist/runner/cli.d.ts +1 -1
  21. package/dist/runner/cli.js +1 -1
  22. package/dist/runner/init/chrome-probe.js +1 -1
  23. package/dist/runner/init.js +1 -1
  24. package/dist/runner/install-chromium.js +1 -1
  25. package/dist/runner/prepare-fix.js +1 -1
  26. package/dist/runner/scaffold-workspace.js +1 -1
  27. package/dist/runner/serve-fixture.js +1 -1
  28. package/dist/runner/web-runner-adapter.js +1 -1
  29. package/dist/scenario-variables-CGexnWK4.d.ts +106 -0
  30. package/examples/idioms/README.md +16 -0
  31. package/examples/idioms/animations-list.js +24 -0
  32. package/examples/idioms/api-call-timeout.js +14 -0
  33. package/examples/idioms/background-tab.js +24 -0
  34. package/examples/idioms/clipboard-paste.js +25 -0
  35. package/examples/idioms/computed-style.js +21 -0
  36. package/examples/idioms/image-size.js +20 -0
  37. package/examples/idioms/never-appears.js +20 -0
  38. package/examples/idioms/never-condition.js +24 -0
  39. package/examples/idioms/page-code-function.js +18 -0
  40. package/examples/idioms/select-by-label.js +22 -0
  41. package/examples/idioms/wait-enabled.js +24 -0
  42. package/examples/idioms/wait-for-animations.js +16 -0
  43. package/examples/idioms/wait-until-value.js +32 -0
  44. package/guides/agent-integration.md +28 -4
  45. package/guides/dsl-reference.md +896 -45
  46. package/llms.txt +38 -9
  47. package/package.json +9 -8
  48. package/types/unotest-dsl.d.ts +107 -30
  49. package/types/unotest-lib.d.ts +5 -3
@@ -1,11 +1,12 @@
1
- import { L as LocatorValue, j as DriverPage, r as DriverDownload, D as DriverContext, b as PageNetworkEntry, W as WebDriver } from '../interfaces-CNvyInrY.js';
2
- export { s as LocatorStep, t as appendStep, u as describeLocator, v as isLocatorValue, w as rootedAt } from '../interfaces-CNvyInrY.js';
1
+ import { L as LocatorValue, j as DriverPage, s as DriverDownload, d as ContextOptions, D as DriverContext, b as PageNetworkEntry, W as WebDriver } from '../interfaces-DDp6Chwx.js';
2
+ export { t as LocatorStep, u as appendStep, v as describeLocator, w as isLocatorValue, x as rootedAt } from '../interfaces-DDp6Chwx.js';
3
3
  import { Matcher, RegexLiteral, JudgeRequest, JudgeVerdict, VisualFailureRecord, SoftFailureRecord, TeardownStateRecord, TeardownFailureRecord } from '@unotest/protocol';
4
4
  import { Browser, SandboxConfig } from '../config/schema.js';
5
- import { UnotestError, RuntimeExecState } from '@unotest/core';
5
+ import { V as VariableStore, H as HostPolicy } from '../scenario-variables-CGexnWK4.js';
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-BpaIstU3.js';
8
+ import { RuntimeExecState } from '@unotest/core';
9
+ export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-q4UNIeGI.js';
9
10
  import 'zod';
10
11
  import '@unotest/dsl';
11
12
 
@@ -67,50 +68,6 @@ declare function chainGetByTitle(loc: LocatorValue, text: Matcher, options?: {
67
68
  exact?: boolean;
68
69
  }): LocatorValue;
69
70
 
70
- /** Configuration invalid or missing. Surfaces during config load / validation. */
71
- declare class ConfigError extends UnotestError {
72
- }
73
- /** A host the run would reach came from the BASE `.env` while a named
74
- * environment is active (#199). Silence here is the whole defect: the
75
- * overlay says "dev", the request goes to the production host the base
76
- * file names, and nothing in the output says which host was used. The
77
- * message names the variable, BOTH files, and the two ways out. */
78
- declare class EnvOverlayHostError extends ConfigError {
79
- constructor(context: {
80
- name: string;
81
- /** Where the name becomes a host, quoted as the author wrote it —
82
- * `apiCall {base: "API_BASE_CHAT"}`, `goto(APP_URL)`, `baseUrl`. */
83
- usage: string;
84
- envName: string;
85
- /** Project-relative file the value actually came from. */
86
- baseFile: string;
87
- /** The overlay that does NOT set it — where it belongs. */
88
- overlayFile: string;
89
- });
90
- }
91
-
92
- /**
93
- * What a host-using call site may ask. A narrow port (ISP) so the linter
94
- * and the DSL runtime depend on the QUESTION, not on the config layer:
95
- * `rejectAsHost` answers with the refusal message, or undefined when the
96
- * name is fine to use as a host here.
97
- */
98
- interface HostVariableCheck {
99
- rejectAsHost(name: string, usage: string): EnvOverlayHostError | undefined;
100
- }
101
- /** The policy as the places that switch environments need it: the same
102
- * question, plus "the same rule, for a different environment". `forEnv`
103
- * carries the config-derived `shared` list ACROSS, which is why the MCP
104
- * server and the child it spawns cannot end up with different lists. */
105
- interface HostPolicy extends HostVariableCheck {
106
- forEnv(envName?: string): HostPolicy;
107
- /** The base-URL variable is a host by construction — `APP_BASE_URL`
108
- * becomes `config.baseUrl`, which every relative `goto` resolves
109
- * against. Asked without naming it, so no consumer keeps a second
110
- * literal of the name. */
111
- rejectBaseUrl(usage: string): EnvOverlayHostError | undefined;
112
- }
113
-
114
71
  interface Logger {
115
72
  info(msg: string, ...rest: unknown[]): void;
116
73
  warn(msg: string, ...rest: unknown[]): void;
@@ -180,38 +137,6 @@ declare class SecretRegistry {
180
137
  private redactNumber;
181
138
  }
182
139
 
183
- /** Read-only lookup over external scenario variables. */
184
- interface VariableStore {
185
- has(name: string): boolean;
186
- get(name: string): string | undefined;
187
- /** Host policy for the environment this store resolves against (#199).
188
- * Optional like `describeSources`: a store built without a project
189
- * behind it (test fakes, ad-hoc runtimes) carries none and the rule is
190
- * then off. `withHostPolicy` (config/env-host-guard.ts) is what puts
191
- * one on a store. */
192
- hostPolicy?: HostPolicy;
193
- /** One-line, human/agent-readable summary of WHERE lookups searched
194
- * (active environment + layer files, missing ones flagged). Optional so
195
- * test fakes stay two-method; consumed by "variable not found" errors. */
196
- describeSources?(): string;
197
- /** Whether `name` holds a credential — from a `.secrets` file, or a
198
- * secret a box injected. Optional like `describeSources`: a store that
199
- * cannot tell (test fakes) leaves it out, and a caller that must not
200
- * hand a secret out then refuses rather than guess. */
201
- isSecret?(name: string): boolean;
202
- /** Why `name` is refused although the environment may hold it — the
203
- * runner's own credential (`withOwnSecretsDenied`,
204
- * config/own-secrets-deny.ts). Optional like `describeSources`; a
205
- * caller that reports a missing name asks this first, so the reader
206
- * learns whose the name is instead of hunting a typo. */
207
- denial?(name: string): string | undefined;
208
- /** The file that declares `name` without giving it a value (a `.example`
209
- * twin), when no layer and no shell has one. Optional like `denial`: a
210
- * store that cannot tell leaves it out, and the caller then reports the
211
- * name as undeclared. */
212
- declaredOnlyIn?(name: string): string | undefined;
213
- }
214
-
215
140
  interface Judge {
216
141
  /** Produce a structured verdict. A clean `fail` is a RESULT (returned);
217
142
  * infrastructure faults throw JudgeUnavailableError / ConfigError. */
@@ -392,6 +317,9 @@ interface VisualAssertDeps {
392
317
  /** The names this run has given, to refuse two that became one file. */
393
318
  names: BaselineNames;
394
319
  backdrop?: BackdropFilterNotice;
320
+ /** The engine this run plays, named in a verdict: each one has its own
321
+ * baseline once the suite lists several. */
322
+ engine?: Browser;
395
323
  }
396
324
 
397
325
  type FrameFormat = "png" | "webp";
@@ -407,6 +335,10 @@ interface ScreenshotSink {
407
335
  * in the same sequence as the pictures; the event says `redacted`.
408
336
  * Returns the project-relative path it landed at. */
409
337
  saveMaskedText(name: string, text: string): Promise<string>;
338
+ /** Persist why a capture did not happen (a capture that ran out of
339
+ * time), in the same sequence, so a green run still shows where its
340
+ * evidence is missing and why. Returns the project-relative path. */
341
+ saveCaptureError(name: string, reason: string): Promise<string>;
410
342
  }
411
343
 
412
344
  interface SavedDownload {
@@ -422,7 +354,14 @@ interface DownloadSink {
422
354
  save(download: DriverDownload): Promise<SavedDownload>;
423
355
  }
424
356
 
357
+ /** What the browser window looks like: a device preset, an explicit
358
+ * size, or both (the size overrides the preset's). */
359
+ type Display = Pick<ContextOptions, "device" | "viewport">;
360
+
425
361
  type ContextFactory = () => Promise<DriverContext>;
362
+ /** How the runner opens one more context with the entry's options — on
363
+ * `display` instead of the entry's window when one is asked for. */
364
+ type ContextOpener = (display?: Display) => Promise<DriverContext>;
426
365
  /** How the runner opens a context on a browser profile of its own
427
366
  * (`newContext({profile})`). It owns what a directory name means: where a
428
367
  * relative one starts, that it exists. */
@@ -430,7 +369,7 @@ interface ProfileContexts {
430
369
  /** The directory as the browser will open it: absolute, made if it was
431
370
  * missing, symlinks resolved — the form two names of one directory agree on. */
432
371
  resolve(dir: string): string;
433
- open(resolvedDir: string): Promise<DriverContext>;
372
+ open(resolvedDir: string, display?: Display): Promise<DriverContext>;
434
373
  /** Whether `resolvedDir` is the profile directory the run's own context
435
374
  * sits on (a run on `launch.userDataDir`, or a browser per test). */
436
375
  isRunProfile(resolvedDir: string): boolean;
@@ -438,10 +377,16 @@ interface ProfileContexts {
438
377
  /** How the runner opens a context in a browser it joins over CDP
439
378
  * (`newContext({cdpEndpoint})`): a browser somebody else started, left
440
379
  * running when the test ends. */
441
- type RemoteContextFactory = (endpoint: string) => Promise<DriverContext>;
380
+ type RemoteContextFactory = (endpoint: string, display?: Display) => Promise<DriverContext>;
442
381
  interface NewContextTarget {
443
382
  profile?: string;
444
383
  cdpEndpoint?: string;
384
+ /** Request headers every page of the new context sends — on whichever
385
+ * of the three it opens in, set before the scenario's first goto there. */
386
+ headers?: Readonly<Record<string, string>>;
387
+ /** The window the new context opens on, over the entry's — the scale
388
+ * is fixed when a context opens, so it cannot be set afterwards. */
389
+ display?: Display;
445
390
  }
446
391
  /** A context that did not close — reported, never swallowed. */
447
392
  interface ContextCloseFailure {
@@ -463,7 +408,7 @@ declare class ContextSet {
463
408
  /** Called with the new active index on every switch (open or select). */
464
409
  private readonly listeners;
465
410
  constructor(first: DriverContext | ContextFactory, opts?: {
466
- open?: ContextFactory;
411
+ open?: ContextOpener;
467
412
  profiles?: ProfileContexts;
468
413
  remote?: RemoteContextFactory;
469
414
  max?: number;
@@ -481,6 +426,7 @@ declare class ContextSet {
481
426
  * browser profile of its own when `profile` names a directory, in a
482
427
  * browser somebody else runs when `cdpEndpoint` names one. */
483
428
  open(target?: NewContextTarget): Promise<number>;
429
+ private openOn;
484
430
  private openRemote;
485
431
  private openProfile;
486
432
  /** Context 0 first, then room under the ceiling, then the new one —
@@ -745,6 +691,8 @@ declare class TerminalSet {
745
691
  /** The active window, or none — for a failure bundle, which must not
746
692
  * fail over a test that never opened a terminal. */
747
693
  current(): TerminalSession | undefined;
694
+ /** The index of the active window while it is open, else none. */
695
+ activeIndex(): number | undefined;
748
696
  /** A frame of `session` fit to leave the run: its picture, or its
749
697
  * masked screen text when a secret is on the screen. */
750
698
  frame(session: TerminalSession): Promise<GuardedFrame>;
@@ -828,8 +776,10 @@ interface McpConnectionEvents {
828
776
  onClose(): void;
829
777
  }
830
778
  interface McpConnection {
831
- /** `tools/call`; resolves with the result as the server sent it. */
832
- callTool(tool: string, args: Readonly<Record<string, unknown>>, timeoutMs: number): Promise<Record<string, unknown>>;
779
+ /** `tools/call`; resolves with the result as the server sent it. The
780
+ * request has no deadline of its own: the caller ends it through
781
+ * `signal`, and the abort reason is what the call rejects with. */
782
+ callTool(tool: string, args: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<Record<string, unknown>>;
833
783
  /** The tail of what the server wrote to stderr — a crash says why there. */
834
784
  stderrTail(): string;
835
785
  close(): Promise<void>;
@@ -852,10 +802,17 @@ interface JsonFilter {
852
802
  describe(): string;
853
803
  }
854
804
 
805
+ type McpJournalLevel = 'info' | 'warn';
855
806
  /** Where the session reports calls, results and notifications — the
856
- * run's journal. Must not throw: reporting never fails a step. */
807
+ * run's journal. Must not throw: reporting never fails a step. A `warn`
808
+ * record is something the scenario left undone that does not fail it. */
857
809
  interface McpJournal {
858
- record(label: string, text: string): Promise<void>;
810
+ record(label: string, text: string, level?: McpJournalLevel): Promise<void>;
811
+ }
812
+ interface McpResultOptions {
813
+ /** Counted from when the result is asked for, not from the start. */
814
+ timeoutMs: number;
815
+ allowError: boolean;
859
816
  }
860
817
  interface McpWaitSpec {
861
818
  method: string;
@@ -873,17 +830,28 @@ declare class McpSession {
873
830
  private last;
874
831
  private readonly pending;
875
832
  private readonly waiters;
833
+ private readonly calls;
834
+ /** Calls whose result was taken, by id: their tool, for the refusal. */
835
+ private readonly taken;
836
+ private callsStarted;
876
837
  private closed;
877
838
  private stopping;
878
839
  private constructor();
879
840
  static start(connector: McpConnector, spec: McpServerSpec, label: string, journal: McpJournal, timeoutMs: number): Promise<McpSession>;
880
841
  get isClosed(): boolean;
881
- call(tool: string, args: Readonly<Record<string, unknown>>, opts: {
882
- timeoutMs: number;
883
- allowError: boolean;
884
- }): Promise<Record<string, unknown>>;
842
+ /** mcpCall: the request and its answer in one step. */
843
+ call(tool: string, args: Readonly<Record<string, unknown>>, opts: McpResultOptions): Promise<Record<string, unknown>>;
844
+ /** Sends `tools/call` and returns the id its answer is kept under. */
845
+ startCall(fnName: string, tool: string, args: Readonly<Record<string, unknown>>): Promise<string>;
846
+ /** The answer of a started call, once. No answer within `timeoutMs`
847
+ * cancels the request: there is no polling a call with short waits. */
848
+ result(fnName: string, id: string, opts: McpResultOptions): Promise<Record<string, unknown>>;
885
849
  waitNotification(spec: McpWaitSpec): Promise<Record<string, unknown>>;
886
850
  stop(): Promise<void>;
851
+ private take;
852
+ /** Calls the scenario started and never took: a warning, not a red
853
+ * step — their answers are dropped with the server. */
854
+ private dropUnclaimed;
887
855
  private open;
888
856
  private observe;
889
857
  private deliver;
@@ -900,6 +868,15 @@ interface McpHandle {
900
868
  readonly id: string;
901
869
  readonly command: string;
902
870
  }
871
+ /** A call mcpCallStart sent, as the scenario holds it; its answer waits in
872
+ * the server's session, behind the id. */
873
+ interface McpCallHandle {
874
+ readonly kind: 'mcpCall';
875
+ /** `<server id>/<call id>`, unique within the test. */
876
+ readonly id: string;
877
+ readonly server: string;
878
+ readonly tool: string;
879
+ }
903
880
  interface McpSessionsDeps {
904
881
  connector: McpConnector;
905
882
  journal: McpJournal;
@@ -917,6 +894,8 @@ declare class McpSessions {
917
894
  }): Promise<McpHandle>;
918
895
  /** The session behind a handle the scenario passed in. */
919
896
  get(fnName: string, handle: unknown): McpSession;
897
+ startCall(fnName: string, handle: unknown, tool: string, args: Readonly<Record<string, unknown>>): Promise<McpCallHandle>;
898
+ result(fnName: string, handle: unknown, opts: McpResultOptions): Promise<Record<string, unknown>>;
920
899
  stop(fnName: string, handle: unknown): Promise<void>;
921
900
  /** Stops the server if the scenario has not — what mcpStart leaves to
922
901
  * the end of the test. */
@@ -939,7 +918,7 @@ type RuntimeContexts = {
939
918
  readonly context: DriverContext | ContextFactory;
940
919
  /** Opens one more context with the entry's options (`newContext()`).
941
920
  * Absent → the runtime cannot add one (an attached debug session). */
942
- readonly openContext?: ContextFactory;
921
+ readonly openContext?: ContextOpener;
943
922
  /** Opens a context on a browser profile of its own
944
923
  * (`newContext({profile})`). Absent → it cannot be. */
945
924
  readonly profiles?: ProfileContexts;
@@ -1087,8 +1066,9 @@ declare class TestRuntime {
1087
1066
  get hostPolicy(): HostPolicy | undefined;
1088
1067
  getVar(name: string): DslValue;
1089
1068
  /** Direct external-variable lookup (`unotest/.env` / `.secrets`), no
1090
- * scope fallback, no throw. Used by shell() to resolve the
1091
- * `sandbox.exportSecrets` allowlist into subprocess env. */
1069
+ * scope fallback, no throw. The one place an empty value becomes "not
1070
+ * set on this environment" (#472): the bare name, `env()`, shell()'s
1071
+ * `sandbox.exportSecrets` and `apiCall`'s `{base}` all read through it. */
1092
1072
  externalVar(name: string): string | undefined;
1093
1073
  /** Whether external variable `name` is a secret; undefined when the
1094
1074
  * variable store cannot tell. Used by `env()`, which never hands one out. */