@unotest/web 0.56.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 (35) hide show
  1. package/.claude/skills/write-e2e-test/SKILL.md +14 -0
  2. package/.claude/skills/write-e2e-test-ground/SKILL.md +14 -0
  3. package/CHANGELOG.md +147 -3
  4. package/README.md +3 -3
  5. package/bin/unotest-web.js +13 -0
  6. package/dist/config/schema.d.ts +15 -15
  7. package/dist/config/schema.js +1 -1
  8. package/dist/driver/index.d.ts +10 -2
  9. package/dist/driver/index.js +1 -1
  10. package/dist/dsl/index.d.ts +66 -16
  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 +2 -2
  14. package/dist/dsl/web-dsl-language-service.js +1 -1
  15. package/dist/inspection/page-inject.d.ts +34 -2
  16. package/dist/inspection/page-inject.js +119 -0
  17. package/dist/{interfaces-BiGd3BdD.d.ts → interfaces-DDp6Chwx.d.ts} +148 -6
  18. package/dist/{linter-DIAb0JOB.d.ts → linter-q4UNIeGI.d.ts} +12 -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-B-ULUTHt.d.ts → scenario-variables-CGexnWK4.d.ts} +18 -0
  30. package/examples/idioms/wait-enabled.js +6 -3
  31. package/guides/agent-integration.md +2 -2
  32. package/guides/dsl-reference.md +388 -17
  33. package/llms.txt +14 -4
  34. package/package.json +8 -8
  35. package/types/unotest-dsl.d.ts +80 -10
@@ -1,12 +1,12 @@
1
- import { L as LocatorValue, j as DriverPage, r as DriverDownload, D as DriverContext, b as PageNetworkEntry, W as WebDriver } from '../interfaces-BiGd3BdD.js';
2
- export { s as LocatorStep, t as appendStep, u as describeLocator, v as isLocatorValue, w as rootedAt } from '../interfaces-BiGd3BdD.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 { V as VariableStore, H as HostPolicy } from '../scenario-variables-B-ULUTHt.js';
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
8
  import { RuntimeExecState } from '@unotest/core';
9
- export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-DIAb0JOB.js';
9
+ export { L as LintDiagnostic, b as LintOptions, a as LintSeverity, l as lintAst } from '../linter-q4UNIeGI.js';
10
10
  import 'zod';
11
11
  import '@unotest/dsl';
12
12
 
@@ -317,6 +317,9 @@ interface VisualAssertDeps {
317
317
  /** The names this run has given, to refuse two that became one file. */
318
318
  names: BaselineNames;
319
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;
320
323
  }
321
324
 
322
325
  type FrameFormat = "png" | "webp";
@@ -351,7 +354,14 @@ interface DownloadSink {
351
354
  save(download: DriverDownload): Promise<SavedDownload>;
352
355
  }
353
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
+
354
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>;
355
365
  /** How the runner opens a context on a browser profile of its own
356
366
  * (`newContext({profile})`). It owns what a directory name means: where a
357
367
  * relative one starts, that it exists. */
