@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,6 +1,6 @@
1
1
  import { InjectedDomHelpers } from '@unotest/grounder-client/dom-walker';
2
2
  import { PickerMode } from '@unotest/protocol';
3
- import { E as ElementHint, A as AnimationInfo } from '../interfaces-BiGd3BdD.js';
3
+ import { E as ElementHint, A as AnimationInfo, F as FocusZoomRead } from '../interfaces-DDp6Chwx.js';
4
4
  import '../config/schema.js';
5
5
  import 'zod';
6
6
 
@@ -444,6 +444,12 @@ declare function readCheckedState(el: Element): boolean | null;
444
444
  /** Disabled state — native `:disabled` (covers `<fieldset disabled>`
445
445
  * inheritance) or `aria-disabled` on a custom widget. */
446
446
  declare function readDisabledState(el: Element): boolean;
447
+ /** The share of the element inside the viewport, 0..1, as an
448
+ * IntersectionObserver reports it on its first callback — ancestors that
449
+ * clip by overflow count, the way Playwright's `toBeInViewport` reads it.
450
+ * The empty animation frame wakes engines that hold the callback until
451
+ * the next frame. */
452
+ declare function readViewportRatio(el: Element): Promise<number>;
447
453
  /** After `fill(…, {force: true})`: whether an `<input>` / `<textarea>`
448
454
  * holds `value`, and the state that kept it from taking it — readonly,
449
455
  * disabled or hidden — or null for an editable field or another element.
@@ -455,6 +461,13 @@ declare function readForcedFillState(el: Element, value: string): {
455
461
  /** Computed value of one CSS property — custom properties included, which
456
462
  * `getPropertyValue` returns with the whitespace after their colon. */
457
463
  declare function readComputedStyle(el: Element, property: string): string;
464
+ /** The fields inside `root` (itself included; the document when absent)
465
+ * that a phone browser zooms into on focus when their text is small, each
466
+ * with its CSS font size, plus the page scale and what the document's
467
+ * viewport meta says of width and zoom. Hidden, disabled and read-only fields take no
468
+ * keyboard and are left out; a nested contenteditable counts once, by its
469
+ * editing host. */
470
+ declare function readFocusZoomFields(root?: Element): FocusZoomRead;
458
471
  /** The visible labels of a `<select>`'s options, in order — what a
459
472
  * select by `{label}` matches against and `{index}` counts. Anything
460
473
  * but a `<select>` has none. */
@@ -491,6 +504,9 @@ declare function pageHasBackdropFilter(): boolean;
491
504
  declare function writeLocalStorageItem([key, value]: [string, string]): void;
492
505
  /** Read a localStorage item (`null` when absent). */
493
506
  declare function readLocalStorageItem(key: string): string | null;
507
+ /** Give the page a `beforeunload` listener that does nothing: it asks
508
+ * nothing and leaves the page's own listeners as they are. */
509
+ declare function addIdleBeforeUnload(): void;
494
510
  /** Make the document report itself hidden or visible to its scripts:
495
511
  * `document.hidden`, `visibilityState`, `hasFocus()`. With `announce` it
496
512
  * fires what a tab switch fires — `blur` then `visibilitychange` on hiding,
@@ -522,5 +538,21 @@ declare function inspectElementRaw(el: Element, args: {
522
538
  limit: number;
523
539
  };
524
540
  }): ElementHintRaw;
541
+ /** One phase of a one-finger touch at viewport point (x, y), dispatched
542
+ * from the page — for engines without a touch input to drive (WebKit,
543
+ * Firefox). Sends what a real finger does: a `pointerType: 'touch'`
544
+ * pointer event, then the touch event. Every phase goes to the element
545
+ * the finger went down on, as touch events (and pointer events under
546
+ * implicit touch capture) do. WebKit will not construct a `Touch` or a
547
+ * `TouchEvent` from script: there the touch event is a plain `Event`
548
+ * carrying `touches` / `targetTouches` / `changedTouches` built by
549
+ * `document.createTouchList` — real `Touch` objects, but the event is not
550
+ * `instanceof TouchEvent`. Returns false when no element is at a
551
+ * `start` point, or no touch is down for a `move` / `end`. */
552
+ declare function dispatchTouchPhase(arg: {
553
+ phase: "start" | "move" | "end";
554
+ x: number;
555
+ y: number;
556
+ }): boolean;
525
557
 
