@unotest/web 0.55.0 → 0.56.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 (48) hide show
  1. package/.claude/skills/write-e2e-test/SKILL.md +30 -7
  2. package/.claude/skills/write-e2e-test-ground/SKILL.md +6 -5
  3. package/CHANGELOG.md +106 -3
  4. package/README.md +4 -3
  5. package/dist/config/schema.d.ts +25 -19
  6. package/dist/config/schema.js +1 -1
  7. package/dist/driver/index.d.ts +8 -2
  8. package/dist/driver/index.js +1 -1
  9. package/dist/dsl/index.d.ts +12 -82
  10. package/dist/dsl/index.js +1 -1
  11. package/dist/dsl/v8/scenario-worker.js +1 -1
  12. package/dist/dsl/web-dsl-language-service.d.ts +30 -3
  13. package/dist/dsl/web-dsl-language-service.js +1 -1
  14. package/dist/inspection/page-inject.d.ts +31 -7
  15. package/dist/inspection/page-inject.js +80 -19
  16. package/dist/{interfaces-CNvyInrY.d.ts → interfaces-BiGd3BdD.d.ts} +19 -4
  17. package/dist/{linter-BpaIstU3.d.ts → linter-DIAb0JOB.d.ts} +8 -0
  18. package/dist/mcp/server.js +1 -1
  19. package/dist/runner/cli.d.ts +1 -1
  20. package/dist/runner/cli.js +1 -1
  21. package/dist/runner/init/chrome-probe.js +1 -1
  22. package/dist/runner/init.js +1 -1
  23. package/dist/runner/install-chromium.js +1 -1
  24. package/dist/runner/prepare-fix.js +1 -1
  25. package/dist/runner/scaffold-workspace.js +1 -1
  26. package/dist/runner/serve-fixture.js +1 -1
  27. package/dist/runner/web-runner-adapter.js +1 -1
  28. package/dist/scenario-variables-B-ULUTHt.d.ts +88 -0
  29. package/examples/idioms/README.md +16 -0
  30. package/examples/idioms/animations-list.js +24 -0
  31. package/examples/idioms/api-call-timeout.js +14 -0
  32. package/examples/idioms/background-tab.js +24 -0
  33. package/examples/idioms/clipboard-paste.js +25 -0
  34. package/examples/idioms/computed-style.js +21 -0
  35. package/examples/idioms/image-size.js +20 -0
  36. package/examples/idioms/never-appears.js +20 -0
  37. package/examples/idioms/never-condition.js +24 -0
  38. package/examples/idioms/page-code-function.js +18 -0
  39. package/examples/idioms/select-by-label.js +22 -0
  40. package/examples/idioms/wait-enabled.js +21 -0
  41. package/examples/idioms/wait-for-animations.js +16 -0
  42. package/examples/idioms/wait-until-value.js +32 -0
  43. package/guides/agent-integration.md +26 -2
  44. package/guides/dsl-reference.md +508 -28
  45. package/llms.txt +24 -5
  46. package/package.json +9 -8
  47. package/types/unotest-dsl.d.ts +27 -20
  48. package/types/unotest-lib.d.ts +5 -3
@@ -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-CNvyInrY.js';
3
+ import { E as ElementHint, A as AnimationInfo } from '../interfaces-BiGd3BdD.js';
4
4
  import '../config/schema.js';
5
5
  import 'zod';
6
6
 
@@ -385,11 +385,18 @@ interface FindElementMatch {
385
385
  * full snapshot. Each entry is `{ role, name, ref }`; unnamed
386
386
  * ancestors are skipped. Capped at 4 entries — deeper structure
387
387
  * rarely informs disambiguation. */
388
- ancestors: Array<{
389
- role: string;
390
- name: string;
391
- ref?: string;
392
- }>;
388
+ ancestors: FindElementAncestor[];
389
+ }
390
+ interface FindElementAncestor {
391
+ role: string;
392
+ /** Accessible name (W3C accname) — what `find_element({name})` matches. */
393
+ name: string;
394
+ /** The label the outline (`get_page_snapshot`) prints for this region:
395
+ * aria-label → aria-labelledby → first heading inside. Absent when
396
+ * there is none. Differs from `name` for a container titled by its
397
+ * own heading (`<form><h2>Employees</h2>…`): no accname, label set. */
398
+ label?: string;
399
+ ref?: string;
393
400
  }
