@unotest/web 0.54.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 +160 -3
  4. package/README.md +24 -6
  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 +29 -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-BU-PQbt4.d.ts → interfaces-BiGd3BdD.d.ts} +29 -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 +43 -5
  44. package/guides/dsl-reference.md +589 -34
  45. package/llms.txt +26 -6
  46. package/package.json +9 -8
  47. package/types/unotest-dsl.d.ts +36 -22
  48. package/types/unotest-lib.d.ts +5 -3
@@ -0,0 +1,24 @@
1
+ // Idiom: what is moving on this element?
2
+ // Habit: evaluateOnLocator(el, '(el) => el.getAnimations().map(…)').
3
+ // Typed step: animations(locator) lists each animation: name, kind,
4
+ // playState, infinite. hasAnimation(locator) is the yes/no.
5
+
6
+ function motion_page_url() {
7
+ return 'data:text/html,<style>' +
8
+ '@keyframes spin { to { transform: rotate(360deg) } }' +
9
+ '[data-testid=spinner] { animation: spin 1s linear infinite }' +
10
+ '</style><div data-testid="spinner">loading</div><div data-testid="still">still</div>';
11
+ }
12
+
13
+ function test_idiom_animations_list() {
14
+ step("Open a page with a spinner", () => {
15
+ goto(motion_page_url());
16
+ waitFor(getByTestId('still'));
17
+ });
18
+
19
+ step("The spinner lists one infinite animation; the still block none", () => {
20
+ let list = animations(getByTestId('spinner'));
21
+ assertTrue(list.length == 1 && list[0].name == 'spin' && list[0].infinite === true, json(list));
22
+ assertEqual(animations(getByTestId('still')), []);
23
+ });
24
+ }
@@ -0,0 +1,14 @@
1
+ // Idiom: give one HTTP call a time limit.
2
+ // Habit: apiCall(method, path, body, headers, options, {timeout: 120000}) —
3
+ // a sixth argument 0.49.2 dropped without a word and 0.50.0 refuses.
4
+ // Typed option: {timeoutMs} in the options slot, the budget for the whole
5
+ // call; past it the step fails as a timeout naming the call.
6
+ // Needs sandbox.apiBaseUrl in unotest.config: the endpoint here is
7
+ // GET /delay?ms=N of the dogfood fixture API.
8
+
9
+ function test_idiom_api_call_timeout() {
10
+ step("An endpoint that answers inside the budget", () => {
11
+ let res = apiCall('GET', '/delay?ms=200', null, null, {timeoutMs: 5000});
12
+ assertEqual(res.status, 200);
13
+ });
14
+ }
@@ -0,0 +1,24 @@
1
+ // Idiom: work in one tab while another is in front.
2
+ // Habit: window.open through evaluate, then guessing the tab index.
3
+ // Typed steps: newPage(url) opens a tab and returns its index;
4
+ // setPage(i, {activate: false}) moves the steps without bringing the tab
5
+ // forward; bringToFront(i) shows a tab without moving the steps.
6
+
7
+ function test_idiom_background_tab() {
8
+ step("The site in tab 0, a second page in a new tab", () => {
9
+ goto('https://playground.unotest.com/scenarios/clicks');
10
+ let second = newPage('https://playground.unotest.com/scenarios/drag-drop');
11
+ assertEqual(second, 1);
12
+ assertUrl('/scenarios/drag-drop');
13
+ });
14
+
15
+ step("Steps back on tab 0, tab 1 stays in front", () => {
16
+ setPage(0, {activate: false});
17
+ assertUrl('/scenarios/clicks');
18
+ });
19
+
20
+ step("Show tab 0 again; the steps do not move", () => {
21
+ bringToFront(0);
22
+ assertUrl('/scenarios/clicks');
23
+ });
24
+ }
@@ -0,0 +1,25 @@
1
+ // Idiom: paste into a field.
2
+ // Habit: evaluate navigator.clipboard.writeText(...), then press('Meta+V'):
3
+ // needs clipboard permissions and differs per OS.
4
+ // Typed step: clipboardPaste(locator, text) puts the text in through the
5
+ // input path the page listens to. A rich editor that needs a real
6
+ // ClipboardEvent is out of its reach.
7
+
8
+ function paste_page_url() {
9
+ return 'data:text/html,<label>Coupon <input></label><output></output>' +
10
+ '<script>document.querySelector("input").addEventListener("input", (e) => {' +
11
+ ' document.querySelector("output").textContent = "got " + e.target.value; });</script>';
12
+ }
13
+
14
+ function test_idiom_clipboard_paste() {
15
+ step("Open a page that echoes its field", () => {
16
+ goto(paste_page_url());
17
+ waitFor(getByLabel('Coupon'));
18
+ });
19
+
20
+ step("Paste a code; the page sees the input event", () => {
21
+ clipboardPaste(getByLabel('Coupon'), 'SPRING10');
22
+ assertValue(getByLabel('Coupon'), 'SPRING10');
23
+ waitForText('got SPRING10');
24
+ });
25
+ }
@@ -0,0 +1,21 @@
1
+ // Idiom: read a CSS value.
2
+ // Habit: evaluate("getComputedStyle(document.querySelector('.badge')).color").
3
+ // Typed step: computedStyle(locator, property) reads the resolved value
4
+ // off the element the locator finds, no page code.
5
+
6
+ function styled_page_url() {
7
+ return 'data:text/html,<style>.badge { color: rgb(200, 0, 0); font-weight: 700 }</style>' +
8
+ '<span class="badge">Overdue</span>';
9
+ }
10
+
11
+ function test_idiom_computed_style() {
12
+ step("Open a page with a styled badge", () => {
13
+ goto(styled_page_url());
14
+ waitForText('Overdue');
15
+ });
16
+
17
+ step("Read the badge's colour and weight", () => {
18
+ assertEqual(computedStyle(getByText('Overdue'), 'color'), 'rgb(200, 0, 0)');
19
+ assertEqual(computedStyle(getByText('Overdue'), 'font-weight'), '700');
20
+ });
21
+ }
@@ -0,0 +1,20 @@
1
+ // Idiom: is the image loaded, and how big is it?
2
+ // Habit: evaluateOnLocator(img, '(img) => img.complete && img.naturalWidth').
3
+ // Typed step: getImageSize(locator) gives the natural {width, height}, or
4
+ // null for an image that did not load.
5
+
6
+ function image_page_url() {
7
+ return 'data:text/html,<img alt="Logo" width="90" height="60" src="data:image/png;base64,' +
8
+ 'iVBORw0KGgoAAAANSUhEUgAAAAMAAAACCAIAAAASFvFNAAAAEElEQVR4nGP4z8AAQQxwFgBB0gX7h/C5SAAAAABJRU5ErkJggg==">';
9
+ }
10
+
11
+ function test_idiom_image_size() {
12
+ step("Open a page with a 3x2 image drawn at 90x60", () => {
13
+ goto(image_page_url());
14
+ waitFor(getByAltText('Logo'));
15
+ });
16
+
17
+ step("The natural size, not the drawn one", () => {
18
+ assertEqual(getImageSize(getByAltText('Logo')), {width: 3, height: 2});
19
+ });
20
+ }
@@ -0,0 +1,20 @@
1
+ // Idiom: something must NOT appear.
2
+ // Habit: pause(3000), then assertHidden(banner). A banner that came and
3
+ // went inside the pause passes unseen.
4
+ // Typed step: assertNeverAppears(locator, {withinMs}) watches the whole
5
+ // window and fails the moment the element shows.
6
+
7
+ function quiet_page_url() {
8
+ return 'data:text/html,<p>Saved.</p><div data-testid="error" hidden>Sync failed</div>';
9
+ }
10
+
11
+ function test_idiom_never_appears() {
12
+ step("Open a page that stays quiet", () => {
13
+ goto(quiet_page_url());
14
+ waitForText('Saved.');
15
+ });
16
+
17
+ step("No error banner during the whole window", () => {
18
+ assertNeverAppears(getByText('Sync failed'), {withinMs: 2000});
19
+ });
20
+ }
@@ -0,0 +1,24 @@
1
+ // Idiom: a condition must never hold.
2
+ // Habit: pause(2000), then one assert on a counter. A value that crossed
3
+ // the line and came back inside the pause is missed.
4
+ // Typed step: assertNever(() => condition, {withinMs}) polls the whole
5
+ // window and names the moment and the value it saw.
6
+
7
+ function counter_page_url() {
8
+ return 'data:text/html,<div data-testid="count">0</div>' +
9
+ '<script>let n = 0; setInterval(() => { n = (n + 1) %25 5;' +
10
+ ' document.querySelector("[data-testid=count]").textContent = String(n); }, 100);</script>';
11
+ }
12
+
13
+ function test_idiom_never_condition() {
14
+ step("Open a counter that wraps at 5", () => {
15
+ goto(counter_page_url());
16
+ // The counter really ticks: a frozen one would pass the window below
17
+ // for nothing.
18
+ waitUntil(() => textContent(getByTestId('count')) == '4', {timeoutMs: 3000, intervalMs: 20, label: 'count reaches 4'});
19
+ });
20
+
21
+ step("The counter never reaches 5", () => {
22
+ assertNever(() => parseJson(textContent(getByTestId('count'))) >= 5, {withinMs: 2000, intervalMs: 50, label: 'count at 5 or more'});
23
+ });
24
+ }
@@ -0,0 +1,18 @@
1
+ // Idiom: run code in the page with a value from the test.
2
+ // Habit: evaluate("document.title = '" + name + "'"): the value becomes
3
+ // page code, and the validator refuses it (validator:evaluate-interpolation).
4
+ // Typed form: a function literal plus arguments, evaluate(fn, value). The
5
+ // function sees only its parameters. Prefer a typed getter when one exists.
6
+
7
+ function test_idiom_page_code_function() {
8
+ step("Open a blank page", () => {
9
+ goto('data:text/html,<title>start</title><p>ready</p>');
10
+ waitForText('ready');
11
+ });
12
+
13
+ step("Pass the value as an argument, not inside the code", () => {
14
+ let name = 'Quarterly report';
15
+ evaluate((title) => { document.title = title; }, name); // lint-ok: the idiom is page code done right
16
+ assertEqual(getTitle(), 'Quarterly report');
17
+ });
18
+ }
@@ -0,0 +1,22 @@
1
+ // Idiom: pick an option by the text the user sees.
2
+ // Habit: evaluate a loop over select.options to find the value of a text,
3
+ // then selectOption(select, thatValue).
4
+ // Typed step: selectOption(locator, {label}) picks by the visible text.
5
+
6
+ function select_page_url() {
7
+ return 'data:text/html,<label>Country <select>' +
8
+ '<option value="de">Germany</option><option value="fr">France</option>' +
9
+ '</select></label>';
10
+ }
11
+
12
+ function test_idiom_select_by_label() {
13
+ step("Open a page with a country select", () => {
14
+ goto(select_page_url());
15
+ waitFor(getByLabel('Country'));
16
+ });
17
+
18
+ step("Pick France by its label", () => {
19
+ selectOption(getByLabel('Country'), {label: 'France'});
20
+ assertValue(getByLabel('Country'), 'fr');
21
+ });
22
+ }
@@ -0,0 +1,21 @@
1
+ // Idiom: wait until a button can be pressed.
2
+ // Habit: a for loop of pause(500) and isEnabled(button).
3
+ // Typed step: waitFor(locator, {state: 'enabled'}); aria-disabled and a
4
+ // disabled fieldset count, not only the disabled attribute.
5
+
6
+ function slow_form_url() {
7
+ return 'data:text/html,<button disabled>Send</button>' +
8
+ '<script>setTimeout(() => { document.querySelector("button").disabled = false; }, 800);</script>';
9
+ }
10
+
11
+ function test_idiom_wait_enabled() {
12
+ step("Open a form whose button unlocks a moment later", () => {
13
+ goto(slow_form_url());
14
+ assertTrue(isDisabled(getByRole('button', {name: 'Send'})), 'Send starts disabled');
15
+ });
16
+
17
+ step("Wait for the state, then press", () => {
18
+ waitFor(getByRole('button', {name: 'Send'}), {state: 'enabled'});
19
+ click(getByRole('button', {name: 'Send'}));
20
+ });
21
+ }
@@ -0,0 +1,16 @@
1
+ // Idiom: wait for an animation to end.
2
+ // Habit: pause(600) "until the dialog has faded in", then read or shoot it.
3
+ // Typed step: waitForAnimations(locator) returns the moment nothing in the
4
+ // element is moving; a static element returns at once.
5
+
6
+ function test_idiom_wait_for_animations() {
7
+ step("Open a dialog that fades in", () => {
8
+ goto('https://playground.unotest.com/scenarios/big-table?rows=20&groups=0&markers=0&shadow=none&hidden=0&seed=42');
9
+ click(getByRole('row', {name: /^Row R-00002:/}).getByRole('button', {name: 'Edit'}));
10
+ });
11
+
12
+ step("Wait for the fade, not for a guessed number of milliseconds", () => {
13
+ waitForAnimations(getByRole('dialog'));
14
+ assertEqual(computedStyle(getByRole('dialog'), 'opacity'), '1');
15
+ });
16
+ }
@@ -0,0 +1,32 @@
1
+ // Idiom: poll until a value is good enough, and keep it.
2
+ // Habit: for (i = 0; i < 20; i++) { v = read(); if (ok(v)) break; pause(250); }
3
+ // Typed step: waitUntil(() => …) retries a falsy value and gives the truthy
4
+ // one back. A variable set inside the body keeps its value between tries.
5
+
6
+ function ticking_page_url() {
7
+ return 'data:text/html,<div data-testid="count">0</div>' +
8
+ '<script>let n = 0; setInterval(() => { n++;' +
9
+ ' document.querySelector("[data-testid=count]").textContent = String(n); }, 100);</script>';
10
+ }
11
+
12
+ function test_idiom_wait_until_value() {
13
+ step("Open a counter that ticks every 100 ms", () => {
14
+ goto(ticking_page_url());
15
+ waitFor(getByTestId('count'));
16
+ });
17
+
18
+ step("Wait for 5 or more; keep the value and the number of tries", () => {
19
+ let tries = 0;
20
+ let reached = waitUntil(() => {
21
+ tries = tries + 1;
22
+ let n = parseJson(textContent(getByTestId('count')));
23
+ if (n < 5) {
24
+ return false;
25
+ }
26
+ return n;
27
+ }, {timeoutMs: 5000, intervalMs: 100, label: 'count at 5'});
28
+ assertTrue(reached >= 5, json(reached));
29
+ assertTrue(tries >= 1, json(tries));
30
+ note('tries', tries);
31
+ });
32
+ }
@@ -20,12 +20,19 @@ connected.
20
20
  "mcpServers": {
21
21
  "unotest-web": {
22
22
  "command": "npx",
23
- "args": ["@unotest/web", "mcp"]
23
+ "args": ["-y", "@unotest/web@<version>", "mcp"]
24
24
  }
25
25
  }
