@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.
- package/.claude/skills/write-e2e-test/SKILL.md +44 -7
- package/.claude/skills/write-e2e-test-ground/SKILL.md +20 -5
- package/CHANGELOG.md +250 -3
- package/README.md +7 -6
- package/bin/unotest-web.js +13 -0
- package/dist/config/schema.d.ts +29 -23
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +16 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +74 -94
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/v8/scenario-worker.js +1 -1
- package/dist/dsl/web-dsl-language-service.d.ts +30 -3
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +63 -7
- package/dist/inspection/page-inject.js +199 -19
- package/dist/{interfaces-CNvyInrY.d.ts → interfaces-DDp6Chwx.d.ts} +167 -10
- package/dist/{linter-BpaIstU3.d.ts → linter-q4UNIeGI.d.ts} +20 -0
- package/dist/mcp/server.js +1 -1
- package/dist/runner/cli.d.ts +1 -1
- package/dist/runner/cli.js +1 -1
- package/dist/runner/init/chrome-probe.js +1 -1
- package/dist/runner/init.js +1 -1
- package/dist/runner/install-chromium.js +1 -1
- package/dist/runner/prepare-fix.js +1 -1
- package/dist/runner/scaffold-workspace.js +1 -1
- package/dist/runner/serve-fixture.js +1 -1
- package/dist/runner/web-runner-adapter.js +1 -1
- package/dist/scenario-variables-CGexnWK4.d.ts +106 -0
- package/examples/idioms/README.md +16 -0
- package/examples/idioms/animations-list.js +24 -0
- package/examples/idioms/api-call-timeout.js +14 -0
- package/examples/idioms/background-tab.js +24 -0
- package/examples/idioms/clipboard-paste.js +25 -0
- package/examples/idioms/computed-style.js +21 -0
- package/examples/idioms/image-size.js +20 -0
- package/examples/idioms/never-appears.js +20 -0
- package/examples/idioms/never-condition.js +24 -0
- package/examples/idioms/page-code-function.js +18 -0
- package/examples/idioms/select-by-label.js +22 -0
- package/examples/idioms/wait-enabled.js +24 -0
- package/examples/idioms/wait-for-animations.js +16 -0
- package/examples/idioms/wait-until-value.js +32 -0
- package/guides/agent-integration.md +28 -4
- package/guides/dsl-reference.md +896 -45
- package/llms.txt +38 -9
- package/package.json +9 -8
- package/types/unotest-dsl.d.ts +107 -30
- package/types/unotest-lib.d.ts +5 -3
|
@@ -197,6 +197,27 @@ For each page state you traverse:
|
|
|
197
197
|
CHANGED the address also carries `url` — that's where you are now,
|
|
198
198
|
no `get_url` / `get_active_context` round-trip needed.
|
|
199
199
|
|
|
200
|
+
**A ref belongs to its snapshot, not to the URL.** A `goto` (or
|
|
201
|
+
`reload`, or a re-render) inside the batch loads a new document, and
|
|
202
|
+
the refs you read before it are stale there. Put a `snapshot` step
|
|
203
|
+
between the navigation and the first step that acts by ref — a login
|
|
204
|
+
is then still one call:
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
explore_steps { explorationId, steps: [
|
|
208
|
+
{action: "goto", url: "<login URL>", section: "Sign in", description: "Open sign-in"},
|
|
209
|
+
{action: "snapshot", section: "Sign in", description: "Fresh refs"},
|
|
210
|
+
{action: "fill", locator: {kind:"locator", steps:[{kind:"ref", ref:"e4"}]},
|
|
211
|
+
value: "LOGIN", section: "Sign in", description: "Fill the login field"},
|
|
212
|
+
…
|
|
213
|
+
]}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Its reply carries `outline` — the `get_page_snapshot` text, refs live
|
|
217
|
+
from there on. The same page gives the same element the same ref, so a
|
|
218
|
+
ref read from an earlier snapshot of that page works after the step.
|
|
219
|
+
The snapshot step is never recorded and never in the saved test.
|
|
220
|
+
|
|
200
221
|
**Record checks as assert steps** — `assert_text {locator, text,
|
|
201
222
|
options?: {exact}}`, `assert_visible {locator}`, `assert_hidden
|
|
202
223
|
{locator}`, `assert_value {locator, value}`, `assert_count
|
|
@@ -213,7 +234,8 @@ For each page state you traverse:
|
|
|
213
234
|
reports `autoRun.status: "skipped"` + reason and the manual Phases
|
|
214
235
|
4–5 apply.
|
|
215
236
|
|
|
216
|
-
|
|
237
|
+
`section` and `description` are **always required**; in
|
|
238
|
+
ad-hoc mode (no `explorationId`) they only label the debug log.
|
|
217
239
|
Adjacent same-section entries are wrapped in one `step("...", () => { … })`
|
|
218
240
|
block in the generated test, so the `section` must read
|
|
219
241
|
like a line in a human test PLAN — the user-facing GOAL of the block
|
|
@@ -240,7 +262,8 @@ For each page state you traverse:
|
|
|
240
262
|
|
|
241
263
|
**Ad-hoc probes** — to try a click or fill without polluting the
|
|
242
264
|
recording, **omit `explorationId`**. Refs forwarded as-is to the
|
|
243
|
-
driver, no resolve/verify, nothing written.
|
|
265
|
+
driver, no resolve/verify, nothing written. `section` and
|
|
266
|
+
`description` are still required — here they only label the debug log.
|
|
244
267
|
|
|
245
268
|
### Phase 4 — stop, generate, save
|
|
246
269
|
|
|
@@ -517,6 +540,20 @@ function overview_header_width() {
|
|
|
517
540
|
}
|
|
518
541
|
```
|
|
519
542
|
|
|
543
|
+
**In view after an action** — `assertVisible` passes below the fold too.
|
|
544
|
+
`assertInViewport` checks the visible area itself (scroll containers that
|
|
545
|
+
clip the element count) and waits like the other asserts; it scrolls
|
|
546
|
+
nothing. In `explore_step` it is `assert_in_viewport`:
|
|
547
|
+
|
|
548
|
+
```js
|
|
549
|
+
press(getByRole('main'), 'ArrowDown');
|
|
550
|
+
assertInViewport(getByRole('heading', {name: 'Pricing'}));
|
|
551
|
+
assertInViewport(getByRole('status'), {ratio: 1}); // wholly in view
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
`{ratio}` (0..1) is the least share of the element in view; without it any
|
|
555
|
+
part will do.
|
|
556
|
+
|
|
520
557
|
`return` is legal in either helper kind, and NOT in a `test_*` entry —
|
|
521
558
|
there it would mean the scenario silently ended halfway. A `flow_*` that
|
|
522
559
|
returns a value gets a `lint:flow-returns-value` warning: fine when the flow
|
|
@@ -611,9 +648,8 @@ the old browser context, then `run_test` again.
|
|
|
611
648
|
| `exit_frame` | | |
|
|
612
649
|
| `screenshot` | | `name`, `fullPage`, `locator`, `outline`, `evidenceOnly` |
|
|
613
650
|
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
no recording.
|
|
651
|
+
`description` + `section` are always required. Ad-hoc (no
|
|
652
|
+
`explorationId`): nothing is recorded, and they only label the debug log.
|
|
617
653
|
|
|
618
654
|
`screenshot` is the **evidence** step: it files a PNG under the session
|
|
619
655
|
(`.unotest/explorations/<explorationId>/screenshots/<NNN>-<name>.png`,
|
|
@@ -628,8 +664,9 @@ do not write throwaway scenarios just to get a picture.
|
|
|
628
664
|
|
|
629
665
|
## Failure modes you will hit
|
|
630
666
|
|
|
631
|
-
- **`StaleRefError`** — ref no longer in the DOM
|
|
632
|
-
and use the new ref
|
|
667
|
+
- **`StaleRefError`** — ref no longer in the DOM: the page changed since
|
|
668
|
+
the snapshot it came from. Re-`get_page_snapshot` and use the new ref;
|
|
669
|
+
inside a batch, a `snapshot` step after the navigation does the same.
|
|
633
670
|
- **`RefResolveError`** — element has no stable identifier (testId /
|
|
634
671
|
role+name / aria-label / placeholder / alt / title / text / href /
|
|
635
672
|
stable id / name attribute). Best fix: ask the app team to add
|
|
@@ -344,7 +344,8 @@ batch):
|
|
|
344
344
|
reports `autoRun.status: "skipped"` + reason and the manual Phases
|
|
345
345
|
4–5 apply.
|
|
346
346
|
|
|
347
|
-
|
|
347
|
+
`section` and `description` are **always required**; in
|
|
348
|
+
ad-hoc mode (no `explorationId`) they only label the debug log.
|
|
348
349
|
Adjacent same-section entries are wrapped in one `step("...", () => { … })`
|
|
349
350
|
block in the generated test, so the `section` must read
|
|
350
351
|
like a line in a human test PLAN — the user-facing GOAL of the block
|
|
@@ -371,7 +372,8 @@ batch):
|
|
|
371
372
|
|
|
372
373
|
**Ad-hoc probes** — to try a click or fill without polluting the
|
|
373
374
|
recording, **omit `explorationId`**. Refs forwarded as-is to the
|
|
374
|
-
driver, no resolve/verify, nothing written.
|
|
375
|
+
driver, no resolve/verify, nothing written. `section` and
|
|
376
|
+
`description` are still required — here they only label the debug log.
|
|
375
377
|
|
|
376
378
|
### Phase 4 — stop, generate, save
|
|
377
379
|
|
|
@@ -648,6 +650,20 @@ function overview_header_width() {
|
|
|
648
650
|
}
|
|
649
651
|
```
|
|
650
652
|
|
|
653
|
+
**In view after an action** — `assertVisible` passes below the fold too.
|
|
654
|
+
`assertInViewport` checks the visible area itself (scroll containers that
|
|
655
|
+
clip the element count) and waits like the other asserts; it scrolls
|
|
656
|
+
nothing. In `explore_step` it is `assert_in_viewport`:
|
|
657
|
+
|
|
658
|
+
```js
|
|
659
|
+
press(getByRole('main'), 'ArrowDown');
|
|
660
|
+
assertInViewport(getByRole('heading', {name: 'Pricing'}));
|
|
661
|
+
assertInViewport(getByRole('status'), {ratio: 1}); // wholly in view
|
|
662
|
+
```
|
|
663
|
+
|
|
664
|
+
`{ratio}` (0..1) is the least share of the element in view; without it any
|
|
665
|
+
part will do.
|
|
666
|
+
|
|
651
667
|
`return` is legal in either helper kind, and NOT in a `test_*` entry —
|
|
652
668
|
there it would mean the scenario silently ended halfway. A `flow_*` that
|
|
653
669
|
returns a value gets a `lint:flow-returns-value` warning: fine when the flow
|
|
@@ -742,9 +758,8 @@ the old browser context, then `run_test` again.
|
|
|
742
758
|
| `exit_frame` | | |
|
|
743
759
|
| `screenshot` | | `name`, `fullPage`, `locator`, `outline`, `evidenceOnly` |
|
|
744
760
|
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
no recording.
|
|
761
|
+
`description` + `section` are always required. Ad-hoc (no
|
|
762
|
+
`explorationId`): nothing is recorded, and they only label the debug log.
|
|
748
763
|
|
|
749
764
|
`screenshot` is the **evidence** step: it files a PNG under the session
|
|
750
765
|
(`.unotest/explorations/<explorationId>/screenshots/<NNN>-<name>.png`,
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,252 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.57.0] - 2026-11-15
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- a12065c: New: `assertInViewport(locator, { ratio?, timeoutMs? })` checks that an element is inside the visible area of the page, as Playwright's `toBeInViewport` does. Scroll containers that clip the element count. `ratio` (0..1) sets the least share of the element that must be in view; without it any part will do. It waits like the other assertions and scrolls nothing, so a block that arrow keys or a click should bring into view can be checked: `assertVisible` passes on an element scrolled out of view, `assertInViewport` does not.
|
|
8
|
+
|
|
9
|
+
New: `explore_step` takes the same check as `assert_in_viewport { locator, options?: { ratio, timeout } }`, recorded as `assertInViewport` in the saved test.
|
|
10
|
+
|
|
11
|
+
replaces: evaluate with getBoundingClientRect against window.innerHeight
|
|
12
|
+
|
|
13
|
+
- 574b4d7: New: `assertNoFocusZoom(scope?, { minFontPx?, timeoutMs? })` catches the iOS Safari zoom on focus: Safari zooms the page into a text field whose text is under 16px and leaves it zoomed. No browser engine Playwright drives does that zoom, so the check reads its cause: every visible, enabled, writable input, textarea, select and contenteditable in the scope (the whole page when absent), its font size times the page scale, against `minFontPx` (default 16). A viewport meta with `maximum-scale` at 1 or below forbids the zoom, and the check passes. Run it on an iPhone device preset. The options may take the place of the scope: `assertNoFocusZoom({ minFontPx: 14 })`.
|
|
14
|
+
|
|
15
|
+
At a page scale other than 1 the failure names the CSS size, the scale and what the reader sees (`input#search 16px × page scale 0.40 = 6.4px`). A page shown zoomed out without `<meta name="viewport" content="width=device-width">` gets that cause named, with the fix.
|
|
16
|
+
|
|
17
|
+
The on-screen keyboard is not emulated: no engine shrinks the visual viewport the way the iOS keyboard does, so a composer fixed to the bottom and hidden under the keyboard is not caught.
|
|
18
|
+
|
|
19
|
+
replaces: evaluate reading getComputedStyle(input).fontSize for each field
|
|
20
|
+
|
|
21
|
+
- e327d43: New: a config listing several `browsers` is played in each of them. `e2e` and `collection` run the suite once per engine, in order — each a run of its own, with its own queue slot, `prepare` and `webServer` boot, and the engine in its run id — then print a line per engine; the exit code is red when any engine is. `--json` prints one document for all engines: every test names its `browser`, and `runs` lists each engine's `runId` and `exitCode`. `UNOTEST_BROWSER` narrows a run to one engine. A run the viewer or `run_test` starts and `--debug` play the first engine and say so in the log. `browsers: ["chromium", "webkit"]` then `npx @unotest/web e2e checkout`, replaces: a separate run per engine with `UNOTEST_BROWSER` — before, only the first entry of `browsers` ran, without a word.
|
|
22
|
+
- 1667c88: New: `closePage({ beforeUnload: 'leave' | 'stay' })` closes a tab the way a person does. The page runs `beforeunload`, and its "Leave site?" prompt gets the answer given, whatever the run's `dialogPolicy`: `'leave'` closes the tab, `'stay'` keeps it and the steps stay on it. With an index the options go second: `closePage(1, { beforeUnload: 'stay' })`. `closePage` now returns `{ asked, closed }`; without the option the tab closes with no prompt, as before (`{ asked: false, closed: true }`). With the option the only open tab closes too: a blank tab is left in its place, and the scenario goes on there; a plain `closePage()` on the only tab is still refused. Browsers ask only after real user input on the page, such as a click; a `fill` alone does not count in Firefox.
|
|
23
|
+
|
|
24
|
+
replaces: a synthetic `new Event('beforeunload')` dispatched from the scenario, and a person checking the real prompt by hand
|
|
25
|
+
|
|
26
|
+
Example:
|
|
27
|
+
|
|
28
|
+
```js
|
|
29
|
+
click(getByLabel("Display name"));
|
|
30
|
+
fill(getByLabel("Display name"), "Draft");
|
|
31
|
+
assertEqual(closePage({ beforeUnload: "stay" }), {
|
|
32
|
+
asked: true,
|
|
33
|
+
closed: false,
|
|
34
|
+
});
|
|
35
|
+
assertEqual(closePage({ beforeUnload: "leave" }), {
|
|
36
|
+
asked: true,
|
|
37
|
+
closed: true,
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- 0ff171c: New: request headers for a browser context. MCP `new_context` and `explore_start` take `headers` — `{ "Authorization": "{{API_TOKEN}}" }` — and every page of the context sends them with every request: documents, fetch and XHR, every tab. A value written whole as `{{NAME}}` is the variable or secret of the session's environment, so the token stays out of the tool call; an unknown name is refused, and the reply names the headers, never their values. In a scenario, `newContext({ headers: { Authorization: API_TOKEN } })` opens a client that sends them; the run's own context does not. A value that is not a string is refused.
|
|
42
|
+
|
|
43
|
+
replaces: a route that adds the header to each request, or a token in the URL
|
|
44
|
+
|
|
45
|
+
- 2039477: New: `dragBy(locator, dx, dy, { sourcePosition?, force?, timeoutMs? })` takes hold of an element and moves the pointer by an offset in pixels — a resize handle, a slider, a selection box on a canvas.
|
|
46
|
+
|
|
47
|
+
New: `dragAndDrop(from, to, { sourcePosition?, targetPosition? })` — `{x, y}` points inside each element, as in Playwright's `dragTo`. `from` and `to` may be the same element, to sweep a selection inside one frame; the validator no longer refuses these keys.
|
|
48
|
+
|
|
49
|
+
New: `explore_step` drags too: `drag_and_drop { locator, target }` and `drag_by { locator, dx, dy }`, recorded as `dragAndDrop` / `dragBy` in the saved test.
|
|
50
|
+
|
|
51
|
+
replaces: pointer events dispatched through `evaluate` in the page
|
|
52
|
+
|
|
53
|
+
- 97e1a9d: New: `e2e` and `collection` take `--json` — when the run is over, one JSON document on stdout with every test: file, test name, status (`pass` / `fail` / `error` / `skip` / `aborted`), duration, the failing file and line, and the absolute paths of the screenshots it took (`screenshot()`, per-step captures, the page at the failure). A collection adds `notRun`, the listed scenarios that never started and why. Every other line goes to stderr; the exit code is unchanged. `npx @unotest/web collection smoke --json > result.json`, replaces: reading the result off the console.
|
|
54
|
+
- 894d47f: New: a run says where each of its variables comes from. `run:started` in the run journal carries an `env` table — every name of the active env files and secrets with its source: the shared `.env`, the environment's `.env.<name>`, a secrets file, or the shell (what a box injects). Names and sources only, never a value. The viewer shows it as the run's folded **Environment** table. `npx @unotest/web e2e checkout --env dev`, replaces: guessing from the header line which file a value came from.
|
|
55
|
+
|
|
56
|
+
New: `lint:env-from-base` (warning). With `--env <name>` active, a bare read of a name whose value still comes from the shared base `unotest/.env` is reported with the file and the overlay that does not set it. `env: { shared: [...] }` silences it and now takes any name, not only hosts; a host left to the base file is still the `lint:env-host-from-base` error. Without `--env` the rule sleeps. `npx @unotest/web lint --env dev`, replaces: a value silently inherited from the shared `.env`.
|
|
57
|
+
|
|
58
|
+
- 6949fc2: New: an agent driving the page over MCP reads its console. `explore_step {action: "console_entries"}` (alone or inside `explore_steps`, never recorded) answers what the active page wrote to its console and threw uncaught — the record a scenario reads with `consoleEntries()` — with a `cursor`; pass it back as `since` for only the new lines. A cursor of another tab reads that page from the start and says `cursorReset: true`. `options.level` filters by level, `options.limit` (default 50, up to 200) keeps the newest and counts the rest in `dropped`.
|
|
59
|
+
|
|
60
|
+
replaces: an `evaluate` that wraps `console.error` to read the console back
|
|
61
|
+
|
|
62
|
+
- ed22fb9: New: linter rule `lint:external-variable-empty` (warning) flags a bare read of a declared variable whose value is empty where the run takes it from — since 0.56.0 an empty value means "not set on this environment", and the run stops at that read after the browser and every earlier step. `lint` and the check before a run now name each such read with its file, line and column and the file that leaves the value empty, so the places to change after the 0.56.0 upgrade no longer have to be found by hand. With `--env <name>`, `lint` reads that environment's files; without it, a name is reported only when no `unotest/.env*` / `.secrets*` file gives it a value. The check before a run also sees the shell. A name empty in a `.secrets` file is told to get its value there. Example: `x = env("QA_LOGIN", "")` where empty is fine. replaces: a bare `QA_LOGIN` with `QA_LOGIN=` in `unotest/.env`, which `lint` now reports as `` `QA_LOGIN` is empty in unotest/.env — the run stops here. `` and which stops the run at that line
|
|
63
|
+
- 2d5094c: New: linter rule `lint:get-attribute-null` (warning) flags a `getAttribute(…)` read compared with `null` or `undefined` — by `==`, `!=`, `===`, `!==` or `assertEqual`, in place or through a variable of the same function. `getAttribute` reads `""` when the attribute is missing, never `null`, so such a check cannot see the attribute missing; the message points to `hasAttribute(loc, name)`. `dsl_lookup` says the same on the `getAttribute` line and finds `hasAttribute` for "check that an attribute is missing". `getAttribute` still returns `""`. Example: `assertTrue(!hasAttribute(locator('body'), 'data-played'))`. replaces: `assertEqual(getAttribute(locator('body'), 'data-played'), null)`, which fails with `expected null, got ""`
|
|
64
|
+
- b95cbdc: New: `lint` checks a scenario against your project's own types. A JSDoc `@import` of a type from your repository — the answer of an `apiCall` as your protocol declares it, or the type a zod schema infers with `z.infer` — now resolves through packages in `node_modules` and the `baseUrl` / `paths` aliases of the nearest `tsconfig.json`, so a field renamed in the protocol is caught before the run. replaces: finding the renamed field only when the run fails.
|
|
65
|
+
|
|
66
|
+
Example:
|
|
67
|
+
|
|
68
|
+
```js
|
|
69
|
+
/** @import { Answer } from '../../../src/protocol/answer' */
|
|
70
|
+
function test_order() {
|
|
71
|
+
step("order", () => {
|
|
72
|
+
/** @type {Answer} */
|
|
73
|
+
const body = apiCall("GET", "/api/order/1").body;
|
|
74
|
+
note("id", body.orderIdd); // error [ts:2551] Property 'orderIdd' does not exist on type 'Answer'
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Changed: `unotest-web lint` exits 1 on two type findings that were warnings: a member a type of your project does not have (`ts:2339`, `ts:2551`), and an `@import` whose module does not resolve (`ts:2307`, `ts:2792`). A CI step that runs `lint` turns red there instead of passing. Scenarios without JSDoc type annotations are not affected; an `@import` that resolves to `any` (a package without types) is a warning, `types:untyped-import`.
|
|
80
|
+
|
|
81
|
+
- 85dc429: New: `mcpCallStart(server, tool, args)` and `mcpCallResult(call, {timeoutMs, allowError})` — an MCP tool call in two steps. Start the call, act in between (for example, click Done on the card an `ask_human` tool shows), then take the answer. The result and the failures are the same as `mcpCall`. `timeoutMs` counts from `mcpCallResult`, and running out of time cancels the call. A call never taken is a warning in the report when the server stops, not a failure. `mcpCall` is unchanged. `const call = mcpCallStart(srv, 'ask_human', {question: 'Ship?'}); click(getByRole('button', {name: 'Done'})); mcpCallResult(call)`, replaces: a background MCP client of your own writing the answer to a file for `waitForFile`.
|
|
82
|
+
- 69d7f74: New: MCP `new_context` and `explore_start` take `reducedMotion` (`"reduce"` / `"no-preference"`) and `colorScheme` (`"light"` / `"dark"` / `"no-preference"`). Every page of the context reports them from its first document — every tab and popup, not one tab as `emulateMedia` does — so an agent's screenshot does not catch an animation mid-way, and a whole window can be captured in a dark theme: `new_context { colorScheme: "dark", reducedMotion: "reduce" }`. An unknown value is refused with the accepted ones.
|
|
83
|
+
|
|
84
|
+
replaces: emulateMedia run on each tab after it opens
|
|
85
|
+
|
|
86
|
+
- acd0f1a: New: `newContext({ viewport: { width, height, deviceScaleFactor } })` opens a browser context on a window of its own, as MCP `new_context` does — a narrow screen at twice the density next to the run's own context. The fields are those of `viewport` in the config, all optional; the window asked for replaces the config's whole, so a scale not given is 1 and the config's `device` is not applied under it. It works next to `headers`, `profile` and `cdpEndpoint`. A stray field or a value that is not a positive number is refused, naming the fields, before the run and at the call.
|
|
87
|
+
|
|
88
|
+
replaces: `setViewport()` after `newContext()`, which cannot change the scale
|
|
89
|
+
|
|
90
|
+
- bb98794: Changed: resolve diagnostics carry an optional `cascade` field. With `reason: "scored"` it names the arm that answered (`reranker`, `picker` or `none`), the reranker's top score, its lead over the runner-up, and how many candidates the picker was shown; with `reason: "reranker-rejected"` the reranker refused the request and the picker decided on the full list.
|
|
91
|
+
- 0dc7eb7: New: `// @each <source>` above a `test_*` runs it once per case, each case a run with its own verdict. The source is a top-level `const` array of objects in the file (`// @each SLOTS`) or a JSONL file, one object a line (`// @each "unotest/e2e/data/questions.jsonl"`, relative to the project root). Each case comes in as the test's first argument and is named after its simple fields, `test_question[slot=1]`, or after its `name` field when it has one. The viewer's tree, collection reports, box runs and `--json` show every case under that name. `--test question` runs every case, and `--test 'question[slot=2]'` runs one. A source that lists no case is refused before the run, by `e2e`, `run_test` and `lint`. That covers a missing or empty table, a missing file, a line that is not JSON, and duplicate case names. `lint` also warns about a field the test reads that no case has.
|
|
92
|
+
|
|
93
|
+
replaces: a loop of step.soft(…, {tag}) over a table or readJsonLine inside one test, all cases under one verdict
|
|
94
|
+
|
|
95
|
+
- 40e39dd: New: touch steps for phone contexts — `tap(locator, { position?, timeoutMs? })`, `longPress(locator, { durationMs?, position?, timeoutMs? })` (holds 800 ms by default) and `swipe(locator, dx, dy, { durationMs?, sourcePosition?, timeoutMs? })`, with the offset read as in `dragBy`. They need a context with a touch screen (`profile: 'ios'` or a touch `device` preset); in a desktop context each fails before touching anything and names that config. Chromium drives its own touch input; WebKit and Firefox get touch events, with `pointerType: 'touch'` pointer events, dispatched from the page — there `event instanceof TouchEvent` is false in WebKit.
|
|
96
|
+
|
|
97
|
+
replaces: `PointerEvent` / `TouchEvent` with `pointerType: 'touch'` built by hand in `evaluate`
|
|
98
|
+
|
|
99
|
+
- 98d295b: New: `waitForWebSocketFrame(glob, {direction?, match?, timeoutMs?})` and `webSocketFrames(glob, {direction?})` read the frames of the page's WebSockets. The browser records them from the socket's first frame, so a `hello` the page sends on open is there for a wait after `goto()` — no script in the page needed. A wait takes the frame it gives, and the next call gives the next one; `match` is a JSON key filter, as in `mcpWaitNotification`. A frame is `{url, direction, text, json, at}`, a binary one has `size` instead of `text`. A timeout names the sockets and the last frames.
|
|
100
|
+
|
|
101
|
+
replaces: overriding the `MessageEvent.prototype.data` getter through `evaluate` after `goto()`, which lost the frames sent on load
|
|
102
|
+
|
|
103
|
+
### Patch Changes
|
|
104
|
+
|
|
105
|
+
- 1962bd2: Fixed: `api` and `dsl_lookup` find a function by the words it is usually searched with: `hasCookie` by "cookie exists", "document.cookie" or "cookie is gone after logout", `waitForRequest` by "tell GET from POST", `mockRoute` by "ordering masks", `pause` by "shell sleep".
|
|
106
|
+
- 39a9b44: Fixed: `api` and `dsl_lookup` find this release's new functions by the habit they replace: `assertInViewport` by "getBoundingClientRect" or "visible area", `assertNoFocusZoom` by "getComputedStyle fontSize", `dragBy` by "pointer events" or "dispatchEvent", `tap`, `longPress` and `swipe` by "TouchEvent" or "PointerEvent", `waitForWebSocketFrame` and `webSocketFrames` by "MessageEvent", `newContext` by "authorization header" or "token in the URL", `closePage` by "leave site", `mcpCallStart` by "ask_human". `dsl_lookup` also finds `assertInViewport` by the task "check that an element is inside the visible area". `dsl_lookup` "evaluate with getBoundingClientRect against window.innerHeight" again names `boundingBox` and `evaluate`, now beside `assertInViewport`, instead of nothing.
|
|
107
|
+
- 0d8fd1f: Fixed: a run whose starting MCP server is gone no longer stays for the whole pause timeout after a second client attached to it and then went away. Attaching inside the window used to keep the run for good, so once that client closed too the run was left with nobody to drive it, holding its queue slot and browser. Now the run stays only while an attached server is alive; when it is gone or calls `detach_debug_session`, the run waits the same window (`UNOTEST_OWNER_GONE_WINDOW_MS`) for another client and then stops. A run started from the viewer is not affected. The run is also told when the attached server leaves it another way — attaching to a different run, `take_wheel` on another run, `new_context` or `explore_start` — so that window starts at once instead of after the pause timeout.
|
|
108
|
+
- 6ab3da7: Changed: `bundle push --run` no longer pins the box environment it runs in. The environment serves the pushed bundle and keeps following its default branch: the next bundle pushed to that branch moves it on, and the viewer no longer shows it as pinned by the push token. Only a pick in the viewer holds an environment. A run ordered into an environment somebody picked by hand replaces that pick and lets go of it.
|
|
109
|
+
- 082ba2b: Fixed: `boxd environment add` no longer tells the operator that a push refused in the last 10 s is refused again — an added environment is served at once when a push names it, and the message now says so.
|
|
110
|
+
- b0430d9: Fixed: an environment added on the box with `environment add` is served as soon as a push names it, even when a push was refused for that name a few seconds earlier. Before, the retry the CLI hint suggests was refused again for up to 10 seconds.
|
|
111
|
+
- 7ab95db: Fixed: an environment taken back with `boxd environment remove` stops being served at once, not on the box's next sweep. Right after the remove, `bundle rm` of the bundle only that environment ran is no longer refused as "in use", and `bundle push` no longer names the removed environment among those missing a value, and a schedule that comes due no longer runs it.
|
|
112
|
+
- f62f7f9: Fixed: a run ordered with `bundle push --run` in an environment that `boxd environment remove` took back before the run reached the queue no longer starts in the removed environment. It ends as not run, and `--follow` prints the reason: the environment was removed.
|
|
113
|
+
- 1e91053: Fixed: after `environment remove` on the box, the removed environment's viewer stops within seconds, as the command says. Before, it kept running for up to five minutes when nothing reached the daemon after the remove. An `environment add` is picked up just as quickly, with no push needed.
|
|
114
|
+
- ef2bbd7: Fixed: a box refusing an oversized upload now delivers its answer (413, or 400 for a declared length over the limit) to a client that is still sending, instead of the connection being reset before the answer arrives.
|
|
115
|
+
- e6f98ff: Fixed: an environment removed from the box config and added back after its selected bundle was deleted no longer serves nothing. The box lets go of the vanished bundle, logs who had selected it and when, and the environment follows its branch again.
|
|
116
|
+
- 52861a7: Fixed: a box being stopped now waits for the CI runs it has already accepted to leave its run queue, so a restart no longer leaves a half-withdrawn ticket behind.
|
|
117
|
+
- 9f432d6: Fixed: on macOS, headless runs on system Chrome no longer pile up 1.3 GB copies of the Chrome app bundle in the temporary folder. A Chrome killed while it starts leaves such a copy behind; unotest-web now removes leftovers when it starts a headless system-Chrome run, and never touches the copy of a Chrome that is still running, your own included. A long-running Chrome, such as your own, no longer keeps the leftovers of other Chrome runs from being removed. The MCP server also closes its browser when it crashes instead of leaving it to be killed. `init` now points out that bundled Chromium is the lighter choice for headless runs.
|
|
118
|
+
- 6ddc3bf: Fixed: a collection that is refused before its first scenario — a judge that cannot answer, a viewport that does not fit the device, a browser profile asked to serve several workers, an app that will not start, a failed `prepare` — now leaves its run with the reason. `bundle push --run --follow` prints that reason as a failed line of the collection and then ends, instead of a silent "finished". The collection's `collection-run:finished` event carries the reason in a new optional `error` field.
|
|
119
|
+
- c299aa9: Fixed: `env push` with values larger than the box accepts (1 MB per request) now says so. The box answers 413 `payload-too-large` instead of a generic `malformed`, and the CLI prints how large the request was and the box's limit, with what to do — instead of advising to upgrade a box that was already current. Against an older box that still answers `malformed`, the CLI recognises an oversized batch by its own size and gives the same advice.
|
|
120
|
+
- fce8fa3: Fixed: `explore_step` `click` dropped `options.position` without a word: the click landed in the centre of the element and the step answered success. `click` now takes the options of the DSL `click()` — `position`, `modifiers`, `button`, `clickCount`, `force`, `timeout` — and the recorded step keeps them; `double_click`, `hover`, `press` and `select_option` take theirs (`position`, `force`, `delay`) the same way. An options key an action does not read is now refused with the keys it does read, for every action, instead of being dropped.
|
|
121
|
+
- 80ab4a2: Fixed: `bundle push --run --follow` prints a run's `finished` line after the lines of its last scenario, not before them. The follower now reads the run's remaining lines until the box says the log is complete, waiting a couple of seconds at most, so the CI log no longer shows steps after the run seemed to end; the verdict is printed either way.
|
|
122
|
+
- 5de8df2: Fixed: the `wait-enabled` idiom example starts its unlock timer on a click, so its first check no longer races the timer on a slow machine.
|
|
123
|
+
- 2ba187e: Fixed: with `--json`, `collection`, `e2e` and `bundle push` send what the project's `prepare` and `generate` commands print to stderr, so stdout carries the result document alone and pipes straight into `jq`. Without `--json` their output stays on stdout.
|
|
124
|
+
- 4c13f0f: Changed: the MCP server's instructions now say that a DSL function with no `explore_step` action (`evaluate`, `boundingBox`, `setCookie`) goes into a scenario run with `run_test`, and that `dsl_lookup` finds it by plain words. The `write-e2e-test` skill gains a recipe for checking that an element is in view after an action: `assertInViewport` (`assert_in_viewport` in `explore_step`), since `assertVisible` passes below the fold too.
|
|
125
|
+
- 0cd81a6: Fixed: a step on an element (`click`, `fill` and the like) that times out now names the page it waited on — its index and url — and, when a terminal is open, says that page steps keep acting on the page and how to reach each: `setPage(n)` or `setTerminal(n)`. Before, a timeout after `setTerminal()` read as if the step had gone to the terminal. The wait itself is unchanged.
|
|
126
|
+
- 254f93e: Fixed: a run an agent started with `run_test` no longer outlives the MCP server by the whole pause timeout. Once the server is gone (the agent's client closed), a run paused on a failure kept its queue slot and browser for 30 minutes, and the next `e2e` waited "queued behind" it until the process was killed by hand. Now the run waits 60 seconds for a client to `attach_debug_session` (a restarted server picking it up again keeps it), then stops as `abort_runtime` would and frees the queue; a run still waiting in the queue leaves it at once. `UNOTEST_OWNER_GONE_WINDOW_MS` sets the window.
|
|
127
|
+
- 753d564: Fixed: with several `browsers`, `assertScreenshot` compared every engine with the first one's picture; it now keeps a baseline per engine. The first engine listed keeps `<name>.png`, so existing baselines stay as they are; any other engine compares with `<name>.<engine>.png` (`home.webkit.png`). `--update-screenshots` plays every engine and writes each one's baseline; a missing one is saved as a candidate under that file name, ready to download. A failure message names the engine and the baseline file. Reordering `browsers` changes which engine `<name>.png` belongs to — rename the files with it.
|
|
128
|
+
- febf9c2: Fixed: in the run's Environment block the variables taken from the env chosen with `--env` are marked with that env, as `--env local`, not as "environment", which read like the shell's environment.
|
|
129
|
+
|
|
130
|
+
Fixed: in a narrow window the run's Environment table scrolls sideways inside its block instead of cutting off the "from" and "file" columns.
|
|
131
|
+
|
|
132
|
+
- b52f738: Fixed: switching an environment's bundle several times in a row on a box no longer leaves it without a viewer. Before, a switch could try to start the new viewer while the previous one was still being removed, and the daemon log showed `viewer unavailable … 409 container name in use`.
|
|
133
|
+
- Updated dependencies [0d8fd1f]
|
|
134
|
+
- Updated dependencies [6ddc3bf]
|
|
135
|
+
- Updated dependencies [c299aa9]
|
|
136
|
+
- Updated dependencies [894d47f]
|
|
137
|
+
- Updated dependencies [bb98794]
|
|
138
|
+
- Updated dependencies [254f93e]
|
|
139
|
+
- Updated dependencies [0dc7eb7]
|
|
140
|
+
- Updated dependencies [febf9c2]
|
|
141
|
+
- @unotest/protocol@0.57.0
|
|
142
|
+
- @unotest/core@0.57.0
|
|
143
|
+
- @unotest/viewer@0.57.0
|
|
144
|
+
- @unotest/grounder-client@0.57.0
|
|
145
|
+
- @unotest/dsl@0.57.0
|
|
146
|
+
|
|
147
|
+
## [0.56.0] - 2026-10-30
|
|
148
|
+
|
|
149
|
+
### Minor Changes
|
|
150
|
+
|
|
151
|
+
- 7ec07ca: New: `lint --json` prints one JSON document instead of text, for tools that read lint results: every diagnostic as `{file, line, column, severity, rule, message, source}`, including a scenario or a helper that does not parse, plus `advice`, `skipped`, `missing` and `totals`. The exit code is unchanged. Lines about the setup, such as the editor typings hint, are in `advice` with a `kind`, never among the diagnostics; the text output stays as it was. Example: `npx @unotest/web lint --json`. replaces: parsing the text output of `lint`
|
|
152
|
+
|
|
153
|
+
Fixed: `e2e` given a folder of `unotest/e2e/` no longer says the scenario was not found and suggests `init`. It says the argument is a folder, how many scenarios it holds, how to run one (`e2e <folder>/<name>`) and how to run them all as a collection. `run_test` over MCP answers the same.
|
|
154
|
+
|
|
155
|
+
- 8f0d1bc: New: `// @env local, dev` marks a test that belongs to some environments only. `e2e --env <name>` and a collection on that environment leave a test whose marker does not name it out as skipped, with the reason (`@env local, dev: not run on prod`), without starting a browser for it. `lint --env <name>` leaves out a file whose tests are all outside. The marker sits where `// @expect-fail` does: in the file's leading comments for every test, or directly above one `function` line for that test, which wins over the file's. Without `--env`, or without the marker, every test runs as before. `lint` warns about an `@env` name with no `unotest/.env.<name>` or `.secrets.<name>` file. `@unotest/protocol`: `ScenarioAnnotations` gains `envs`. replaces: `if (env('X') === null) skip('…')` at the top of a test, which `lint` could not see
|
|
156
|
+
- f3f1d03: New: `npx @unotest/web upgrade-check [<from>]` prints every Migration note of `@unotest/web` and `@unotest/dsl` between `<from>` and the version that runs, oldest release first, each under its version and date. Without `<from>` it starts from the version the suite's lockfile holds (`unotest/package-lock.json` or a `pnpm-lock.yaml`); with neither, it says what to write. Run it as `cd unotest && npx @unotest/web@<new> upgrade-check` before you upgrade. `--json` prints the notes as data. replaces: reading the changelog by hand for every release since the one you are on
|
|
157
|
+
- 0c73ccb: BREAKING: `fill(locator, value, {force: true})` on a readonly, disabled or hidden field used to pass and leave the field as it was. The step now fails: `the field is readonly and does not hold the value — force skips the editable check, it does not make the field editable`. The value is not shown. A forced fill of an editable field works as before.
|
|
158
|
+
|
|
159
|
+
Migration: a step that forced a fill into a field the page does not let you edit now fails. Make the field editable first (the click or choice that enables it), fill another field, or drop the step if it never did anything.
|
|
160
|
+
|
|
161
|
+
- b8416ec: New: `pause(ms, reason)` for a wait the test means, such as a task that opens 20 minutes after the start. The reason is printed on the step, and `lint:pause-explicit` no longer reports the call. A bare `pause(ms)` is reported as before, and the warning now names the reason form. The DSL reference has a new section, "Waiting a fixed time", which links to `setTestTimeout` for the test's budget. Example: `pause(1260000, 'the hunt opens 21 minutes after the start')`. replaces: shell('sleep …') and a bare pause with a lint-ok comment
|
|
162
|
+
- f8472eb: New: `waitForRequest(glob, {method})` and `assertNoRequest(glob, {method})`. `waitForRequest` takes only a request of that HTTP method (any case); a request of another method is not taken and stays for the next wait, so a GET and a POST to one path no longer need an order of masks. `assertNoRequest` counts only stopped requests of that method. Without `{method}` both behave as before. Example: `waitForRequest('**/api/item', {method: 'POST'})`. replaces: ordering masks so that a GET and a POST to one path are told apart
|
|
163
|
+
|
|
164
|
+
Changed: `screenshot()` is evidence, not a check. A capture that runs out of time no longer fails the test: the call returns `null`, the step gets a warning line, and the reason is filed next to the pictures as `screenshot/<NNN>-<name>-screenshot-error.txt`. Any other capture failure still fails the step, and `assertScreenshot()` still fails on a timeout. New option `screenshot(name, {timeoutMs})`; the default is the context's `defaultTimeoutMs`.
|
|
165
|
+
|
|
166
|
+
- 20884bc: New: `lint:function-newer-than-suite`, a warning when a scenario calls a DSL function this `@unotest/web` knows but the suite's installed release does not. The message names both versions, for example `setTestTimeout() was added in 0.46.0, the suite runs 0.33.0`. The suite's own lint would report the call as an unknown function, and its run would refuse it. Example: `lint` in a suite that installs 0.33.0. replaces: grepping unpacked packages in the npx cache to learn when a function appeared
|
|
167
|
+
|
|
168
|
+
New: the DSL reference has a "Versions" section that lists the release that added each function, generated from the DSL contracts. A DSL function contract now carries `since`.
|
|
169
|
+
|
|
170
|
+
- 62da1f2: New: `hasCookie(name, options?)` says whether a cookie is there at all — the probe that tells a missing cookie from an empty value, as `hasAttribute` does for `getAttribute`. `getCookie` still reads `''` for both. Example: `assertTrue(!hasCookie('session'))` after a logout. replaces: `getCookie(name) == ''`, which an empty cookie also passes
|
|
171
|
+
- 62da1f2: New: `getCookie(name, {page: true})` and `hasCookie(name, {page: true})` read the cookies the page's script is given — `document.cookie` of the page, or of the frame entered with `enterFrame`. Without the option they read the browser context's jar as before: every domain and path, `httpOnly` too. With it, an `httpOnly` cookie or one for another path or domain reads as missing, as the app sees it. Example: `assertTrue(!hasCookie('session', {page: true}))` for an `httpOnly` session. replaces: `evaluate(() => document.cookie)`
|
|
172
|
+
- 62da1f2: BREAKING: `setCookie` now reads the cookie back after the write, and a cookie the browser does not keep fails the step instead of passing. The most common case is `sameSite: 'None'` without `secure: true`: `setCookie('cross'): the browser dropped the cookie — sameSite: 'None' requires secure: true`. The value is not shown. A cookie set with `expires` in the past is a deletion and passes as before.
|
|
173
|
+
|
|
174
|
+
Migration: add `secure: true` next to `sameSite: 'None'`. A step that relied on the cookie being dropped should delete it with `expires` in the past, or not set it.
|
|
175
|
+
|
|
176
|
+
- 0ae6af4: New: `dsl_lookup` answers a task that is a CLI command's, not a scenario's, with that command. The task is weighed against the commands `npx @unotest/web --help` lists as well as the DSL functions; when a command explains it best, the reply carries `command: {name, synopsis, summary, help}`, a `hint` that says it is a CLI command and not a scenario function, and an empty `functions`. Example: `set up a cron schedule for the suite` returns `schedules`, `log in to the cloud account` returns `login`. Replies for function tasks are unchanged. replaces: reading the `commands` pointer and searching `--help` for the command by hand
|
|
177
|
+
|
|
178
|
+
Fixed: `dsl_lookup` no longer offers `env` and `boundingBox` for "send only the staging environment to a new box", or `env` for "find a typo in a variable name": words that belong to the CLI's commands no longer count as evidence for a function.
|
|
179
|
+
|
|
180
|
+
- 992fb90: BREAKING: an empty value (`ADMIN_BASE_URL=` in `unotest/.env`, not set by the active `--env` overlay) now means the name is not set on that environment. A test that reads the name bare fails with an error that names the variable and the environment, instead of reading `""` — before, `goto(ADMIN_BASE_URL)` quietly opened `APP_BASE_URL` and the test passed. `env('ADMIN_BASE_URL', fallback)` returns the fallback, or `null` without one. A value set by the overlay or the shell is read as before.
|
|
181
|
+
|
|
182
|
+
Migration: a test that reads a name left empty on some environment now fails there. Skip it where the name is missing, at the top of the test: `skip('ADMIN_BASE_URL is not set here', env('ADMIN_BASE_URL', null) == null);` — this works with `--env` and without. A `// @env local, staging` marker above the test is enough only if every run passes `--env`: a run without `--env` ignores the marker and fails the same way.
|
|
183
|
+
|
|
184
|
+
- 83bda13: New: a `snapshot` step for `explore_step` and `explore_steps`, `{action: "snapshot", section, description}`. Its reply carries `outline`, the page outline in the `get_page_snapshot` format, and the refs in it are live for the steps after it. A ref belongs to the snapshot that listed it, so a batch that navigates and then acts by ref puts a `snapshot` step in between: a login with `goto`, `snapshot`, `fill`, `fill`, `click` is one call. The step is never recorded and never appears in the saved test. A server started with `UNOTEST_SNAPSHOT=0` refuses it and says how to locate elements instead. replaces: splitting the batch around a `get_page_snapshot` call
|
|
185
|
+
|
|
186
|
+
Fixed: a stale ref error names only the discovery tools the session has. With snapshots on, it points to `get_page_snapshot` or a `snapshot` step. With the grounder on, it points to the intent step or `ground_element`. With both off, it points to `find_element`. It used to suggest ground mode even when the grounder was off.
|
|
187
|
+
|
|
188
|
+
- 4e5a470: New: `init` writes the idioms to `unotest/e2e/examples/idioms/` — one scenario per habit the DSL has a typed step for (a pause before an absence check, page code for a CSS value, a guessed tab index…), each naming the habit and the step that replaces it, with a README. They ship with the package; a later `init` leaves your edits alone, and `init --force` keeps your version as `.bak`. `llms.txt` lists every idiom with where `init` writes it, and `api` without a word ends with the same pointer. Example: `npx @unotest/web e2e examples/idioms/never-appears`. replaces: nothing
|
|
189
|
+
- d48c5a6: New: each `check_locator` match now names the element the way the page snapshot and `find_element` do. `name` is the accessible name, so a field found by `getByPlaceholder` or labelled by a `<label>` carries its name instead of only `role: textbox`; it is `""` when the element has none. Form fields also report `placeholder` and their current `value`; a password field reports `valueHidden: true` and never its value.
|
|
190
|
+
replaces: a snapshot or a re-run of the test to see whether the locator found the right field
|
|
191
|
+
|
|
192
|
+
Fixed: `find_element` ancestors now carry a `label` with the region label `get_page_snapshot` prints. A form titled by its own heading showed as `form "Employees"` in the snapshot but as a form with an empty name in `ancestors`; it now has `label: "Employees"`, while `name` stays the accessible name that `find_element({ name })` matches.
|
|
193
|
+
|
|
194
|
+
### Patch Changes
|
|
195
|
+
|
|
196
|
+
- b6f8876: Fixed: in a live debug run, a breakpoint toggled in the viewer reaches the run only after it has been saved. When the save is refused (a box whose breakpoint store is read-only), the mark goes back on screen and the run no longer stops on a line shown without one. The breakpoint store directory can now be set explicitly with `UNOTEST_STATE_DIR`; a box sets it for the viewer and every run. Without it, the directory is found as before. `@unotest/protocol`: `STATE_DIR_ENV`, `stateDirIn` and `runsTreeEnv`.
|
|
197
|
+
- 548aae6: Fixed: `bundle push` no longer refuses a scenario that names a system path such as `/proc/self/status`, `/etc/hosts` or `/dev/null`. The check used to look such a path up on the author's machine, so the same bundle was refused on Linux and accepted on macOS. Now only two places are judged: a file inside the project that the bundle does not carry is still an error, and a file in your home directory outside the project is a warning (the box will not have it). Any other path belongs to the machine and is not checked.
|
|
198
|
+
|
|
199
|
+
Fixed: editor typings now use JavaScript's own library (`"lib": ["es2023", "dom"]`), the one the `lint` type layer already checks against. A scenario runs as plain JavaScript, so `Date`, classes and `Map.prototype.keys` complete in the editor, and `sortBy`, which the scenario engine no longer has, no longer does.
|
|
200
|
+
|
|
201
|
+
Migration: run `npx @unotest/web types` in `unotest/`. A `jsconfig.json` an earlier `init` wrote is brought up to date; until then `lint` and runs remind you in one line. A jsconfig you edited by hand is never rewritten: drop `"noLib"` from `compilerOptions`, set `"lib": ["es2023", "dom"]`, and remove `unotest-lib.d.ts` from `include`. The `types/unotest-lib.d.ts` file still ships, frozen, for this release, so an old jsconfig keeps its completion; it will be removed in a later release.
|
|
202
|
+
|
|
203
|
+
- de4daff: Fixed: reading a declared variable as `globalThis.NAME` no longer hands a silent `undefined` to the next call (`goto(): argument 1 (url) must be a string value, got nothing`). Since 0.55.0 only a bare read reaches the project's variables; the step now fails at the read with `globalThis.NAME does not read the project's variable` and says what to write: the bare name `NAME`, or `env("NAME")` for a value that is not a secret. The value is not shown. A name the project does not declare, or one the scenario sets on `globalThis` itself, reads as before.
|
|
204
|
+
- 0ff8049: Fixed: the last two next steps `init` prints now start with `cd unotest &&`, like the others: `cd unotest && npx @unotest/web init --ci github` and `cd unotest && npx @unotest/web login && npx @unotest/web box create --ttl none`. From the repository root `npx` fetched the latest npm release instead of the version the suite pins.
|
|
205
|
+
- c1872ce: Fixed: the MCP server now says when it is not the `@unotest/web` version the suite installed (`unotest/node_modules`). The line comes in the server's instructions and once, in the first tool reply: `run_test`, `lint` and explore run on the server's version, and `cd unotest && npx @unotest/web init` pins `.mcp.json` to the suite's version. Running `init` again now pins an `npx @unotest/web mcp` entry that has no version. An entry you changed (a local binary, another pin) is kept. When the versions agree, nothing is added.
|
|
206
|
+
- 7e8ee03: New: `sandbox.database` and `sandbox.apiBaseUrl` take `'{{NAME}}'`: the value of `NAME` in the active environment's files (`unotest/.env*`, `unotest/.secrets*`, the shell), read when the run starts. One config now points each environment at its own database or API, with the password in `unotest/.secrets.<env>`. The value is masked in logs. The reference is the whole value; `postgres://u:{{PW}}@host` is refused. A name with no value stops the run before the browser starts, and `lint` reports it on the config file as `lint:external-variable-undeclared`. Under `--env`, an `apiBaseUrl` the overlay leaves to the base `unotest/.env` is refused, as for `goto(NAME)` (`lint:env-host-from-base`). A scenario still cannot point the run at another database. replaces: a script called through `shell()` that reads the connection string from the application's own `.env`
|
|
207
|
+
- 0c73ccb: Fixed: failed checks and timed-out actions now name the locator they were about, with its options. `assertCount`, `assertVisible`, `assertHidden`, `assertNeverAppears` and `waitForCount` end with `for getByRole("button", {name: "Save", disabled: false})`. A timed-out `click`, `fill`, `waitFor` and the other actions start with `click for getByRole(…): ` before Playwright's own words. In a step with several `getByRole` calls, the failure now says which one missed.
|
|
208
|
+
- 0c73ccb: Fixed: `assertText` on a locator that matches no element said "the page gave no answer … (its main thread is busy)". It now says `no element matches getByRole("button", {name: "Save", disabled: false}) within 1000ms`. A present element with other text still fails with `expected … got …`.
|
|
209
|
+
- afefcfb: Fixed: `lint` checks the option keys of `assertScreenshot('page', {…})`, `assertNoFile(path, {…})` and `waitForFile(path, {…})` when the options come second. A typo such as `{maxDifRatio: 0}` or `{withinMS: 100}` used to pass lint silently and is now reported as an unknown option, naming the keys that are supported.
|
|
210
|
+
- 7985139: Fixed: `shell(..., {timeoutMs})` longer than what is left of the test's budget now warns on the step before the command starts. The warning gives both numbers and the `setTestTimeout(…)` that fits the wait. The command still runs. Before, the test was cut off with a bare `testTimeoutMs budget exhausted` that did not name the wait. A literal `timeoutMs` that long was already reported by `lint:wait-exceeds-test-budget`.
|
|
211
|
+
- 7da3404: Fixed: `dsl_lookup` and `unotest-web api` lead from the habits `waitForResponse` replaces to it. "wait until the items request finishes instead of a pause" and "check what the server returned for the items request" now find `waitForResponse` first, and so do `api pause after click` and `api waitUntil networkEntries`, which found no function before. `api pause` and `api sleep` still find `pause` first.
|
|
212
|
+
- 2b9fdbd: Fixed: `lint` without `--env` no longer reports a variable that only `unotest/.env.local`, `unotest/.env.<name>` or `unotest/.secrets.<name>` declares. With no environment chosen, a name any `unotest/.env*` or `unotest/.secrets*` file declares counts. The error stays for a name no file declares. `lint --env <name>` reads the same files as that run, as before.
|
|
213
|
+
|
|
214
|
+
Fixed: `init` no longer ignores `unotest/.secrets.example`. It now writes `!unotest/.secrets.example` right after `unotest/.secrets*`, the same way it keeps `unotest/.env.example`. Running `init` again adds the line to an existing `.gitignore`. `lint` warns when git ignores either template: a fresh checkout would not know the names it declares.
|
|
215
|
+
|
|
216
|
+
Fixed: the `lint:external-variable-undeclared` message, and the "external variable not found" message of a run, now point at the committed template. A credential (a name some `unotest/.secrets*` file holds, or one ending in `_PASSWORD`, `_TOKEN`, `_SECRET` or `_KEY`) goes to `unotest/.secrets.example`, any other name to `unotest/.env.example`. The value still goes to `unotest/.secrets` or `unotest/.env`.
|
|
217
|
+
|
|
218
|
+
- 2009b14: Fixed: a recorded `goto` no longer pins the test to the stand it was recorded on. A URL under the session's base URL renders as a relative path, `goto("/login/")`. A URL under another `*_BASE_URL` variable of the session renders through it, `goto(ITR_BASE_URL + "/login/")`. The longest matching value wins. Two variables with the same value keep the URL literal and add an `AMBIGUOUS_BASE_URL` warning that names both.
|
|
219
|
+
|
|
220
|
+
Fixed: the `explore_step` description and the `write-e2e-test` skills now say that `section` and `description` are always required. In ad-hoc mode (no `explorationId`) they only label the debug log. The docs used to say ad-hoc did not need them, and the schema refused the call.
|
|
221
|
+
|
|
222
|
+
Changed: `lint:goto-concat` now flags only `goto(APP_BASE_URL + ...)`, the variable that feeds the browser's base URL. `goto(ITR_BASE_URL + ...)` for a second host is no longer reported.
|
|
223
|
+
|
|
224
|
+
- 07921d0: Fixed: a value recorded in an exploration started with `env` now renders as the variable it names. `fill(..., "ITR_FLEET")` typed the overlay's value live, but the generated test held the string `"ITR_FLEET"` and failed on its own assertion; it is now `fill(..., ITR_FLEET)`. A bare name that a project env file declares but the session has no value for still goes in as text, and is now said: the step reply carries a `variableWarnings` line naming the file, and the generated test a `VAR_AS_LITERAL` warning. Ad-hoc `explore_step` resolves against the base environment and warns the same way.
|
|
225
|
+
- 094b305: Fixed: `explore_start` now says why intent locators are off in a `grounder.cause` field: `off`, `unreachable`, `models-missing` (with the names in `missing`) or `misconfigured`. With `UNOTEST_GROUNDER_MODE=off`, a deliberate snapshot-only setup, the answer no longer offers the paid Picker or any other command. When a local ollama is running but the configured models are not pulled, the reason no longer says the grounder is unreachable and `orElse` is one `ollama pull` command for the missing models instead of `ollama serve`; the Picker stays in `next`.
|
|
226
|
+
- 48d3c0e: Fixed: `lint:shadows-dsl-function` no longer warns about every variable or parameter named like a DSL function. A variable such as a helper's `check` or `count` parameter is reported only when the code that sees it calls `check()` or `count()` bare, the call the variable takes away. A function of your own with a DSL name is still reported as before.
|
|
227
|
+
|
|
228
|
+
Fixed: `lint:env-host-from-base` no longer reports a host variable that the base `unotest/.env` sets empty (`ADMIN_BASE_URL=`) and the active overlay does not set. An empty value means the host does not exist in that environment, so the advice to list it under `env.shared` was the opposite of what the file says.
|
|
229
|
+
|
|
230
|
+
Docs: every `lint:*` rule now has its own section under "Linter rules" at the end of the DSL reference (`dsl-reference.md`, shipped in the package's `guides/`), moved there from the troubleshooting manual. This includes `lint:env-host-from-base`, in place since 0.43.0 and not named until now: what counts as a host, the three places a variable becomes one, `env.shared`, and what an empty value in the base file means.
|
|
231
|
+
|
|
232
|
+
- 175c2f3: Fixed: the MCP tool `cloud_box_create` now says in its description that a box rented without `ttl` lives for 24 hours by default, and that `ttl: "none"` keeps a CI box. Before, it said only that the cloud's default applies, so an agent renting a box for CI learned the number only from the approval or from `expiresAt`. The CLI plan of `box create` says the same in its own words.
|
|
233
|
+
- 4b713f5: Fixed: a run that just finished no longer goes missing from the viewer's run history until the page is reloaded. The history was read the moment the run ended and could come back before the run had been saved to it; the viewer now reads it again once the run is in, and the WebSocket stream carries a new `fs:run-indexed` message for that.
|
|
234
|
+
- b9edb1a: Fixed: when a test fails, the variables saved for the failed run and a debug pause (and shown in the viewer) no longer hold values of sensitive response headers. Values under credential-like keys, such as `authorization`, `cookie`, `x-csrf-token`, `x-api-key` or `x-auth-*`, are masked as `‹redacted›`; the key stays. The scenario itself still reads the real header value from `waitForResponse`.
|
|
235
|
+
- 1804b45: Fixed: in a narrow history panel, the tally of a collection or file run (`1 ✓ 2 ✗ (1 ‼) 1●`) is no longer cut off at the edge. When it does not fit beside the name, it moves to a second line of the row and stays whole.
|
|
236
|
+
- 8cd94f9: Fixed: `npm audit` in a project that installs `@unotest/web` no longer reports the fastify vulnerabilities the viewer used to bring in. The viewer now runs on NestJS 12 and validates requests itself instead of through `nestjs-zod`, which does not support NestJS 12. Its HTTP API answers as before: an invalid request gets the same 400 body, `{ "statusCode": 400, "message": "Validation failed", "errors": [...] }`.
|
|
237
|
+
- Updated dependencies [b6f8876]
|
|
238
|
+
- Updated dependencies [8f0d1bc]
|
|
239
|
+
- Updated dependencies [20884bc]
|
|
240
|
+
- Updated dependencies [d48c5a6]
|
|
241
|
+
- Updated dependencies [4b713f5]
|
|
242
|
+
- Updated dependencies [1804b45]
|
|
243
|
+
- Updated dependencies [8cd94f9]
|
|
244
|
+
- @unotest/viewer@0.56.0
|
|
245
|
+
- @unotest/protocol@0.56.0
|
|
246
|
+
- @unotest/dsl@0.56.0
|
|
247
|
+
- @unotest/grounder-client@0.56.0
|
|
248
|
+
- @unotest/core@0.56.0
|
|
249
|
+
|
|
3
250
|
## [0.55.0] - 2026-10-25
|
|
4
251
|
|
|
5
252
|
### Minor Changes
|
|
@@ -2554,7 +2801,7 @@ picker on` fetches this project's own access and writes the three grounder
|
|
|
2554
2801
|
|
|
2555
2802
|
That screen named one command:
|
|
2556
2803
|
|
|
2557
|
-
|
|
2804
|
+
npx @unotest/web bundle push --run --env ENVIRONMENT
|
|
2558
2805
|
|
|
2559
2806
|
In a project that has just been created, the command refuses with `no box
|
|
2560
2807
|
address` before it does anything: the project holds neither the box's address
|
|
@@ -2563,8 +2810,8 @@ address` before it does anything: the project holds neither the box's address
|
|
|
2563
2810
|
|
|
2564
2811
|
The screen now names both steps, in the order they have to happen:
|
|
2565
2812
|
|
|
2566
|
-
|
|
2567
|
-
|
|
2813
|
+
npx @unotest/web box access larch
|
|
2814
|
+
npx @unotest/web bundle push --run --env ENVIRONMENT
|
|
2568
2815
|
|
|
2569
2816
|
The box's own name is filled in when its licence carries one. `box access`
|
|
2570
2817
|
with no name refuses, and its refusal offers to create a box — to somebody who
|
package/README.md
CHANGED
|
@@ -24,14 +24,14 @@ package; the full reference is at https://docs.unotest.com/reference/dsl/.
|
|
|
24
24
|
- **Navigation** — `goto`, `reload`, `goBack`, `goForward`, `waitForUrl`, `waitForNavigation`
|
|
25
25
|
- **Locators** — `locator`, `getByRole`, `getByText`, `getByLabel`, `getByPlaceholder`, `getByAltText`, `getByTitle`, `getByTestId`, `contentFrame`
|
|
26
26
|
- **Refining a locator** — `filter`, `first`, `last`, `nth`, `randomNth`
|
|
27
|
-
- **Actions** — `click`, `doubleClick`, `check`, `uncheck`, `hover`, `scrollIntoView`, `fill`, `press`, `selectOption`, `dragAndDrop`, `uploadFile`, `clipboardPaste`
|
|
27
|
+
- **Actions** — `click`, `doubleClick`, `check`, `uncheck`, `hover`, `scrollIntoView`, `fill`, `press`, `selectOption`, `dragAndDrop`, `dragBy`, `tap`, `longPress`, `swipe`, `uploadFile`, `clipboardPaste`
|
|
28
28
|
- **Waits and the page clock** — `waitFor`, `waitForText`, `waitForCount`, `waitForAnimations`, `pause`, `waitForDownload`, `clockFreeze`, `clockTick`, `clockRun`
|
|
29
|
-
- **Assertions** — `assertText`, `assertTexts`, `assertAttribute`, `assertVisible`, `assertHidden`, `assertNeverAppears`, `assertValue`, `assertCount`, `assertUrl`, `assertJudge`, `assertScreenshot`, `assertEqual`, `assertTrue`, `assertSchema`, `assertFileHas`, `assertFileLacks`, `skip`, `setTestTimeout`
|
|
29
|
+
- **Assertions** — `assertText`, `assertTexts`, `assertAttribute`, `assertVisible`, `assertHidden`, `assertInViewport`, `assertNoFocusZoom`, `assertNeverAppears`, `assertValue`, `assertCount`, `assertUrl`, `assertJudge`, `assertScreenshot`, `assertEqual`, `assertTrue`, `assertSchema`, `assertFileHas`, `assertFileLacks`, `skip`, `setTestTimeout`
|
|
30
30
|
- **Reading the page and values** — `clipboardRead`, `assertClipboard`, `count`, `textContent`, `texts`, `inputValue`, `isVisible`, `isChecked`, `isDisabled`, `isEnabled`, `hasAttribute`, `computedStyle`, `getImageSize`, `hasAnimation`, `animations`, `randomFirstName`, `randomLastName`, `randomEmail`, `randomText`, `randomWord`, `json`, `textContains`, `textJoin`, `nowMs`, `today`, `daysFromNow`, `textMatches`, `parseJson`, `urlParam`, `toNumber`, `round`, `formatNumber`, `env`
|
|
31
31
|
- **Page state** — `getAttribute`, `getInnerText`, `getInputValue`, `boundingBox`, `getTitle`, `getUrl`, `log`
|
|
32
|
-
- **Storage and cookies** — `setLocalStorage`, `getLocalStorage`, `setCookie`, `getCookie`
|
|
32
|
+
- **Storage and cookies** — `setLocalStorage`, `getLocalStorage`, `setCookie`, `getCookie`, `hasCookie`
|
|
33
33
|
- **Tabs, frames, contexts, extensions** — `setPage`, `waitForPage`, `bringToFront`, `setPageHidden`, `newPage`, `closePage`, `setViewport`, `emulateMedia`, `newContext`, `setContext`, `enterFrame`, `exitFrame`, `addVirtualAuthenticator`, `virtualCredentials`, `removeVirtualAuthenticator`, `grantPermissions`, `setOffline`, `waitForServiceWorker`, `extensionId`, `evaluateInServiceWorker`
|
|
34
|
-
- **Data, files, network, processes** — `shell`, `waitForFile`, `assertNoFile`, `waitForJsonLine`, `assertNoJsonLine`, `readJsonLine`, `readJson`, `readFile`, `readFileInfo`, `waitForFileCount`, `assertFileCount`, `dbQuery`, `dbExec`, `apiCall`, `upload`, `mockRoute`, `unmockRoute`, `waitForRequest`, `waitForResponse`, `waitForWebSocket`, `networkEntries`, `assertNoRequest`, `openTerminal`, `setTerminal`, `closeTerminal`, `terminalType`, `terminalClipboardWrite`, `terminalClipboardRead`, `terminalPress`, `terminalWaitForText`, `terminalWaitForExit`, `terminalAssertText`, `terminalResize`, `terminalText`, `terminalScreenshot`, `mcpStart`, `mcpCall`, `mcpWaitNotification`, `mcpStop`, `vmAvailable`, `vmClone`, `vmRun`, `vmIp`, `vmStop`, `vmDelete`
|
|
34
|
+
- **Data, files, network, processes** — `shell`, `waitForFile`, `assertNoFile`, `waitForJsonLine`, `assertNoJsonLine`, `readJsonLine`, `readJson`, `readFile`, `readFileInfo`, `waitForFileCount`, `assertFileCount`, `dbQuery`, `dbExec`, `apiCall`, `upload`, `mockRoute`, `unmockRoute`, `waitForRequest`, `waitForResponse`, `waitForWebSocket`, `waitForWebSocketFrame`, `webSocketFrames`, `networkEntries`, `assertNoRequest`, `openTerminal`, `setTerminal`, `closeTerminal`, `terminalType`, `terminalClipboardWrite`, `terminalClipboardRead`, `terminalPress`, `terminalWaitForText`, `terminalWaitForExit`, `terminalAssertText`, `terminalResize`, `terminalText`, `terminalScreenshot`, `mcpStart`, `mcpCall`, `mcpCallStart`, `mcpCallResult`, `mcpWaitNotification`, `mcpStop`, `vmAvailable`, `vmClone`, `vmRun`, `vmIp`, `vmStop`, `vmDelete`
|
|
35
35
|
- **Diagnostics** — `screenshot`, `note`, `consoleEntries`, `pageErrors`, `assertNoConsoleErrors`
|
|
36
36
|
- **Structure** — `step`, `teardown`, `waitUntil`, `assertNever`
|
|
37
37
|
- **Page code (last resort)** — `evaluate`, `evaluateOnLocator`
|
|
@@ -47,8 +47,9 @@ npm install --prefix unotest
|
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
Run once in your project — any stack (Node, Django, Rails, Go, …), no
|
|
50
|
-
`package.json` required. `init` writes the config
|
|
51
|
-
|
|
50
|
+
`package.json` required. `init` writes the config, a starter scenario and
|
|
51
|
+
the idioms (`unotest/e2e/examples/idioms/`: one scenario per habit, with
|
|
52
|
+
the typed step that replaces it), sets up the browser (it asks: bundled Chromium or your system Chrome;
|
|
52
53
|
without a terminal to ask in, as in CI, it takes the system Chrome when it
|
|
53
54
|
finds one), and wires the MCP config so Claude Code / Cursor / Codex
|
|
54
55
|
pick the server up automatically. Re-run anytime to update — it never
|
package/bin/unotest-web.js
CHANGED
|
@@ -190,6 +190,19 @@ const child = spawn(cmd, cmdArgs, {
|
|
|
190
190
|
stdio: linkParent ? ["inherit", "inherit", "inherit", "ipc"] : "inherit",
|
|
191
191
|
});
|
|
192
192
|
|
|
193
|
+
// An MCP server's run_test starts this wrapper with a channel of its own.
|
|
194
|
+
// The server going — the agent's client closed — is not a stop: a run it
|
|
195
|
+
// started waits a window for a restarted server to attach, then stops. So
|
|
196
|
+
// it is told to the cli as a message, not forwarded as a signal. The kind
|
|
197
|
+
// is `OWNER_GONE` of src/runner/parent-link.ts, which decides the rest.
|
|
198
|
+
// Under the tsx fallback the cli holds no channel and is not told.
|
|
199
|
+
if (process.connected === true && process.channel) {
|
|
200
|
+
process.channel.unref();
|
|
201
|
+
process.once("disconnect", () => {
|
|
202
|
+
if (child.connected) child.send({ kind: "owner-gone" });
|
|
203
|
+
});
|
|
204
|
+
}
|
|
205
|
+
|
|
193
206
|
// Pass termination on to the child. This dispatcher is a thin wrapper: kill
|
|
194
207
|
// IT and the real process — the viewer server, a running scenario — has to
|
|
195
208
|
// go too, or it is orphaned to init and keeps its port for the rest of the
|