394
401
  interface FindElementResult {
395
402
  /** All matches; first `nth` (default 20) returned. */
@@ -413,6 +420,15 @@ declare function findElementAlgorithm(h: InjectedDomHelpers, args: {
413
420
  limit: number;
414
421
  }): FindElementResult;
415
422
 
423
+ /** What the page reports about one match beyond its hint. */
424
+ interface ProbeFields {
425
+ name: string;
426
+ placeholder?: string;
427
+ value?: string;
428
+ valueHidden?: true;
429
+ }
430
+ declare function probeFieldsAlgorithm(h: InjectedDomHelpers): (el: Element) => ProbeFields;
431
+
416
432
  /** Raw element hint read off a live DOM element: `ElementHint` minus the
417
433
  * wire-only `ref` the caller adds when mapping. Type-only import — erased
418
434
  * at runtime, so the serialized functions stay self-contained. */
@@ -428,6 +444,14 @@ declare function readCheckedState(el: Element): boolean | null;
428
444
  /** Disabled state — native `:disabled` (covers `<fieldset disabled>`
429
445
  * inheritance) or `aria-disabled` on a custom widget. */
430
446
  declare function readDisabledState(el: Element): boolean;
447
+ /** After `fill(…, {force: true})`: whether an `<input>` / `<textarea>`
448
+ * holds `value`, and the state that kept it from taking it — readonly,
449
+ * disabled or hidden — or null for an editable field or another element.
450
+ * Compared here, so the value never leaves the page (#537). */
451
+ declare function readForcedFillState(el: Element, value: string): {
452
+ state: "readonly" | "disabled" | "hidden" | null;
453
+ holds: boolean;
454
+ };
431
455
  /** Computed value of one CSS property — custom properties included, which
432
456
  * `getPropertyValue` returns with the whitespace after their colon. */
433
457
  declare function readComputedStyle(el: Element, property: string): string;
@@ -499,4 +523,4 @@ declare function inspectElementRaw(el: Element, args: {
499
523
  };
500
524
  }): ElementHintRaw;
501
525
 
