@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
@@ -112,7 +112,10 @@ interface Viewport extends Partial<ViewportSize> {
112
112
  /** Device pixels per CSS pixel. Fixed for the life of a context. */
113
113
  deviceScaleFactor?: number;
114
114
  }
115
- interface ContextOptions {
115
+ /** `reducedMotion` / `colorScheme` (EmulatedMedia) are the media
116
+ * features every page of the context reports from its first document —
117
+ * unset, the browser's own. */
118
+ interface ContextOptions extends EmulatedMedia {
116
119
  baseUrl?: string;
117
120
  /** A device preset by name — the driver owns the list and refuses a
118
121
  * name it does not know. Applied before `viewport`, which overrides the
@@ -137,6 +140,9 @@ interface ContextOptions {
137
140
  locale?: string;
138
141
  /** Timezone, e.g. "Europe/Moscow". */
139
142
  timezoneId?: string;
143
+ /** Request headers every page of the context sends with every request
144
+ * (Playwright `extraHTTPHeaders`) — a token a host lets the app in with. */
145
+ headers?: Readonly<Record<string, string>>;
140
146
  /**
141
147
  * Default action timeout in milliseconds — applied to every Playwright
142
148
  * `click` / `fill` / `waitFor` / etc. via `context.setDefaultTimeout`.
@@ -177,6 +183,37 @@ interface ClickOptions extends ActionTimeout {
177
183
  /** Number of clicks. Default: 1. */
178
184
  clickCount?: number;
179
185
  }
186
+ /** A point inside an element, in CSS pixels from its top-left corner. */
187
+ interface ElementPoint {
188
+ x: number;
189
+ y: number;
190
+ }
191
+ interface DragOptions extends ActionTimeout {
192
+ force?: boolean;
193
+ /** Where the drag takes hold of the source. Default: its centre. */
194
+ sourcePosition?: ElementPoint;
195
+ /** Where the drag lets go on the target. Default: its centre. */
196
+ targetPosition?: ElementPoint;
197
+ }
198
+ /** A drag by an offset has no target element to land on. */
199
+ type DragByOptions = Omit<DragOptions, "targetPosition">;
200
+ /** One finger down and up — the touch counterpart of a click. */
201
+ interface TapOptions extends ActionTimeout {
202
+ /** Where the finger lands inside the element. Default: its centre. */
203
+ position?: ElementPoint;
204
+ }
205
+ /** One finger held on the element before it lifts. */
206
+ interface LongPressOptions extends TapOptions {
207
+ /** How long the finger stays down, in ms. Default: `LONG_PRESS_MS`. */
208
+ durationMs?: number;
209
+ }
210
+ /** One finger put down on the element and moved by an offset. */
211
+ interface SwipeOptions extends ActionTimeout {
212
+ /** Where the finger goes down inside the element. Default: its centre. */
213
+ sourcePosition?: ElementPoint;
214
+ /** How long the move takes, in ms. Default: `SWIPE_MS`. */
215
+ durationMs?: number;
216
+ }
180
217
  interface FillOptions extends ActionTimeout {
181
218
  force?: boolean;
182
219
  }
@@ -270,6 +307,9 @@ interface ScreenshotOptions {
270
307
  animations?: "disabled" | "allow";
271
308
  /** `"hide"` — the text caret is not drawn (it blinks). Default `"initial"`. */
272
309
  caret?: "hide" | "initial";
310
+ /** How long the capture may take. Default: the context's
311
+ * `defaultTimeoutMs`. */
312
+ timeoutMs?: number;
273
313
  }
274
314
  /** Encoding options for an element capture — `ScreenshotOptions` minus
275
315
  * the page-geometry fields (`fullPage`, `clip`) that have no meaning for a
@@ -415,6 +455,30 @@ interface PageNetworkEntry {
415
455
  /** When the request was sent, epoch ms (as `nowMs()`). */
416
456
  at: number;
417
457
  }