@@ -359,7 +369,7 @@ interface ProfileContexts {
359
369
  /** The directory as the browser will open it: absolute, made if it was
360
370
  * missing, symlinks resolved — the form two names of one directory agree on. */
361
371
  resolve(dir: string): string;
362
- open(resolvedDir: string): Promise<DriverContext>;
372
+ open(resolvedDir: string, display?: Display): Promise<DriverContext>;
363
373
  /** Whether `resolvedDir` is the profile directory the run's own context
364
374
  * sits on (a run on `launch.userDataDir`, or a browser per test). */
365
375
  isRunProfile(resolvedDir: string): boolean;
@@ -367,10 +377,16 @@ interface ProfileContexts {
367
377
  /** How the runner opens a context in a browser it joins over CDP
368
378
  * (`newContext({cdpEndpoint})`): a browser somebody else started, left
369
379
  * running when the test ends. */
370
- type RemoteContextFactory = (endpoint: string) => Promise<DriverContext>;
380
+ type RemoteContextFactory = (endpoint: string, display?: Display) => Promise<DriverContext>;
371
381
  interface NewContextTarget {
372
382
  profile?: string;
373
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;
374
390
  }
375
391
  /** A context that did not close — reported, never swallowed. */
376
392
  interface ContextCloseFailure {
@@ -392,7 +408,7 @@ declare class ContextSet {
392
408
  /** Called with the new active index on every switch (open or select). */
393
409
  private readonly listeners;
394
410
  constructor(first: DriverContext | ContextFactory, opts?: {
395
- open?: ContextFactory;
411
+ open?: ContextOpener;
396
412
  profiles?: ProfileContexts;
397
413
  remote?: RemoteContextFactory;
398
414
  max?: number;
@@ -410,6 +426,7 @@ declare class ContextSet {
410
426
  * browser profile of its own when `profile` names a directory, in a
411
427
  * browser somebody else runs when `cdpEndpoint` names one. */
412
428
  open(target?: NewContextTarget): Promise<number>;
429
+ private openOn;
413
430
  private openRemote;
414
431
  private openProfile;
415
432
  /** Context 0 first, then room under the ceiling, then the new one —
@@ -674,6 +691,8 @@ declare class TerminalSet {
674
691
  /** The active window, or none — for a failure bundle, which must not
675
692
  * fail over a test that never opened a terminal. */
676
693
  current(): TerminalSession | undefined;
694
+ /** The index of the active window while it is open, else none. */
695
+ activeIndex(): number | undefined;
677
696
  /** A frame of `session` fit to leave the run: its picture, or its
678
697
  * masked screen text when a secret is on the screen. */
679
698
  frame(session: TerminalSession): Promise<GuardedFrame>;
@@ -757,8 +776,10 @@ interface McpConnectionEvents {
757
776
  onClose(): void;
758
777
  }
759
778
  interface McpConnection {
760
- /** `tools/call`; resolves with the result as the server sent it. */
761
- 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>>;
762
783
  /** The tail of what the server wrote to stderr — a crash says why there. */
763
784
  stderrTail(): string;
764
785
  close(): Promise<void>;
@@ -781,10 +802,17 @@ interface JsonFilter {
781
802
  describe(): string;
782
803
  }
783
804
 
805
+ type McpJournalLevel = 'info' | 'warn';
784
806
  /** Where the session reports calls, results and notifications — the
785
- * 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. */
786
809
  interface McpJournal {
787
- 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;
788
816
  }
789
817
  interface McpWaitSpec {
790
818
  method: string;
@@ -802,17 +830,28 @@ declare class McpSession {
802
830
  private last;
803
831
  private readonly pending;
804
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;
805
837
  private closed;
806
838
  private stopping;
807
839
  private constructor();
808
840
  static start(connector: McpConnector, spec: McpServerSpec, label: string, journal: McpJournal, timeoutMs: number): Promise<McpSession>;
809
841
  get isClosed(): boolean;
810
- call(tool: string, args: Readonly<Record<string, unknown>>, opts: {
811
- timeoutMs: number;
812
- allowError: boolean;
813
- }): 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>>;
814
849
  waitNotification(spec: McpWaitSpec): Promise<Record<string, unknown>>;
815
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;
816
855
  private open;
817
856
  private observe;
818
857
  private deliver;
@@ -829,6 +868,15 @@ interface McpHandle {
829
868
  readonly id: string;
830
869
  readonly command: string;
831
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
+ }
832
880
  interface McpSessionsDeps {
833
881
  connector: McpConnector;
834
882
  journal: McpJournal;
@@ -846,6 +894,8 @@ declare class McpSessions {
846
894
  }): Promise<McpHandle>;
847
895
  /** The session behind a handle the scenario passed in. */
848
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>>;
849
899
  stop(fnName: string, handle: unknown): Promise<void>;
850
900
  /** Stops the server if the scenario has not — what mcpStart leaves to
851
901
  * the end of the test. */
@@ -868,7 +918,7 @@ type RuntimeContexts = {
868
918
  readonly context: DriverContext | ContextFactory;
869
919
  /** Opens one more context with the entry's options (`newContext()`).
870
920
  * Absent → the runtime cannot add one (an attached debug session). */
871
- readonly openContext?: ContextFactory;
921
+ readonly openContext?: ContextOpener;
872
922
  /** Opens a context on a browser profile of its own
873
923
  * (`newContext({profile})`). Absent → it cannot be. */
874
924
  readonly profiles?: ProfileContexts;