502
- export { type ElementHintRaw, type ImageState, ariaSnapshotAlgorithm, endsByItself, findElementAlgorithm, inspectElementRaw, isImageComplete, outlineAlgorithm, pageHasBackdropFilter, pasteValue, pickerOverlayAlgorithm, readAnimations, readCheckedState, readClipboardText, readComputedStyle, readDisabledState, readImageState, readLocalStorageItem, readOptionLabels, semanticDomAlgorithm, serializeRuntimeDom, writeDisplayMode, writeDocumentHidden, writeLocalStorageItem };
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 };
@@ -1666,7 +1666,7 @@ function outlineAlgorithm(h, assignRefs) {
1666
1666
  clickAffordance,
1667
1667
  testIdOf,
1668
1668
  formFieldRole,
1669
- nameFromLabelledby,
1669
+ landmarkLabel,
1670
1670
  svgAccname,
1671
1671
  makeAccname,
1672
1672
  ariaStateFlags,
@@ -1774,23 +1774,6 @@ function outlineAlgorithm(h, assignRefs) {
1774
1774
  return null;
1775
1775
  }
1776
1776
  __name(findLandmark, "findLandmark");
1777
- function landmarkLabel(landmark) {
1778
- const aria = trim(landmark.getAttribute("aria-label"));
1779
- if (aria) return cap(aria);
1780
- const fromLabelledby = nameFromLabelledby(
1781
- landmark,
1782
- /* @__PURE__ */ new Set(),
1783
- (ref) => trim(textContentVisible(ref))
1784
- );
1785
- if (fromLabelledby) return fromLabelledby;
1786
- const heading = landmark.querySelector("h1, h2, h3, h4, h5, h6");
1787
- if (heading) {
1788
- const txt = trim(textContentVisible(heading));
1789
- if (txt) return cap(txt);
1790
- }
1791
- return "";
1792
- }
1793
- __name(landmarkLabel, "landmarkLabel");
1794
1777
  function tooltipLabel(el) {
1795
1778
  for (const a of Array.from(el.attributes)) {
1796
1779
  if (!a.name.startsWith("data-") || a.name.startsWith("data-unotest")) continue;
@@ -2319,6 +2302,12 @@ import { pickerOverlayAlgorithm as pickerOverlayInjectable } from "@unotest/web/
2319
2302
  // src/util/errors.ts
2320
2303
  import { UnotestError } from "@unotest/core";
2321
2304
 
2305
+ // src/dsl/external-variable-messages.ts
2306
+ import { ENV_FILE, SECRETS_FILE } from "@unotest/protocol";
2307
+
2308
+ // src/config/env-layers.ts
2309
+ import { activeEnvName, envLayerFilesFor, secretsLayerFilesFor } from "@unotest/protocol";
2310
+
2322
2311
  // src/inspection/picker-overlay.ts
2323
2312
  function pickerOverlayAlgorithm(op) {
2324
2313
  const REF_ATTR = "data-unotest-ref";
@@ -2733,7 +2722,10 @@ function findElementAlgorithm(h, args) {
2733
2722
  if (role) {
2734
2723
  const name = h.accname(p);
2735
2724
  if (role !== "generic" || name) {
2736
- chain.push({ role, name, ref: h.ensureRef(p, "n") });
2725
+ const entry = { role, name, ref: h.ensureRef(p, "n") };
2726
+ const label = h.landmarkLabel(p);
2727
+ if (label) entry.label = label;
2728
+ chain.push(entry);
2737
2729
  }
2738
2730
  }
2739
2731
  p = h.parentOrHost(p);
@@ -2757,6 +2749,64 @@ function findElementAlgorithm(h, args) {
2757
2749
  }
2758
2750
  __name(findElementAlgorithm, "findElementAlgorithm");
2759
2751
 
2752
+ // src/inspection/probe-locator.ts
2753
+ import { composeInjectedScript as composeInjectedScript4 } from "@unotest/grounder-client/dom-walker";
2754
+
2755
+ // src/driver/options.ts
2756
+ function optionKeys() {
2757
+ return (keys) => keys;
2758
+ }
2759
+ __name(optionKeys, "optionKeys");
2760
+ var CLICK_OPTION_KEYS = optionKeys()(["timeout", "force", "position", "modifiers", "button", "clickCount"]);
2761
+ var FILL_OPTION_KEYS = optionKeys()(["timeout", "force"]);
2762
+ var PRESS_OPTION_KEYS = optionKeys()(["timeout", "delay"]);
2763
+ var CHECK_OPTION_KEYS = optionKeys()(["timeout", "force"]);
2764
+ var SELECT_OPTION_KEYS = optionKeys()(["timeout", "force"]);
2765
+ var HOVER_OPTION_KEYS = optionKeys()(["timeout", "force", "position"]);
2766
+ var WAIT_FOR_OPTION_KEYS = optionKeys()(["timeout", "state"]);
2767
+ var WAIT_FOR_TEXT_OPTION_KEYS = optionKeys()(["timeout", "state", "first", "exact"]);
2768
+ var NAVIGATION_OPTION_KEYS = optionKeys()(["timeout", "waitUntil"]);
2769
+
2770
+ // src/dsl/locator-value.ts
2771
+ var FILTER_OPTION_KEYS = optionKeys()([
2772
+ "hasText",
2773
+ "hasNotText",
2774
+ "has",
2775
+ "hasNot"
2776
+ ]);
2777
+ var ROLE_OPTION_KEYS = optionKeys()([
2778
+ "name",
2779
+ "exact",
2780
+ "checked",
2781
+ "disabled",
2782
+ "expanded",
2783
+ "includeHidden",
2784
+ "level",
2785
+ "pressed",
2786
+ "selected"
2787
+ ]);
2788
+
2789
+ // src/inspection/probe-locator.ts
2790
+ import { probeFieldsAlgorithm as probeFieldsAlgorithmInjectable } from "@unotest/web/internal/page-inject";
2791
+ function probeFieldsAlgorithm(h) {
2792
+ const nonText = ["checkbox", "radio", "button", "submit", "reset", "image", "file", "hidden"];
2793
+ return (el) => {
2794
+ const out = { name: h.accname(el) };
2795
+ const tag = el.tagName.toLowerCase();
2796
+ if (tag === "input" || tag === "textarea") {
2797
+ const placeholder = h.trim(el.placeholder);
2798
+ if (placeholder) out.placeholder = placeholder;
2799
+ }
2800
+ const type = tag === "input" ? el.type.toLowerCase() : "";
2801
+ if (type === "password") out.valueHidden = true;
2802
+ else if (tag === "textarea" || tag === "select" || tag === "input" && !nonText.includes(type)) {
2803
+ out.value = el.value;
2804
+ }
2805
+ return out;
2806
+ };
2807
+ }
2808
+ __name(probeFieldsAlgorithm, "probeFieldsAlgorithm");
2809
+
2760
2810
  // src/inspection/page-dom.ts
2761
2811
  function readClipboardText() {
2762
2812
  return navigator.clipboard.readText();
@@ -2801,6 +2851,15 @@ function readDisabledState(el) {
2801
2851
  return el.matches(":disabled") || el.getAttribute("aria-disabled") === "true";
2802
2852
  }
2803
2853
  __name(readDisabledState, "readDisabledState");
2854
+ function readForcedFillState(el, value) {
2855
+ globalThis.__name ??= (fn) => fn;
2856
+ if (el.tagName !== "INPUT" && el.tagName !== "TEXTAREA") return { state: null, holds: true };
2857
+ const field = el;
2858
+ const hidden = field.tagName === "INPUT" && field.type === "hidden" || field.getClientRects().length === 0 || getComputedStyle(field).visibility === "hidden";
2859
+ const state = field.matches(":disabled") ? "disabled" : field.readOnly ? "readonly" : hidden ? "hidden" : null;
2860
+ return { state, holds: field.value === value };
2861
+ }
2862
+ __name(readForcedFillState, "readForcedFillState");
2804
2863
  function readComputedStyle(el, property) {
2805
2864
  globalThis.__name ??= (fn) => fn;
2806
2865
  return getComputedStyle(el).getPropertyValue(property).trim();
@@ -3114,11 +3173,13 @@ export {
3114
3173
  pageHasBackdropFilter,
3115
3174
  pasteValue,
3116
3175
  pickerOverlayAlgorithm,
3176
+ probeFieldsAlgorithm,
3117
3177
  readAnimations,
3118
3178
  readCheckedState,
3119
3179
  readClipboardText,
3120
3180
  readComputedStyle,
3121
3181
  readDisabledState,
3182
+ readForcedFillState,
3122
3183
  readImageState,
3123
3184
  readLocalStorageItem,
3124
3185
  readOptionLabels,
@@ -270,6 +270,9 @@ interface ScreenshotOptions {
270
270
  animations?: "disabled" | "allow";
271
271
  /** `"hide"` — the text caret is not drawn (it blinks). Default `"initial"`. */
272
272
  caret?: "hide" | "initial";
273
+ /** How long the capture may take. Default: the context's
274
+ * `defaultTimeoutMs`. */
275
+ timeoutMs?: number;
273
276
  }
274
277
  /** Encoding options for an element capture — `ScreenshotOptions` minus
275
278
  * the page-geometry fields (`fullPage`, `clip`) that have no meaning for a
@@ -520,6 +523,11 @@ interface BlockedRequest {
520
523
  * where several match one request, the one mocked last answers it, and
521
524
  * mocking a mask again replaces its answer and makes it the latest.
522
525
  * Mocks last as long as the context. */
526
+ interface RequestWaitOptions {
527
+ timeoutMs: number;
528
+ /** Upper-case HTTP method; absent → a request of any method. */
529
+ method?: string;
530
+ }
523
531
  interface DriverNetwork {
524
532
  mock(glob: string, response: RouteResponse): Promise<void>;
525
533
  /** Take off the mock at `glob`, or every mock when it is omitted.
@@ -528,10 +536,10 @@ interface DriverNetwork {
528
536
  /** The next request matching `glob` not yet returned by an earlier
529
537
  * wait. A mocked mask keeps its requests from the moment it was
530
538
  * 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>;
539
+ * sees requests from the call on. With `method` (upper case) only a
540
+ * request of that method is taken; one of another method stays for the
541
+ * next wait. Throws TimeoutError after `timeoutMs`. */
542
+ waitForRequest(glob: string, opts: RequestWaitOptions): Promise<CapturedRequest>;
535
543
  /** The requests stopped by the recording abort at `glob`. Throws when
536
544
  * `glob` was never mocked with a recording abort: an empty answer
537
545
  * would then mean "nothing was watched", not "nothing left". */
@@ -658,7 +666,11 @@ interface DriverContext {
658
666
  /** Typed storage shortcuts (D-6). */
659
667
  setLocalStorage(key: string, value: string): Promise<void>;
660
668
  getLocalStorage(key: string): Promise<string | null>;
669
+ /** Writes the cookie into the context's jar; throws CookieRejectedError
670
+ * when the browser does not keep it (a cookie set already expired is a
671
+ * deletion and passes). */
661
672
  setCookie(name: string, value: string, opts?: CookieOptions): Promise<void>;
673
+ /** The jar's value — every domain and path, httpOnly too. */
662
674
  getCookie(name: string): Promise<string | null>;
663
675
  /**
664
676
  * Persist current storage state to disk (D-23 opt-in caching). Used by
@@ -841,6 +853,9 @@ interface DriverPage {
841
853
  /** `evaluate` on the matched element: a function body is called with
842
854
  * the element and `arg`. */
843
855
  evaluateOnLocator<T = unknown>(loc: LocatorValue, js: string, arg?: unknown): Promise<T>;
856
+ /** `document.cookie` of the scope (the innermost entered frame, else the
857
+ * page): the cookies its script is given — no httpOnly ones. */
858
+ documentCookie(): Promise<string>;
844
859
  screenshot(opts?: ScreenshotOptions): Promise<Buffer>;
845
860
  /** Capture ONE element (first match, scrolled into view) instead of the
846
861
  * viewport — the evidence shot of a card / row / dialog. Same encoding
@@ -41,6 +41,10 @@ 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
+ /** Whether some `.secrets*` file names NAME, any environment's: an
45
+ * undeclared credential is pointed at the secrets template (#469).
46
+ * Absent → only the name's ending decides. */
47
+ inSecretsFile?(name: string): boolean;
44
48
  /** Host policy of the environment this lookup describes (#199) — it
45
49
  * answers why NAME must not be used as a HOST in `usage`, or undefined
46
50
  * when the use is fine. Absent on a lookup with no project behind it,
@@ -83,6 +87,10 @@ interface LintOptions {
83
87
  * sets none of its own. Absent → the rule only knows `setTestTimeout`
84
88
  * literals. */
85
89
  testBudget?: TestBudgetHint;
90
+ /** The `@unotest/web` the suite installs (`installedSuiteVersion`), when
91
+ * it differs from the one linting: a function newer than it is unknown
92
+ * to the suite's own lint and run. Absent → the rule is off. */
93
+ suiteVersion?: string;
86
94
  }
87
95
  /** A test's time budget and the setting it comes from. */
88
96
  interface TestBudgetHint {