458
+ type WebSocketDirection = "sent" | "received";
459
+ /** One frame of a WebSocket the page opened, kept from the page's last
460
+ * load on. A text frame has `text`, and `json` when it parses; a binary
461
+ * one has its `size` in bytes only. */
462
+ type WebSocketFrame = {
463
+ url: string;
464
+ direction: WebSocketDirection;
465
+ text: string;
466
+ json: unknown;
467
+ at: number;
468
+ } | {
469
+ url: string;
470
+ direction: WebSocketDirection;
471
+ size: number;
472
+ json: null;
473
+ at: number;
474
+ };
475
+ /** Which frames a `waitForWebSocketFrame` takes beyond its mask and
476
+ * direction; `text` is the condition as the scenario wrote it, for the
477
+ * timeout to quote. */
478
+ interface WebSocketFrameMatch {
479
+ accepts(frame: WebSocketFrame): boolean;
480
+ text: string;
481
+ }
418
482
  /** A file a page of the context downloaded. The bytes stay with the
419
483
  * browser until `saveAs` copies them out. */
420
484
  interface DriverDownload {
@@ -520,6 +584,11 @@ interface BlockedRequest {
520
584
  * where several match one request, the one mocked last answers it, and
521
585
  * mocking a mask again replaces its answer and makes it the latest.
522
586
  * Mocks last as long as the context. */
587
+ interface RequestWaitOptions {
588
+ timeoutMs: number;
589
+ /** Upper-case HTTP method; absent → a request of any method. */
590
+ method?: string;
591
+ }
523
592
  interface DriverNetwork {
524
593
  mock(glob: string, response: RouteResponse): Promise<void>;
525
594
  /** Take off the mock at `glob`, or every mock when it is omitted.
@@ -528,15 +597,25 @@ interface DriverNetwork {
528
597
  /** The next request matching `glob` not yet returned by an earlier
529
598
  * wait. A mocked mask keeps its requests from the moment it was
530
599
  * mocked, so one sent before the wait is still found; any other mask
531
- * sees requests from the call on. Throws TimeoutError after `timeoutMs`. */
532
- waitForRequest(glob: string, opts: {
533
- timeoutMs: number;
534
- }): Promise<CapturedRequest>;
600
+ * sees requests from the call on. With `method` (upper case) only a
601
+ * request of that method is taken; one of another method stays for the
602
+ * next wait. Throws TimeoutError after `timeoutMs`. */
603
+ waitForRequest(glob: string, opts: RequestWaitOptions): Promise<CapturedRequest>;
535
604
  /** The requests stopped by the recording abort at `glob`. Throws when
536
605
  * `glob` was never mocked with a recording abort: an empty answer
537
606
  * would then mean "nothing was watched", not "nothing left". */
538
607
  blocked(glob: string): ReadonlyArray<BlockedRequest>;
539
608
  }
609
+ /** The answer `closePage` gives the page's "Leave site?" prompt. */
610
+ type BeforeUnloadAnswer = "leave" | "stay";
611
+ interface ClosePageOptions {
612
+ beforeUnload?: BeforeUnloadAnswer;
613
+ }
614
+ /** `asked` — the page showed the prompt; `closed` — the tab is gone. */
615
+ interface ClosePageResult {
616
+ asked: boolean;
617
+ closed: boolean;
618
+ }
540
619
  interface DriverContext {
541
620
  /** Currently-open tabs/windows in this context. Index 0 = first opened. */
542
621
  pages(): ReadonlyArray<DriverPage>;
@@ -563,6 +642,10 @@ interface DriverContext {
563
642
  * shown; asking for the state it is in changes nothing. Absent index →
564
643
  * the active page. Throws `DriverError` on an index no open tab has. */
565
644
  setPageHidden(hidden: boolean, index?: number): Promise<void>;
645
+ /** Request headers every page of this context sends from now on, every
646
+ * tab and every request — what `ContextOptions.headers` sets at open
647
+ * time, for a context somebody else opened (a profile, a joined browser). */
648
+ setHeaders(headers: Readonly<Record<string, string>>): Promise<void>;
566
649
  /** Open a blank tab in this context and make it the active page (brought
567
650
  * to front, frame stack reset). It counts as handed: `waitForNewPage`
568
651
  * never returns it. Resolves with its index. */
@@ -571,8 +654,17 @@ interface DriverContext {
571
654
  * makes the page that was active before it active again (the one at the
572
655
  * index below when that one is gone); closing another tab keeps the
573
656
  * active page. Throws `DriverError` on an index no open tab has, and on
574
- * the only open tab — nothing would be left to drive. */
575
- closePage(index?: number): Promise<void>;
657
+ * the only open tab — nothing would be left to drive.
658
+ *
659
+ * `beforeUnload` closes as a person does: the page's `beforeunload`
660
+ * runs, and its "Leave site?" prompt gets the answer given — `leave`
661
+ * closes, `stay` keeps the tab, the active page and the frame stack as
662
+ * they were. The context's dialog policy does not answer that prompt.
663
+ * Engines ask only after a user gesture on the page (a fill alone is
664
+ * none to Firefox). Without the option the tab closes as before, no
665
+ * `beforeunload` run. Throws `TimeoutError`
666
+ * when the tab neither closes nor asks within the action timeout. */
667
+ closePage(index?: number, opts?: ClosePageOptions): Promise<ClosePageResult>;
576
668
  /**
577
669
  * Subscribe to new-page events. Listener fires when a tab/window opens
578
670
  * in this context (`target="_blank"`, `window.open`, etc.). Returns an
@@ -658,7 +750,11 @@ interface DriverContext {
658
750
  /** Typed storage shortcuts (D-6). */
659
751
  setLocalStorage(key: string, value: string): Promise<void>;
660
752
  getLocalStorage(key: string): Promise<string | null>;
753
+ /** Writes the cookie into the context's jar; throws CookieRejectedError
754
+ * when the browser does not keep it (a cookie set already expired is a
755
+ * deletion and passes). */
661
756
  setCookie(name: string, value: string, opts?: CookieOptions): Promise<void>;
757
+ /** The jar's value — every domain and path, httpOnly too. */
662
758
  getCookie(name: string): Promise<string | null>;
663
759
  /**
664
760
  * Persist current storage state to disk (D-23 opt-in caching). Used by
@@ -737,8 +833,20 @@ interface DriverPage {
737
833
  selectOption(loc: LocatorValue, value: SelectOptionValue, opts?: SelectOptions): Promise<void>;
738
834
  hover(loc: LocatorValue, opts?: HoverOptions): Promise<void>;
739
835
  scrollIntoView(loc: LocatorValue): Promise<void>;
740
- /** Drag the source element onto the target. */
741
- dragAndDrop(from: LocatorValue, to: LocatorValue, opts?: ClickOptions): Promise<void>;
836
+ /** Drag the source element onto the target, each at its centre or at
837
+ * the point the options name. */
838
+ dragAndDrop(from: LocatorValue, to: LocatorValue, opts?: DragOptions): Promise<void>;
839
+ /** Take hold of the element (its centre or `sourcePosition`) and move
840
+ * the pointer `dx`, `dy` CSS pixels before letting go — a resize
841
+ * handle, a slider, a selection box on a canvas. */
842
+ dragBy(loc: LocatorValue, dx: number, dy: number, opts?: DragByOptions): Promise<void>;
843
+ /** Finger down and up on the element (its centre or `position`). */
844
+ tap(loc: LocatorValue, opts?: TapOptions): Promise<void>;
845
+ /** Finger held on the element for `durationMs` before it lifts. */
846
+ longPress(loc: LocatorValue, opts?: LongPressOptions): Promise<void>;
847
+ /** Finger down on the element (its centre or `sourcePosition`), moved
848
+ * `dx`, `dy` CSS pixels over `durationMs`, lifted at the end. */
849
+ swipe(loc: LocatorValue, dx: number, dy: number, opts?: SwipeOptions): Promise<void>;
742
850
  /** Set the input element's selected files. Accepts a path, path[], or an in-memory file buffer. */
743
851
  uploadFile(loc: LocatorValue, files: string | ReadonlyArray<string> | {
744
852
  name: string;
@@ -767,6 +875,10 @@ interface DriverPage {
767
875
  * `value` is the submitted payload ("on" by default), never its state. */
768
876
  checkedState(loc: LocatorValue): Promise<boolean | null>;
769
877
  isVisible(loc: LocatorValue): Promise<boolean>;
878
+ /** The share of the matched element inside the viewport, 0..1 — ancestors
879
+ * that clip by overflow count, as in Playwright's `toBeInViewport`. No
880
+ * scrolling. */
881
+ viewportRatio(loc: LocatorValue): Promise<number>;
770
882
  /** Where the matched element lies in the viewport, CSS pixels; `null`
771
883
  * when it is not rendered (display:none, detached). No scrolling. */
772
884
  boundingBox(loc: LocatorValue): Promise<BoundingBox | null>;
@@ -781,6 +893,13 @@ interface DriverPage {
781
893
  * `getComputedStyle(el).getPropertyValue(property)` gives it — custom
782
894
  * properties (`--accent`) included; "" for one that is not set. */
783
895
  computedStyle(loc: LocatorValue, property: string): Promise<string>;
896
+ /** The fields a phone browser zooms into on focus when their text is
897
+ * small — visible, enabled, writable text-like inputs, textareas,
898
+ * selects and contenteditable hosts — inside `scope` (itself included),
899
+ * the whole document of the active frame when absent; with the zoom
900
+ * limits of the document's `<meta name="viewport">`. A read, no
901
+ * threshold: what counts as small is the caller's rule. */
902
+ focusZoomFields(scope?: LocatorValue): Promise<FocusZoomRead>;
784
903
  /** Natural size of the matched `<img>` once it has settled (loaded or
785
904
  * failed), within the action timeout; `null` when it has no pixels —
786
905
  * broken, or no src. The one query that waits: "still loading" is not
@@ -813,6 +932,18 @@ interface DriverPage {
813
932
  }): Promise<{
814
933
  url: string;
815
934
  }>;
935
+ /** The first frame of a socket matching `glob` that no earlier call has
936
+ * taken — one that came before the call counts — and takes it. Throws
937
+ * `TimeoutError` naming the sockets and the last frames. */
938
+ waitForWebSocketFrame(glob: string, opts: {
939
+ timeoutMs: number;
940
+ direction?: WebSocketDirection;
941
+ match?: WebSocketFrameMatch;
942
+ }): Promise<WebSocketFrame>;
943
+ /** Every frame kept of the sockets matching `glob`, oldest first; takes none. */
944
+ webSocketFrames(glob: string, opts?: {
945
+ direction?: WebSocketDirection;
946
+ }): ReadonlyArray<WebSocketFrame>;
816
947
  /** Change the media features this page reports, from now on: what
817
948
  * `matchMedia` and CSS `@media` see. A feature left out keeps its
818
949
  * current value. This page only — a tab opened later starts without it. */
@@ -841,6 +972,9 @@ interface DriverPage {
841
972
  /** `evaluate` on the matched element: a function body is called with
842
973
  * the element and `arg`. */
843
974
  evaluateOnLocator<T = unknown>(loc: LocatorValue, js: string, arg?: unknown): Promise<T>;
975
+ /** `document.cookie` of the scope (the innermost entered frame, else the
976
+ * page): the cookies its script is given — no httpOnly ones. */
977
+ documentCookie(): Promise<string>;
844
978
  screenshot(opts?: ScreenshotOptions): Promise<Buffer>;
845
979
  /** Capture ONE element (first match, scrolled into view) instead of the
846
980
  * viewport — the evidence shot of a card / row / dialog. Same encoding
@@ -878,6 +1012,29 @@ interface BoundingBox {
878
1012
  width: number;
879
1013
  height: number;
880
1014
  }
1015
+ /** One field `focusZoomFields` found. `fontPx` is its computed font size in
1016
+ * CSS pixels; the reader sees it times the read's `scale`. */
1017
+ interface FocusZoomField {
1018
+ /** Lower-case tag name: "input", "textarea", "select", or the
1019
+ * contenteditable host's. */
1020
+ tag: string;
1021
+ /** The input's `type`; "" for anything else. */
1022
+ type: string;
1023
+ id: string;
1024
+ name: string;
1025
+ fontPx: number;
1026
+ }
1027
+ /** What `focusZoomFields` reads: the fields, the visual viewport's scale,
1028
+ * and the document's viewport meta — `deviceWidth` true when it sets
1029
+ * `width=device-width`, `maximumScale` null when not set, `userScalable`
1030
+ * false for `user-scalable=no` / `0`. */
1031
+ interface FocusZoomRead {
1032
+ fields: FocusZoomField[];
1033
+ scale: number;
1034
+ deviceWidth: boolean;
1035
+ maximumScale: number | null;
1036
+ userScalable: boolean;
1037
+ }
881
1038
  /** An image's natural size, in its own pixels. */
882
1039
  interface ImageSize {
883
1040
  width: number;
@@ -1031,4 +1188,4 @@ interface PageConsole {
1031
1188
  errors: readonly PageErrorEntry[];
1032
1189
  }
1033
1190
 
1034
- export { type AnimationInfo as A, type BoundingBox as B, type CaptureFrame as C, type DriverContext as D, type ElementHint as E, type FillOptions as F, type GotoOptions as G, type HoverOptions as H, type ImageSize as I, type LocatorValue as L, type NetworkEntry as N, type PageConsole as P, type ReloadOptions as R, type ScreenshotOptions as S, type VirtualCredential as V, type WebDriver as W, type CaptureRect as a, type PageNetworkEntry as b, type LaunchOptions as c, type ContextOptions as d, type AttachOptions as e, type ActionTimeout as f, type CheckOptions as g, type ClickOptions as h, type CookieOptions as i, type DriverPage as j, type NavigationOptions as k, type PressOptions as l, type SelectOptions as m, type Viewport as n, type ViewportSize as o, type WaitOptions as p, type WaitState as q, type DriverDownload as r, type LocatorStep as s, appendStep as t, describeLocator as u, isLocatorValue as v, rootedAt as w };
1191
+ export { type AnimationInfo as A, type BoundingBox as B, type CaptureFrame as C, type DriverContext as D, type ElementHint as E, type FocusZoomRead as F, type GotoOptions as G, type HoverOptions as H, type ImageSize as I, type LocatorValue as L, type NetworkEntry as N, type PageConsole as P, type ReloadOptions as R, type ScreenshotOptions as S, type VirtualCredential as V, type WebDriver as W, type CaptureRect as a, type PageNetworkEntry as b, type LaunchOptions as c, type ContextOptions as d, type AttachOptions as e, type ActionTimeout as f, type CheckOptions as g, type ClickOptions as h, type CookieOptions as i, type DriverPage as j, type FillOptions as k, type NavigationOptions as l, type PressOptions as m, type SelectOptions as n, type Viewport as o, type ViewportSize as p, type WaitOptions as q, type WaitState as r, type DriverDownload as s, type LocatorStep as t, appendStep as u, describeLocator as v, isLocatorValue as w, rootedAt as x };
@@ -41,6 +41,16 @@ interface ExternalVariableLookup {
41
41
  * the environment would be invisible to it — so there a template's name
42
42
  * simply counts as declared (`has`). */
43
43
  declaredOnlyIn?(name: string): string | undefined;
44
+ /** Where NAME, declared, resolves to an empty value — the layer file
45
+ * (`unotest/.env.local`) or the shell — so a bare read of it stops the
46
+ * run (#472). Undefined when it has a value. Both lookups answer it:
47
+ * `lint` from the files, a run from its store (shell included).
48
+ * Absent → `lint:external-variable-empty` is off. */
49
+ emptyIn?(name: string): string | undefined;
50
+ /** Whether some `.secrets*` file names NAME, any environment's: an
51
+ * undeclared credential is pointed at the secrets template (#469).
52
+ * Absent → only the name's ending decides. */
53
+ inSecretsFile?(name: string): boolean;
44
54
  /** Host policy of the environment this lookup describes (#199) — it
45
55
  * answers why NAME must not be used as a HOST in `usage`, or undefined
46
56
  * when the use is fine. Absent on a lookup with no project behind it,
@@ -56,6 +66,12 @@ interface ExternalVariableLookup {
56
66
  rejectBaseUrl(usage: string): {
57
67
  message: string;
58
68
  } | undefined;
69
+ /** Why a READ of NAME is worth a warning: an environment is active and
70
+ * the value still comes from the shared `.env` (#450). Optional — a
71
+ * policy that cannot tell leaves `lint:env-from-base` off. */
72
+ warnFromBase?(name: string): {
73
+ message: string;
74
+ } | undefined;
59
75
  };
60
76
  }
61
77
  interface LintOptions {
@@ -83,6 +99,10 @@ interface LintOptions {
83
99
  * sets none of its own. Absent → the rule only knows `setTestTimeout`
84
100
  * literals. */
85
101
  testBudget?: TestBudgetHint;
102
+ /** The `@unotest/web` the suite installs (`installedSuiteVersion`), when
103
+ * it differs from the one linting: a function newer than it is unknown
104
+ * to the suite's own lint and run. Absent → the rule is off. */
105
+ suiteVersion?: string;
86
106
  }
87
107
  /** A test's time budget and the setting it comes from. */
88
108
  interface TestBudgetHint {