526
- export { type ElementHintRaw, type ImageState, ariaSnapshotAlgorithm, endsByItself, findElementAlgorithm, inspectElementRaw, isImageComplete, outlineAlgorithm, pageHasBackdropFilter, pasteValue, pickerOverlayAlgorithm, probeFieldsAlgorithm, readAnimations, readCheckedState, readClipboardText, readComputedStyle, readDisabledState, readForcedFillState, readImageState, readLocalStorageItem, readOptionLabels, semanticDomAlgorithm, serializeRuntimeDom, writeDisplayMode, writeDocumentHidden, writeLocalStorageItem };
558
+ export { type ElementHintRaw, type ImageState, addIdleBeforeUnload, ariaSnapshotAlgorithm, dispatchTouchPhase, endsByItself, findElementAlgorithm, inspectElementRaw, isImageComplete, outlineAlgorithm, pageHasBackdropFilter, pasteValue, pickerOverlayAlgorithm, probeFieldsAlgorithm, readAnimations, readCheckedState, readClipboardText, readComputedStyle, readDisabledState, readFocusZoomFields, readForcedFillState, readImageState, readLocalStorageItem, readOptionLabels, readViewportRatio, semanticDomAlgorithm, serializeRuntimeDom, writeDisplayMode, writeDocumentHidden, writeLocalStorageItem };
@@ -2758,6 +2758,11 @@ function optionKeys() {
2758
2758
  }
2759
2759
  __name(optionKeys, "optionKeys");
2760
2760
  var CLICK_OPTION_KEYS = optionKeys()(["timeout", "force", "position", "modifiers", "button", "clickCount"]);
2761
+ var DRAG_OPTION_KEYS = optionKeys()(["timeout", "force", "sourcePosition", "targetPosition"]);
2762
+ var DRAG_BY_OPTION_KEYS = optionKeys()(["timeout", "force", "sourcePosition"]);
2763
+ var TAP_OPTION_KEYS = optionKeys()(["timeout", "position"]);
2764
+ var LONG_PRESS_OPTION_KEYS = optionKeys()(["timeout", "position", "durationMs"]);
2765
+ var SWIPE_OPTION_KEYS = optionKeys()(["timeout", "sourcePosition", "durationMs"]);
2761
2766
  var FILL_OPTION_KEYS = optionKeys()(["timeout", "force"]);
2762
2767
  var PRESS_OPTION_KEYS = optionKeys()(["timeout", "delay"]);
2763
2768
  var CHECK_OPTION_KEYS = optionKeys()(["timeout", "force"]);
@@ -2851,6 +2856,19 @@ function readDisabledState(el) {
2851
2856
  return el.matches(":disabled") || el.getAttribute("aria-disabled") === "true";
2852
2857
  }
2853
2858
  __name(readDisabledState, "readDisabledState");
