@unotest/web 0.50.0 → 0.51.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/llms.txt ADDED
@@ -0,0 +1,223 @@
1
+ # @unotest/web
2
+
3
+ > End-to-end tests for web apps, written as JavaScript scenarios that call the functions below.
4
+ > Each line: signature · the keys its options object takes · the release that added it — when you need it.
5
+ > Prefer a typed function to page code, shell or a fixed pause: most habits have one.
6
+
7
+ Search this index from a terminal: `npx @unotest/web api <word>` (`api sleep`, `api clipboard`, `api css`).
8
+ Full reference: https://docs.unotest.com/reference/dsl/
9
+
10
+ ## Navigation
11
+
12
+ - `goto(url, { waitUntil?, timeoutMs? })` · options `{waitUntil?, timeoutMs?}` (alias: timeout → timeoutMs) — Navigate to a URL.
13
+ - `reload({ waitUntil?, timeoutMs? })` · options `{waitUntil?, timeoutMs?}` (alias: timeout → timeoutMs) — Reload the current page.
14
+ - `goBack({ waitUntil?, timeoutMs? })` · options `{waitUntil?, timeoutMs?}` (alias: timeout → timeoutMs) — Navigate back in history.
15
+ - `goForward({ waitUntil?, timeoutMs? })` · options `{waitUntil?, timeoutMs?}` (alias: timeout → timeoutMs) — Navigate forward in history.
16
+ - `waitForUrl(pattern, { waitUntil?, timeoutMs? })` · options `{waitUntil?, timeoutMs?}` (alias: timeout → timeoutMs) — Wait until the URL contains `pattern` (a string, substring match) or matches it (a /regex/, unanchored).
17
+ - `waitForNavigation({ timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Wait for the next navigation event.
18
+
19
+ ## Locators
20
+
21
+ - `locator(css, { hasText?, hasNotText?, has?, hasNot? }?)` · options `{hasText?, hasNotText?, has?, hasNot?}` — Match by raw CSS selector.
22
+ - `getByRole(role, { name?, exact?, checked?, disabled?, expanded?, includeHidden?, level?, pressed?, selected? })` · options `{name?, exact?, checked?, disabled?, expanded?, includeHidden?, level?, pressed?, selected?}` — Match by ARIA role + accessible name.
23
+ - `getByText(text, { exact? })` · options `{exact?}` — Match by visible text content.
24
+ - `getByLabel(text, { exact? })` · options `{exact?}` — Match a form control by its associated label.
25
+ - `getByPlaceholder(text, { exact? })` · options `{exact?}` — Match an input by its placeholder.
26
+ - `getByAltText(text, { exact? })` · options `{exact?}` — Match an image by its `alt` text.
27
+ - `getByTitle(text, { exact? })` · options `{exact?}` — Match by `title` attribute.
28
+ - `getByTestId(id)` — Match by `data-testid`.
29
+ - `contentFrame(locator)` — Resolve an `<iframe>` element to its content frame.
30
+
31
+ ## Refining a locator
32
+
33
+ - `filter(locator, { hasText?, hasNotText?, has?, hasNot? })` · options `{hasText?, hasNotText?, has?, hasNot?}` — Keep matches by contained text or a nested child locator.
34
+ - `first(locator)` — First match.
35
+ - `last(locator)` — Last match.
36
+ - `nth(locator, index)` — The N-th match (0-indexed).
37
+ - `randomNth(locator)` — A random one of the matches — for flows where any item will do.
38
+
39
+ ## Actions
40
+
41
+ - `click(locator, { force?, timeoutMs?, position?, modifiers?, button?, clickCount? })` · options `{force?, position?, modifiers?, button?, clickCount?, timeoutMs?}` (alias: timeout → timeoutMs) — Click an element.
42
+ - `doubleClick(locator, { force?, position?, modifiers?, timeoutMs? })` · options `{force?, position?, modifiers?, timeoutMs?}` (alias: timeout → timeoutMs) — Double-click an element.
43
+ - `check(locator, { force?, timeoutMs? })` · options `{force?, timeoutMs?}` (alias: timeout → timeoutMs) — Check a checkbox/radio/switch: click, then wait until it reads checked (a controlled widget may flip a beat later).
44
+ - `uncheck(locator, { force?, timeoutMs? })` · options `{force?, timeoutMs?}` (alias: timeout → timeoutMs) — Uncheck a checkbox/switch: click, then wait until it reads unchecked.
45
+ - `hover(locator, { force?, position?, timeoutMs? })` · options `{force?, position?, timeoutMs?}` (alias: timeout → timeoutMs) — Hover over an element.
46
+ - `scrollIntoView(locator)` — Scroll an element into the viewport.
47
+ - `fill(locator, value, { force?, timeoutMs? })` · options `{force?, timeoutMs?}` (alias: timeout → timeoutMs) — Clear and type a value into an input.
48
+ - `press(locator, key, { delay?, timeoutMs? })` · options `{delay?, timeoutMs?}` (alias: timeout → timeoutMs) — Press a key (e.g. 'Enter', 'Control+A').
49
+ - `selectOption(locator, value, { force?, timeoutMs? })` · options `{force?, timeoutMs?}` (alias: timeout → timeoutMs) — Select option(s) in a `<select>`.
50
+ - `dragAndDrop(from, to, { force?, timeoutMs? })` · options `{force?, timeoutMs?}` (alias: timeout → timeoutMs) — Drag one element onto another.
51
+ - `uploadFile(locator, files)` — Set files on a file input.
52
+ - `clipboardPaste(locator, text)` — Paste text.
53
+
54
+ ## Waits and the page clock
55
+
56
+ - `waitFor(locator, { state?, timeoutMs? })` · options `{state?, timeoutMs?}` (alias: timeout → timeoutMs) — Wait for an element state: DOM presence ('visible' default, 'hidden', 'attached', 'detached') or interaction ('enabled' / 'disabled' — same probe as isEnabled, so aria-disabled counts).
57
+ - `waitForText(text, { exact?, state?, timeoutMs? })` · options `{state?, exact?, timeoutMs?}` (alias: timeout → timeoutMs) — Wait until `text` appears anywhere on the page.
58
+ - `waitForCount(locator, count, { exact?, timeoutMs? })` · options `{exact?, timeoutMs?}` (alias: timeout → timeoutMs) — Poll until the locator matches AT LEAST `count` elements (`{exact: true}` for exactly).
59
+ - `waitForAnimations(locator, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) · since 0.47.0 — Wait until the element and its descendants have no animation still running — a dialog done fading in, a card done sliding.
60
+ - `pause(ms)` — Explicit delay.
61
+ - `waitForDownload(options?) → { path, name }` · options `{timeoutMs?, name?}` · since 0.45.0 — The first file the page downloaded that the scenario has not taken yet, saved with the run: `path` is absolute (read it with waitForFile), `name` is the name the site suggested.
62
+ - `clockFreeze(iso)` · since 0.44.0 — Stop time on the page at an ISO instant: `Date` reads it and no timer fires until clockTick / clockRun.
63
+ - `clockTick(ms)` · since 0.44.0 — Move frozen time forward by ms, firing every timer due in it.
64
+ - `clockRun()` · since 0.44.0 — Let time on the page run again from where it stands.
65
+
66
+ ## Assertions
67
+
68
+ - `assertText(locator, expected, { exact?, not?, timeoutMs? })` · options `{exact?, not?, timeoutMs?}` (alias: timeout → timeoutMs) — Element's text equals `expected` (a string; exact: false — contains it) or matches it (a /regex/).
69
+ - `assertTexts(locator, expected, { exact?, timeoutMs? })` · options `{exact?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.46.0 — The locator matches exactly expected.length elements, and element i's text matches expected[i] (string or /regex/, same rules as assertText), in order.
70
+ - `assertAttribute(locator, name, expected, { exact?, not?, timeoutMs? })` · options `{exact?, not?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.46.0 — Polls the attribute `name` until it equals `expected` (exact: false — contains) or matches a /regex/.
71
+ - `assertVisible(locator, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Element is visible.
72
+ - `assertHidden(locator, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Element is hidden or detached.
73
+ - `assertNeverAppears(locator, { withinMs })` · options `{withinMs?}` — Negative window assert: FAIL the moment the locator becomes visible; pass when the whole window elapsed clean.
74
+ - `assertValue(locator, expected, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Input's value equals `expected`.
75
+ - `assertCount(locator, expected, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Number of matches equals `expected`.
76
+ - `assertUrl(pattern, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Current URL contains `pattern` (a string) or matches it (a /regex/, unanchored).
77
+ - `assertJudge(locator, rubric)` · since 0.22.0 — LLM-judge assert for free-form text (chat replies, generated content): the element's rendered text + a natural-language rubric go to the configured judge (UNOTEST_JUDGE_MODE); a fail verdict fails the step with the judge's reasoning.
78
+ - `assertScreenshot(name | locator, name?, { maxDiffRatio?, threshold?, mask?, ignore?, fullPage? })` · options `{maxDiffRatio?, threshold?, mask?, ignore?, fullPage?}` · since 0.44.0 — The page (or an element) against the PNG baseline unotest/e2e/<scenario>.screenshots/<name>.png.
79
+ - `assertEqual(actual, expected)` · since 0.45.0 — Deep equality as JSON sees it: key order does not count, a missing key differs from a null one.
80
+ - `assertTrue(condition, message?)` — Assert a boolean condition.
81
+ - `assertSchema(value, schema)` · since 0.46.0 — Check a value against a JSON Schema (draft 2020-12), e.g.
82
+ - `assertFileHas(path, needle, { timeoutMs? })` · options `{timeoutMs?}` · since 0.51.0 — A string or a regex must appear in a file, or anywhere in a directory (searched recursively; symlinks inside are not followed).
83
+ - `assertFileLacks(path, needle, { withinMs? })` · options `{withinMs?}` · since 0.51.0 — A string or a regex must NOT appear in a file or a directory tree — a secret in a log or a DB dump.
84
+ - `skip(reason, condition?)` · since 0.46.0 — End the test as skipped when the condition is true (always, without one) — it does not apply here: skip('no live API configured', env('LIVE_API') == null).
85
+ - `setTestTimeout(ms)` · since 0.46.0 — This test's own time budget, counted from its start (Playwright's test.setTimeout).
86
+
87
+ ## Reading the page and values
88
+
89
+ - `clipboardRead() → string` · since 0.51.0 — The clipboard's text as the active page reads it — what a 'copy' button left there.
90
+ - `assertClipboard(expected, { timeoutMs? })` · options `{timeoutMs?}` · since 0.51.0 — Wait until the clipboard holds `expected`: the whole text for a string, a match for a regex.
91
+ - `count(locator) → number` — Number of matching elements.
92
+ - `textContent(locator) → string` — Text content ("" if none).
93
+ - `texts(locator) → string[]` · since 0.49.2 — textContent of every match, in DOM order; [] when nothing matches.
94
+ - `inputValue(locator) → string` — Current input value.
95
+ - `isVisible(locator) → boolean` — Whether the element is visible.
96
+ - `isChecked(locator) → boolean` · since 0.49.2 — Checked state of a checkbox/radio/switch (native or ARIA role).
97
+ - `isDisabled(locator) → boolean` — Whether the element is disabled (native :disabled incl. fieldset, or aria-disabled).
98
+ - `isEnabled(locator) → boolean` — Negation of isDisabled.
99
+ - `hasAttribute(locator, name) → boolean` — Whether the attribute is present at all — the honest probe for boolean attributes.
100
+ - `computedStyle(locator, property) → string` · since 0.47.0 — The element's computed CSS value, as the browser resolved it: computedStyle(card, "opacity") → "0.5", custom properties too ("--accent").
101
+ - `getImageSize(locator) → {width, height} | null` · since 0.49.1 — Natural size of an <img>, once it has loaded or failed (waits up to the action timeout); null when it has no pixels — broken, or no src.
102
+ - `hasAnimation(locator) → bool` · since 0.47.0 — Whether the element or a descendant has an animation still running towards an end.
103
+ - `animations(locator) → [{ name, kind, playState, currentTime?, infinite }]` · since 0.51.0 — Every animation of the element and its descendants: `name` is the @keyframes name, the transitioned property or a script animation's id; `kind` is animation, transition or script; `playState` is running, paused, finished or idle; `currentTime` in ms, left out when it has none; `infinite` for one that repeats forever.
104
+ - `randomFirstName() → string` — Random first name for fixture data.
105
+ - `randomLastName() → string` — Random last name for fixture data.
106
+ - `randomEmail() → string` — Random unique email address for fixture data.
107
+ - `randomText(length) → string` — Lorem-style prose cut to `length` characters.
108
+ - `randomWord(length?) → string` — Random lowercase letters (default 8) — digit-free unique markers.
109
+ - `json(value) → string` — Serialize any value to a JSON string — readable assert messages for API/data steps: assertTrue(res.status == 202, json(res.body)).
110
+ - `textContains(haystack, needle) → boolean` — Substring probe for strings (shell stdout, api bodies): assertTrue(textContains(out.stdout, 'ready'), out.stderr).
111
+ - `textJoin(parts) → string` — Concatenate an array of parts (numbers coerced).
112
+ - `nowMs() → number` — Current epoch milliseconds.
113
+ - `today() → string` — Local date as YYYY-MM-DD.
114
+ - `daysFromNow(n) → string` — Local date n days ahead (negative = past) as YYYY-MM-DD.
115
+ - `textMatches(text, /re/) → false | string[]` · since 0.45.0 — First match of a regex literal: false on a miss, else `[whole, group1, …]` (a group that took no part is null).
116
+ - `parseJson(text) → any` · since 0.45.0 — Parse a JSON string (an api body, a data attribute, a request's postData) into a value you walk with `.` and `[]`.
117
+ - `urlParam(url, key) → string | null` · since 0.45.0 — A query parameter of a URL, decoded; null when the key is absent, '' when it is empty.
118
+ - `toNumber(text, { decimal? }) → number` · options `{decimal?}` · since 0.47.0 — A number as a page writes it: '1 234,5', '1,234.56', '−12'.
119
+ - `round(n, digits?) → number` · since 0.47.0 — Round to `digits` decimals (0..10, default 0), half away from zero on the decimal as written: round(2.5) → 3, round(-2.5) → -3, round(1.005, 2) → 1.01.
120
+ - `formatNumber(n, { locale?, minFractionDigits?, maxFractionDigits? }) → string` · options `{locale?, minFractionDigits?, maxFractionDigits?}` · since 0.47.0 — A number as text, via Intl.NumberFormat with digit grouping.
121
+ - `env(name, fallback?) → string | fallback | null` · since 0.46.0 — An environment value the test can do without: the ambient environment, unotest/.env or .secrets, as a bare UPPER_SNAKE name reads it — but the fallback (null without one) when unset instead of failing.
122
+
123
+ ## Page state
124
+
125
+ - `getAttribute(locator, name) → string` — Attribute value ("" if missing).
126
+ - `getInnerText(locator) → string` — Rendered inner text.
127
+ - `getInputValue(locator) → string` — Input value (alias of inputValue).
128
+ - `boundingBox(locator) → {x, y, width, height} | null` · since 0.45.0 — Where the element lies in the viewport, CSS pixels; null when it is not rendered (display:none, detached).
129
+ - `getTitle() → string` — Document title of the active page.
130
+ - `getUrl() → string` — URL of the active page.
131
+ - `log(...args)` — Write a line to the runner's output AND to the run journal, under the current step — visible in the viewer's System pane after the run too.
132
+
133
+ ## Storage and cookies
134
+
135
+ - `setLocalStorage(key, value)` — Set a localStorage item.
136
+ - `getLocalStorage(key) → string` — Read a localStorage item ("" if missing).
137
+ - `setCookie(name, value, options?)` · options `{domain?, path?, expires?, httpOnly?, secure?, sameSite?}` — Set a cookie (options: path, domain, expires, httpOnly, secure, sameSite).
138
+ - `getCookie(name) → string` — Read a cookie value ("" if missing).
139
+
140
+ ## Tabs, frames, contexts, extensions
141
+
142
+ - `setPage(index, options?)` · options `{activate?}` — Switch the active tab/page by index (0-based) and bring it to front.
143
+ - `waitForPage(options?) → number` · options `{timeoutMs?}` · since 0.45.0 — Wait for a tab the scenario has not been handed yet (window.open, target=_blank, an extension), switch to it and return its index.
144
+ - `bringToFront(index?)` · since 0.45.0 — Bring a tab to front — the visible one — without changing the tab the steps act on.
145
+ - `setPageHidden(hidden, index?)` · since 0.51.0 — Emulates the tab's visibility for its scripts: true sends it to the background (document.hidden, visibilityState 'hidden', blur + visibilitychange), false brings it back.
146
+ - `newPage(url?) → number` · since 0.45.0 — Open a new tab in the active browser context, make it active and return its index.
147
+ - `closePage(index?)` · since 0.45.0 — Close a tab; no index: the active one.
148
+ - `setViewport({width, height})` · since 0.44.0 — Resize every tab of the browser, and the ones it opens later, without reloading.
149
+ - `emulateMedia({ reducedMotion?, colorScheme? })` · options `{reducedMotion?, colorScheme?}` · since 0.47.0 — Change the media features the current tab reports from now on — what matchMedia and CSS @media see: reducedMotion 'reduce' | 'no-preference', colorScheme 'light' | 'dark' | 'no-preference'.
150
+ - `newContext() → number` · since 0.44.0 — Open another browser context — a separate client with its own cookies, storage and tabs — and make it active.
151
+ - `setContext(index)` · since 0.44.0 — Make browser context `index` active.
152
+ - `enterFrame(locator)` — Scope subsequent calls to an iframe (persists until exitFrame).
153
+ - `exitFrame()` — Exit the innermost iframe scope.
154
+ - `addVirtualAuthenticator({ protocol?, transport?, hasResidentKey?, hasUserVerification?, isUserVerified?, automaticPresenceSimulation? }) → id` · options `{protocol?, transport?, hasResidentKey?, hasUserVerification?, isUserVerified?, automaticPresenceSimulation?}` · since 0.51.0 — A passkey without a person at a device: a virtual WebAuthn authenticator on the active tab answers navigator.credentials.create/get.
155
+ - `virtualCredentials(id?) → [{ credentialId, rpId, userHandle, signCount, resident }]` · since 0.51.0 — The credentials a virtual authenticator holds — one, or all of them.
156
+ - `removeVirtualAuthenticator(id)` · since 0.51.0 — Take a virtual authenticator off; its passkeys go with it.
157
+ - `grantPermissions(permissions, { origin? })` · options `{origin?}` · since 0.51.0 — Grant browser permissions to the context — ['notifications'], ['geolocation'] — for every origin or {origin}.
158
+ - `setOffline(offline)` · since 0.51.0 — setOffline(true) cuts every page of the context off the network; setOffline(false) connects it again.
159
+ - `waitForServiceWorker({ timeoutMs?, url? }) → string` · options `{timeoutMs?, url?}` · since 0.45.0 — Wait for a browser extension's service worker and return its URL (`chrome-extension://<id>/sw.js`); a running one comes back at once.
160
+ - `extensionId() → string` · since 0.45.0 — The id of the extension whose service worker runs — for `goto('chrome-extension://' + extensionId() + '/popup.html')`.
161
+ - `evaluateInServiceWorker(js, ...args) → any` · since 0.45.0 — Like evaluate, in the extension's service worker — the way to `chrome.storage`, `chrome.tabs`, `chrome.runtime`.
162
+
163
+ ## Data, files, network, processes
164
+
165
+ - `shell(cmd, ...args, options?) → { stdout, stderr, code }` — Run a binary (execFile, no shell interpretation).
166
+ - `waitForFile(path, pattern?, options?) → string` · options `{timeoutMs?}` — Poll a file (relative to config `shellCwd`) until it exists / contains a substring or regex, then return its content.
167
+ - `assertNoFile(path, pattern?, { withinMs })` · options `{withinMs?}` — Mirror of waitForFile with inverted polarity: FAIL the moment the file exists (and matches pattern); pass when the window elapsed clean.
168
+ - `waitForJsonLine(path, filter, options?) → object` · options `{timeoutMs?}` — Wait for a LINE of a JSONL file that matches every key of `filter` (strict equality, dot paths for nesting), then return it parsed.
169
+ - `assertNoJsonLine(path, filter, { withinMs })` · options `{withinMs?}` — Negative twin of waitForJsonLine: FAIL the moment a matching line appears; pass when the window elapsed clean.
170
+ - `readJsonLine(path, filter) → object` · since 0.31.0 — First matching line of a JSONL file that already exists, no wait: one read, same key filter as waitForJsonLine.
171
+ - `readJson(path) → any` · since 0.45.0 — A whole JSON file, read once and parsed: app constants a build script exported, fixture objects.
172
+ - `readFile(path, options?) → string` · options `{encoding?}` · since 0.45.0 — A whole file, read once: its text, or its bytes as base64 with {encoding: 'base64'}.
173
+ - `readFileInfo(path) → object` · since 0.45.0 — What to assert about a file without reading it: {size} in bytes, plus png: {width, height} for a PNG (from its header).
174
+ - `waitForFileCount(path, pattern, count, options?) → number` · options `{timeoutMs?}` — Wait until AT LEAST `count` lines match, then return how many there are.
175
+ - `assertFileCount(path, pattern, count)` — Snapshot count of matching lines, strict equality — 'exactly N happened'.
176
+ - `dbQuery(sql, ...params) → rows[]` — Parameterized SELECT.
177
+ - `dbExec(sql, ...params) → number` — Parameterized INSERT/UPDATE/DELETE.
178
+ - `apiCall(method, path, body?, headers?, { base?, timeoutMs? }) → { status, body, headers }` · options `{base?, timeoutMs?}` — HTTP call.
179
+ - `upload(path, options?) → UploadRef` · options `{field?, fields?}` — Multipart marker for apiCall's body (options: field, fields).
180
+ - `mockRoute(glob, response)` · since 0.45.0 — From now on, requests matching `glob` (a Playwright URL glob: `**/api/items*`) get a fixed answer: `{status?, body?, headers?, contentType?}` (an object body goes as JSON), `{abort: true, record?}` or `{continue: true}` (to the network).
181
+ - `unmockRoute(glob?)` · since 0.45.0 — Take off the mock at `glob`, or every mock when called without one.
182
+ - `waitForRequest(glob, { timeoutMs? }) → { url, method, headers, postData, postDataJson }` · options `{timeoutMs?}` · since 0.45.0 — Wait for a request matching `glob` and return it; `postDataJson` is the body read as JSON (null when it is not).
183
+ - `waitForWebSocket(glob, { timeoutMs? }) → { url }` · options `{timeoutMs?}` · since 0.51.0 — Wait until the active page has opened a WebSocket whose URL matches `glob` (a Playwright URL glob: `**/ws`, `ws://localhost:*/live`) and return its URL.
184
+ - `assertNoRequest(glob, { since? })` · options `{since?}` · since 0.45.0 — FAIL if the recording abort at `glob` — mockRoute(glob, {abort: true, record: true}) — stopped any request; with `since` (epoch ms, from nowMs()) only from then on.
185
+ - `openTerminal(app, { host? }) → number` · options `{host?}` · since 0.51.0 — Open a real terminal window — 'Terminal' (Terminal.app) or 'iTerm2' — and make it the one the terminal steps act on; returns its index for setTerminal.
186
+ - `setTerminal(index)` · since 0.51.0 — Make the terminal window `index` (from openTerminal) the one the terminal steps act on.
187
+ - `closeTerminal()` · since 0.51.0 — Close the active terminal window and stop what runs in it.
188
+ - `terminalType(text, { echo? })` · options `{echo?}` · since 0.51.0 — Put `text` into the active terminal window as a paste, line by line with Return between the lines, so the keyboard layout does not change it; the clipboard is restored after.
189
+ - `terminalPress(key)` · since 0.51.0 — Press a key in the active terminal window, with modifiers held as press() spells them: 'Enter', 'Shift+Enter', 'Control+]', 'Escape', 'ArrowUp', 'F5'; a character with a modifier is that key of a US keyboard.
190
+ - `terminalWaitForText(text, { not?, timeoutMs? })` · options `{not?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.51.0 — Wait until `text` (a substring, or a /regex/) is on the active terminal's screen; {not: true} waits for it to go.
191
+ - `terminalAssertText(text, { not?, timeoutMs? })` · options `{not?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.51.0 — FAIL unless `text` (a substring, or a /regex/) is on the active terminal's screen within the timeout (default 5000 ms); {not: true} fails while it is there.
192
+ - `terminalResize(cols, rows)` · since 0.51.0 — Resize the active terminal window to `cols` × `rows` character cells.
193
+ - `terminalScreenshot(name?) → string` · since 0.51.0 — A PNG of the active terminal window, saved with the run; returns its project-relative path.
194
+ - `mcpStart(command, args?, { env?, cwd?, timeoutMs? }) → server` · options `{env?, cwd?, timeoutMs?}` · since 0.51.0 — Start a stdio MCP server and finish its handshake; returns the handle the other mcp* functions take.
195
+ - `mcpCall(server, tool, args?, { timeoutMs?, allowError? }) → { content, structuredContent?, isError? }` · options `{timeoutMs?, allowError?}` · since 0.51.0 — Call a tool and return its result.
196
+ - `mcpWaitNotification(server, method, { match?, timeoutMs? }) → params` · options `{timeoutMs?, match?}` · since 0.51.0 — Wait for a notification of `method` and return its params.
197
+ - `mcpStop(server)` · since 0.51.0 — Stop the server.
198
+ - `vmAvailable() → bool` · since 0.51.0 — Whether VMs can run here: Tart is installed and answers.
199
+ - `vmClone(image) → name` · since 0.51.0 — A new VM from a ready image (a local Tart VM or an OCI reference); returns its name, unotest-<id>-<n>, unique to the test.
200
+ - `vmRun(name, { timeoutMs? }) → ip` · options `{timeoutMs?}` · since 0.51.0 — Boot the VM without a window and wait for its address; returns the IP.
201
+ - `vmIp(name, { timeoutMs? }) → ip` · options `{timeoutMs?}` · since 0.51.0 — The address of a running VM.
202
+ - `vmStop(name)` · since 0.51.0 — Stop the VM.
203
+ - `vmDelete(name)` · since 0.51.0 — Delete the VM, stopping it first if it runs.
204
+
205
+ ## Diagnostics
206
+
207
+ - `screenshot(name?, { fullPage? }) → string` · options `{fullPage?}` — Capture the active page into the run's artifact dir; returns the project-relative path.
208
+ - `note(label, value)` · since 0.31.0 — Attach a labelled value to the current step: shown in the viewer under the step (also after the run) and kept in the run journal.
209
+ - `consoleEntries({ level?, since? }) → [{ level, text, url }]` · options `{level?, since?}` · since 0.46.0 — What the active page wrote to its console, oldest first: `level` is log, info, warn, error or debug.
210
+ - `pageErrors({ since? }) → [{ message, stack }]` · options `{since?}` · since 0.46.0 — Errors the active page threw and nothing caught (an uncaught exception, a rejected promise), oldest first; `stack` is empty when the browser gave none.
211
+ - `assertNoConsoleErrors({ includePageErrors?, since? })` · options `{includePageErrors?, since?}` · since 0.46.0 — FAIL when the active page logged console errors, or threw uncaught ones (unless {includePageErrors: false}), quoting the first three.
212
+
213
+ ## Structure
214
+
215
+ - `step(label, () => { ... })` — Required around every executable step in a `test_*` function.
216
+ - `teardown(label, () => { ... })` — Register a rollback block: nothing runs where it stands; after the test body — passed, failed, timed out or stopped — every registered block runs, newest first, each even if another fails.
217
+ - `waitUntil(() => condition, { timeoutMs?, intervalMs?, label? }) → any` — Poll a condition no single wait covers — a counter crossing a threshold, an API answering the way the test needs.
218
+ - `assertNever(() => condition, { withinMs, intervalMs?, label? })` · since 0.51.0 — Negative window for a condition: the body (an expression, or a block that `return`s its value) is polled for the whole window; FAIL the moment it is truthy, naming the value and the time into the window; pass when the window elapsed clean.
219
+
220
+ ## Page code (last resort)
221
+
222
+ - `evaluate(js, arg?) → any` — Run raw JS in the page context.
223
+ - `evaluateOnLocator(locator, js, ...args) → any` · since 0.45.0 — Like evaluate, on the matched element: the body is called with the element, then the extra arguments by the same rule (`(el, x) => …`, two or more → `(el, [a, b]) => …`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unotest/web",
3
- "version": "0.50.0",
3
+ "version": "0.51.0",
4
4
  "description": "AI-native E2E testing for web applications. MCP server (run_test / step / resume / inspect_runtime / agent_fix) + CLI runner + JavaScript DSL scenarios on a sandboxed AST engine + semantic DOM snapshots.",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -71,6 +71,7 @@
71
71
  ".claude/skills",
72
72
  ".claude/hooks",
73
73
  "CHANGELOG.md",
74
+ "llms.txt",
74
75
  "LICENSE",
75
76
  "README.md"
76
77
  ],
@@ -85,18 +86,18 @@
85
86
  "tsx": "^4.19.2",
86
87
  "yaml": "^2.6.0",
87
88
  "zod": "^3.23.8",
88
- "@unotest/core": "^0.50.0",
89
- "@unotest/grounder-client": "^0.50.0",
90
- "@unotest/dsl": "^0.50.0",
91
- "@unotest/viewer": "^0.50.0",
92
- "@unotest/protocol": "^0.50.0"
89
+ "@unotest/core": "^0.51.0",
90
+ "@unotest/protocol": "^0.51.0",
91
+ "@unotest/grounder-client": "^0.51.0",
92
+ "@unotest/dsl": "^0.51.0",
93
+ "@unotest/viewer": "^0.51.0"
93
94
  },
94
95
  "devDependencies": {
95
96
  "@types/node": "^22.10.0",
96
97
  "javascript-obfuscator": "^4.1.1",
97
98
  "tsup": "^8.5.1",
98
99
  "typescript": "^5.7.2",
99
- "@unotest/judge": "^0.50.0",
100
- "@unotest/grounder": "^0.50.0"
100
+ "@unotest/judge": "^0.51.0",
101
+ "@unotest/grounder": "^0.51.0"
101
102
  }
102
103
  }