26
26
  }
27
27
  ```
28
28
 
29
+ Pin the version your suite installs (`unotest/package.json`). `init`
30
+ writes the entry pinned to its own version, and run again it pins an
31
+ entry that has none. Unpinned, `npx` starts whatever copy its cache
32
+ holds: when that is not the suite's version, the server says so in its
33
+ instructions and in its first tool reply, and `run_test`, `lint` and
34
+ explore run on the server's version, not the suite's.
35
+
29
36
  Claude Code prompts for approval on first start. After approve, the
30
37
  50 `mcp__unotest-web__*` tools appear in the agent's tool surface.
31
38
 
@@ -83,6 +90,19 @@ One to three functions, best first; none and a `hint` when no function
83
90
  holds the words. The same index answers `npx @unotest/web api <word>`
84
91
  and ships as `llms.txt` in the package.
85
92
 
93
+ A task that is a CLI command's, not a scenario's, is weighed against the
94
+ commands `npx @unotest/web --help` lists too, and answered with the
95
+ command. `functions` stays, empty:
96
+
97
+ ```json
98
+ dsl_lookup({"task": "set up a cron schedule for the suite"})
99
+ → {"command": {"name": "schedules", "synopsis": "schedules",
100
+ "summary": "Print the project's schedules: …",
101
+ "help": "npx @unotest/web schedules --help"},
102
+ "functions": [],
103
+ "hint": "`schedules` is a CLI command, not a scenario function: …", …}
104
+ ```
105
+
86
106
  ### Core lifecycle and observers (9)
87
107
 
88
108
  Open and close the browser, and read what the agent "sees" — a semantic
@@ -124,7 +144,11 @@ output need no retraining.
124
144
  Returns matching element refs without dumping a full snapshot — the
125
145
  escape hatch when `get_page_snapshot` / `get_aria_snapshot` exceed
126
146
  the MCP token cap (table-heavy fleet UIs with 100+ rows). Refs are
127
- shared with outline / aria-snapshot.
147
+ shared with outline / aria-snapshot. Each match lists its named
148
+ `ancestors` as `{role, name, label?, ref}`: `name` is the accessible
149
+ name, `label` the region label `get_page_snapshot` prints — a form
150
+ titled by its own `<h2>Employees</h2>` has `name: ""` and
151
+ `label: "Employees"`.
128
152
 
129
153
  `UNOTEST_SNAPSHOT=0` unregisters the three snapshot tools
130
154
  (`get_page_snapshot`, `get_frame_snapshot`, `get_aria_snapshot`) — for
@@ -316,6 +340,15 @@ this is the list.
316
340
  - `box_queue` — who is waiting, who is running
317
341
  - `box_screenshot` — one frame the run captured, as an image
318
342
 
343
+ ### Writing to a box (1)
344
+
345
+ - `box_repo_add { url? }` — map the repository (default: the git
346
+ origin) to the project on a box rented before 0.54.0, so `bundle push`
347
+ stops warning "maps to no project on this box". Uses the project's
348
+ push token, like `bundle push` — not the read token above. Answers
349
+ `mapped` / `already-mapped`; `box-too-old` means Update the box in the
350
+ dashboard first.
351
+
319
352
  ### Cloud account (9)
320
353
 
321
354
  The account that rents boxes, as tools: the same operations as the
@@ -325,9 +358,14 @@ same whether an agent or a person asked. They act with the key
325
358
  `UNOTEST_CLOUD_TOKEN`).
326
359
 
327
360
  - `cloud_boxes_list` — every box on the account, with its state
328
- - `cloud_box_status` — one box: state, address, paid-until, projects,
329
- Picker
330
- - `cloud_box_create` — rent a box (`name`, `envs`, `size?`, `picker?`)
361
+ - `cloud_box_status` — one box: state, address, paid-until, when it
362
+ ends, projects, Picker
363
+ - `cloud_box_create` — rent a box (`name`, `envs`, `size?`, `picker?`,
364
+ `ttl?`: `8h`, `2d`, up to `30d`, or `none`; without it the box lives
365
+ 24 hours and is then deleted by itself)
366
+ - `cloud_box_extend` — move a box's end later (`name`, `ttl`; `none`
367
+ takes the lifetime away). Nothing is charged at once; a key that may
368
+ not spend asks a person, as for a create
331
369
  - `cloud_box_destroy` — delete a box and everything on it
332
370
  - `cloud_box_access` — a fresh push + read token pair, written into
333
371
  `unotest/.env` and `unotest/.secrets` the way `box access` does. No