2859
+ function readViewportRatio(el) {
2860
+ globalThis.__name ??= (fn) => fn;
2861
+ return new Promise((resolve) => {
2862
+ const observer = new IntersectionObserver((entries) => {
2863
+ resolve(entries[0]?.intersectionRatio ?? 0);
2864
+ observer.disconnect();
2865
+ });
2866
+ observer.observe(el);
2867
+ requestAnimationFrame(() => {
2868
+ });
2869
+ });
2870
+ }
2871
+ __name(readViewportRatio, "readViewportRatio");
2854
2872
  function readForcedFillState(el, value) {
2855
2873
  globalThis.__name ??= (fn) => fn;
2856
2874
  if (el.tagName !== "INPUT" && el.tagName !== "TEXTAREA") return { state: null, holds: true };
@@ -2865,6 +2883,43 @@ function readComputedStyle(el, property) {
2865
2883
  return getComputedStyle(el).getPropertyValue(property).trim();
2866
2884
  }
2867
2885
  __name(readComputedStyle, "readComputedStyle");
2886
+ function readFocusZoomFields(root) {
2887
+ globalThis.__name ??= (fn) => fn;
2888
+ const NO_KEYBOARD = /* @__PURE__ */ new Set(["checkbox", "radio", "button", "submit", "reset", "file", "image", "range", "color", "hidden"]);
2889
+ const scale = window.visualViewport?.scale ?? 1;
2890
+ const takesText = /* @__PURE__ */ __name((el) => {
2891
+ if (el instanceof HTMLInputElement) return !NO_KEYBOARD.has(el.type) && !el.readOnly;
2892
+ if (el instanceof HTMLTextAreaElement) return !el.readOnly;
2893
+ if (el instanceof HTMLSelectElement) return true;
2894
+ return el instanceof HTMLElement && el.isContentEditable && !el.parentElement?.isContentEditable;
2895
+ }, "takesText");
2896
+ const shown = /* @__PURE__ */ __name((el) => el.getClientRects().length > 0 && getComputedStyle(el).visibility !== "hidden" && !el.matches(":disabled"), "shown");
2897
+ const field = /* @__PURE__ */ __name((el) => ({
2898
+ tag: el.tagName.toLowerCase(),
2899
+ type: el instanceof HTMLInputElement ? el.type : "",
2900
+ id: el.id,
2901
+ name: el.getAttribute("name") ?? "",
2902
+ fontPx: parseFloat(getComputedStyle(el).fontSize)
2903
+ }), "field");
2904
+ const selector = "input, textarea, select, [contenteditable]";
2905
+ const within = root ?? document.documentElement;
2906
+ const candidates = [...within.matches(selector) ? [within] : [], ...Array.from(within.querySelectorAll(selector))];
2907
+ const limits = /* @__PURE__ */ new Map();
2908
+ for (const pair of (document.querySelector('meta[name="viewport"]')?.getAttribute("content") ?? "").split(/[,;]/)) {
2909
+ const [key, value] = pair.split("=");
2910
+ if (key && value !== void 0) limits.set(key.trim().toLowerCase(), value.trim().toLowerCase());
2911
+ }
2912
+ const maximum = parseFloat(limits.get("maximum-scale") ?? "");
2913
+ const scalable = limits.get("user-scalable");
2914
+ return {
2915
+ fields: candidates.filter((el) => takesText(el) && shown(el)).map(field),
2916
+ scale,
2917
+ deviceWidth: limits.get("width") === "device-width",
2918
+ maximumScale: Number.isFinite(maximum) ? maximum : null,
2919
+ userScalable: scalable !== "no" && scalable !== "0"
2920
+ };
2921
+ }
2922
+ __name(readFocusZoomFields, "readFocusZoomFields");
2868
2923
  function readOptionLabels(el) {
2869
2924
  globalThis.__name ??= (fn) => fn;
2870
2925
  return el instanceof HTMLSelectElement ? Array.from(el.options, (o) => o.label) : [];
@@ -2927,6 +2982,12 @@ function readLocalStorageItem(key) {
2927
2982
  return localStorage.getItem(key);
2928
2983
  }
2929
2984
  __name(readLocalStorageItem, "readLocalStorageItem");
2985
+ function addIdleBeforeUnload() {
2986
+ globalThis.__name ??= (fn) => fn;
2987
+ addEventListener("beforeunload", () => {
2988
+ });
2989
+ }
2990
+ __name(addIdleBeforeUnload, "addIdleBeforeUnload");
2930
2991
  function writeDocumentHidden([hidden, announce]) {
2931
2992
  globalThis.__name ??= (fn) => fn;
2932
2993
  if (hidden) {
@@ -3163,8 +3224,64 @@ function inspectElementRaw(el, args) {
3163
3224
  __name(inferRole, "inferRole");
3164
3225
  }
3165
3226
  __name(inspectElementRaw, "inspectElementRaw");
3227
+ function dispatchTouchPhase(arg) {
3228
+ globalThis.__name ??= (fn) => fn;
3229
+ const state = globalThis;
3230
+ const POINTER_ID = 1;
3231
+ const TOUCH_ID = 1;
3232
+ if (arg.phase === "start") state.__unotestTouchTarget = document.elementFromPoint(arg.x, arg.y);
3233
+ const target = state.__unotestTouchTarget ?? null;
3234
+ if (target === null) return false;
3235
+ if (arg.phase === "end") state.__unotestTouchTarget = null;
3236
+ const pointerType = { start: "pointerdown", move: "pointermove", end: "pointerup" }[arg.phase];
3237
+ const touchType = { start: "touchstart", move: "touchmove", end: "touchend" }[arg.phase];
3238
+ const down = arg.phase !== "end";
3239
+ target.dispatchEvent(
3240
+ new PointerEvent(pointerType, {
3241
+ bubbles: true,
3242
+ cancelable: true,
3243
+ composed: true,
3244
+ pointerId: POINTER_ID,
3245
+ pointerType: "touch",
3246
+ isPrimary: true,
3247
+ clientX: arg.x,
3248
+ clientY: arg.y,
3249
+ buttons: down ? 1 : 0,
3250
+ pressure: down ? 0.5 : 0
3251
+ })
3252
+ );
3253
+ const init = { bubbles: true, cancelable: true, composed: true };
3254
+ const standard = /* @__PURE__ */ __name(() => {
3255
+ const touch = new Touch({ identifier: TOUCH_ID, target, clientX: arg.x, clientY: arg.y, pageX: arg.x + scrollX, pageY: arg.y + scrollY });
3256
+ const held = down ? [touch] : [];
3257
+ return new TouchEvent(touchType, { ...init, touches: held, targetTouches: held, changedTouches: [touch] });
3258
+ }, "standard");
3259
+ const legacy = /* @__PURE__ */ __name(() => {
3260
+ const doc = document;
3261
+ const touch = doc.createTouch(window, target, TOUCH_ID, arg.x + scrollX, arg.y + scrollY, arg.x, arg.y);
3262
+ const held = down ? doc.createTouchList(touch) : doc.createTouchList();
3263
+ const event2 = new Event(touchType, init);
3264
+ Object.defineProperties(event2, {
3265
+ touches: { value: held },
3266
+ targetTouches: { value: held },
3267
+ changedTouches: { value: doc.createTouchList(touch) }
3268
+ });
3269
+ return event2;
3270
+ }, "legacy");
3271
+ let event;
3272
+ try {
3273
+ event = standard();
3274
+ } catch {
3275
+ event = legacy();
3276
+ }
3277
+ target.dispatchEvent(event);
3278
+ return true;
3279
+ }
3280
+ __name(dispatchTouchPhase, "dispatchTouchPhase");
3166
3281
  export {
3282
+ addIdleBeforeUnload,
3167
3283
  ariaSnapshotAlgorithm,
3284
+ dispatchTouchPhase,
3168
3285
  endsByItself,
3169
3286
  findElementAlgorithm,
3170
3287
  inspectElementRaw,
@@ -3179,10 +3296,12 @@ export {
3179
3296
  readClipboardText,
3180
3297
  readComputedStyle,
3181
3298
  readDisabledState,
3299
+ readFocusZoomFields,
3182
3300
  readForcedFillState,
3183
3301
  readImageState,
3184
3302
  readLocalStorageItem,
3185
3303
  readOptionLabels,
3304
+ readViewportRatio,
3186
3305
  semanticDomAlgorithm,
3187
3306
  serializeRuntimeDom,
3188
3307
  writeDisplayMode,
@@ -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
  }
@@ -418,6 +455,30 @@ interface PageNetworkEntry {
418
455
  /** When the request was sent, epoch ms (as `nowMs()`). */
419
456
  at: number;
420
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
+ }
421
482
  /** A file a page of the context downloaded. The bytes stay with the
422
483
  * browser until `saveAs` copies them out. */
423
484
  interface DriverDownload {
@@ -545,6 +606,16 @@ interface DriverNetwork {
545
606
  * would then mean "nothing was watched", not "nothing left". */
546
607
  blocked(glob: string): ReadonlyArray<BlockedRequest>;
547
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
+ }
548
619
  interface DriverContext {
549
620
  /** Currently-open tabs/windows in this context. Index 0 = first opened. */
550
621
  pages(): ReadonlyArray<DriverPage>;
@@ -571,6 +642,10 @@ interface DriverContext {
571
642
  * shown; asking for the state it is in changes nothing. Absent index →
572
643
  * the active page. Throws `DriverError` on an index no open tab has. */
573
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>;
574
649
  /** Open a blank tab in this context and make it the active page (brought
575
650
  * to front, frame stack reset). It counts as handed: `waitForNewPage`
576
651
  * never returns it. Resolves with its index. */
@@ -579,8 +654,17 @@ interface DriverContext {
579
654
  * makes the page that was active before it active again (the one at the
580
655
  * index below when that one is gone); closing another tab keeps the
581
656
  * active page. Throws `DriverError` on an index no open tab has, and on
582
- * the only open tab — nothing would be left to drive. */
583
- 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>;
584
668
  /**
585
669
  * Subscribe to new-page events. Listener fires when a tab/window opens
586
670
  * in this context (`target="_blank"`, `window.open`, etc.). Returns an
@@ -749,8 +833,20 @@ interface DriverPage {
749
833
  selectOption(loc: LocatorValue, value: SelectOptionValue, opts?: SelectOptions): Promise<void>;
750
834
  hover(loc: LocatorValue, opts?: HoverOptions): Promise<void>;
751
835
  scrollIntoView(loc: LocatorValue): Promise<void>;
752
- /** Drag the source element onto the target. */
753
- 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>;
754
850
  /** Set the input element's selected files. Accepts a path, path[], or an in-memory file buffer. */
755
851
  uploadFile(loc: LocatorValue, files: string | ReadonlyArray<string> | {
756
852
  name: string;
@@ -779,6 +875,10 @@ interface DriverPage {
779
875
  * `value` is the submitted payload ("on" by default), never its state. */
780
876
  checkedState(loc: LocatorValue): Promise<boolean | null>;
781
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>;
782
882
  /** Where the matched element lies in the viewport, CSS pixels; `null`
783
883
  * when it is not rendered (display:none, detached). No scrolling. */
784
884
  boundingBox(loc: LocatorValue): Promise<BoundingBox | null>;
@@ -793,6 +893,13 @@ interface DriverPage {
793
893
  * `getComputedStyle(el).getPropertyValue(property)` gives it — custom
794
894
  * properties (`--accent`) included; "" for one that is not set. */
795
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>;
796
903
  /** Natural size of the matched `<img>` once it has settled (loaded or
797
904
  * failed), within the action timeout; `null` when it has no pixels —
798
905
  * broken, or no src. The one query that waits: "still loading" is not
@@ -825,6 +932,18 @@ interface DriverPage {
825
932
  }): Promise<{
826
933
  url: string;
827
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>;
828
947
  /** Change the media features this page reports, from now on: what
829
948
  * `matchMedia` and CSS `@media` see. A feature left out keeps its
830
949
  * current value. This page only — a tab opened later starts without it. */
@@ -893,6 +1012,29 @@ interface BoundingBox {
893
1012
  width: number;
894
1013
  height: number;
895
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
+ }
896
1038
  /** An image's natural size, in its own pixels. */
897
1039
  interface ImageSize {
898
1040
  width: number;
@@ -1046,4 +1188,4 @@ interface PageConsole {
1046
1188
  errors: readonly PageErrorEntry[];
1047
1189
  }
1048
1190
 
1049
- 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,12 @@ 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;
44
50
  /** Whether some `.secrets*` file names NAME, any environment's: an
45
51
  * undeclared credential is pointed at the secrets template (#469).
46
52
  * Absent → only the name's ending decides. */
@@ -60,6 +66,12 @@ interface ExternalVariableLookup {
60
66
  rejectBaseUrl(usage: string): {
61
67
  message: string;
62
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;
63
75
  };
64
76
  }
65
77
  interface LintOptions {