@unotest/web 0.52.1 → 0.53.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 CHANGED
@@ -147,7 +147,7 @@ Full reference: https://docs.unotest.com/reference/dsl/
147
147
  - `closePage(index?)` · since 0.45.0 — Close a tab; no index: the active one.
148
148
  - `setViewport({width, height})` · since 0.44.0 — Resize every tab of the browser, and the ones it opens later, without reloading.
149
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.
150
+ - `newContext({ profile?, cdpEndpoint? }) → number` · options `{profile?, cdpEndpoint?}` · since 0.44.0 — Open another browser context — a separate client with its own cookies, storage and tabs — and make it active.
151
151
  - `setContext(index)` · since 0.44.0 — Make browser context `index` active.
152
152
  - `enterFrame(locator)` — Scope subsequent calls to an iframe (persists until exitFrame).
153
153
  - `exitFrame()` — Exit the innermost iframe scope.
@@ -181,16 +181,21 @@ Full reference: https://docs.unotest.com/reference/dsl/
181
181
  - `unmockRoute(glob?)` · since 0.45.0 — Take off the mock at `glob`, or every mock when called without one.
182
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
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
+ - `networkEntries({ since?, glob? }) → [{ url, method, status, ok, failureText?, mocked?, requestJson, responseJson, responseText, truncated?, at }]` · options `{since?, glob?}` · since 0.53.0 — What the active page requested and was answered, oldest first: the status and, for `fetch` / `xhr` with a text or JSON content type, the bodies (`requestJson` as `postDataJson` of `waitForRequest`; `responseJson` is null when the body is not JSON; at most 64 KB each, then `truncated`).
184
185
  - `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.
186
+ - `openTerminal(app?, { host?, leaveOpen?, env?, cwd?, shell?, cols?, rows?, term?, locale?, cleanProfile? }) → number` · options `{host?, leaveOpen?, env?, cwd?, shell?, cols?, rows?, term?, locale?, cleanProfile?}` · since 0.51.0 — Open a terminal and make it the one the terminal steps act on; returns its index for setTerminal.
187
+ - `setTerminal(index)` · since 0.51.0 — Make the terminal `index` (from openTerminal) the one the terminal steps act on.
188
+ - `closeTerminal()` · since 0.51.0 — Close the active terminal and stop what runs in it: HUP to the processes on its tty and their children, KILL for those that ignore it; a note lists them.
189
+ - `terminalType(text, { echo? })` · options `{echo?}` · since 0.51.0 — Put `text` into the active terminal as a paste, line by line with Return between the lines, so the keyboard layout does not change it (a window's clipboard is restored after).
190
+ - `terminalClipboardWrite(text)` · since 0.53.0 — Put `text` on the active terminal's clipboard: for a window, the clipboard of its machine (this Mac, or the VM of {host}), concealed and transient; for the 'shell' terminal, its own — the answer a program gets to an OSC 52 query.
191
+ - `terminalClipboardRead() → string` · since 0.53.0 — What is on the active terminal's clipboard ('' when empty): for a window, its machine's; for the 'shell' terminal, what a program set with OSC 52.
192
+ - `terminalPress(key)` · since 0.51.0 — Press a key in the active terminal, 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.
193
+ - `terminalWaitForText(text, { not?, timeoutMs? }) → match` · 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.
194
+ - `terminalWaitForExit({ code?, timeoutMs? }) → { exitCode, signal }` · options `{code?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.53.0 — Wait until the shell of the active terminal exits and return how it ended: `exitCode`, and `signal` — its name (`SIGTERM`) when a signal ended it, else null.
191
195
  - `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.
196
+ - `terminalResize(cols, rows)` · since 0.51.0 — Resize the active terminal to `cols` × `rows` character cells.
197
+ - `terminalText() → string` · since 0.53.0 — The active terminal's screen as text, rows without their padding — what a failed test keeps as terminal.txt.
198
+ - `terminalScreenshot(name?) → string` · since 0.51.0 — A PNG of the active terminal, saved with the run — a window's own picture, or the 'shell' terminal's screen drawn by the headless browser; returns its project-relative path.
194
199
  - `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
200
  - `mcpCall(server, tool, args?, { timeoutMs?, allowError? }) → { content, structuredContent?, isError? }` · options `{timeoutMs?, allowError?}` · since 0.51.0 — Call a tool and return its result.
196
201
  - `mcpWaitNotification(server, method, { match?, timeoutMs? }) → params` · options `{timeoutMs?, match?}` · since 0.51.0 — Wait for a notification of `method` and return its params.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unotest/web",
3
- "version": "0.52.1",
3
+ "version": "0.53.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": {
@@ -78,6 +78,8 @@
78
78
  "dependencies": {
79
79
  "@faker-js/faker": "^10.5.0",
80
80
  "@modelcontextprotocol/sdk": "^1.0.4",
81
+ "@xterm/addon-unicode11": "0.10.0-beta.290",
82
+ "@xterm/headless": "6.1.0-beta.290",
81
83
  "ajv": "^8.20.0",
82
84
  "chokidar": "^4.0.3",
83
85
  "dotenv": "^16.4.5",
@@ -86,19 +88,22 @@
86
88
  "tsx": "^4.19.2",
87
89
  "yaml": "^2.6.0",
88
90
  "zod": "^3.23.8",
89
- "@unotest/core": "^0.52.1",
90
- "@unotest/viewer": "^0.52.1",
91
- "@unotest/grounder-client": "^0.52.1",
92
- "@unotest/dsl": "^0.52.1",
93
- "@unotest/protocol": "^0.52.1"
91
+ "@unotest/viewer": "^0.53.0",
92
+ "@unotest/dsl": "^0.53.0",
93
+ "@unotest/grounder-client": "^0.53.0",
94
+ "@unotest/core": "^0.53.0",
95
+ "@unotest/protocol": "^0.53.0"
96
+ },
97
+ "optionalDependencies": {
98
+ "node-pty": "1.2.0-beta.15"
94
99
  },
95
100
  "devDependencies": {
96
101
  "@types/node": "^22.10.0",
97
102
  "javascript-obfuscator": "^4.1.1",
98
103
  "tsup": "^8.5.1",
99
104
  "typescript": "^5.7.2",
100
- "@unotest/judge": "^0.52.1",
101
- "@unotest/grounder": "^0.52.1"
105
+ "@unotest/judge": "^0.53.0",
106
+ "@unotest/grounder": "^0.53.0"
102
107
  },
103
108
  "peerDependencies": {
104
109
  "typescript": ">=5.0.0 <7"
@@ -296,7 +296,9 @@ fill(getByLabel('Password'), TEST_USER_PASSWORD);
296
296
  - An UPPER_SNAKE name that isn't in either file fails the run with
297
297
  "external variable X not found — add it to unotest/.env". When you need a
298
298
  value the project hasn't defined, tell the user to add it; don't inline a
299
- literal.
299
+ literal. A name that `unotest/.env.example` declares but nothing gives a value
300
+ says so ("declared in ... but has no value here"): the user sets it, in
301
+ `unotest/.env`, the active overlay or the shell.
300
302
  - Secret values are auto-masked (`‹secret:NAME›`) in the debug log, so a
301
303
  password passed to `fill` never lands on disk verbatim.
302
304
 
@@ -346,7 +346,7 @@ declare function screenshot(name?: string, options?: { fullPage?: boolean }): st
346
346
  /**
347
347
  * note(label, value)
348
348
  *
349
- * 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. Any value — a string, a number, an object (recorded as JSON). Secrets are masked; long values are cut at 4 KB. Use it for the question a data-driven case asked and the answer it got.
349
+ * 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. Any value — a string, a number, an object (recorded as JSON). Secrets are masked; the journal keeps the first 4 KB of a long value and the whole of it goes to a file in the run directory, named in the output. Use it for the question a data-driven case asked and the answer it got.
350
350
  */
351
351
  declare function note(label: string, value: any): void;
352
352
 
@@ -442,11 +442,11 @@ declare function setViewport(size: { width?: number; height?: number } | null):
442
442
  declare function emulateMedia(media: { reducedMotion?: "reduce" | "no-preference"; colorScheme?: "light" | "dark" | "no-preference" }): void;
443
443
 
444
444
  /**
445
- * newContext() → number
445
+ * newContext({ profile?, cdpEndpoint? }) → number
446
446
  *
447
- * Open another browser context — a separate client with its own cookies, storage and tabs — and make it active. Returns its number (the run's own is 0).
447
+ * Open another browser context — a separate client with its own cookies, storage and tabs — and make it active. Returns its number (the run's own is 0). With `profile: '<dir>'` the context runs on a browser profile of its own in that directory (a relative one starts at the project root; made if missing, kept after the run): two devices side by side, each keeping what it stored. The same directory twice in a run is refused. With `cdpEndpoint: 'http://<ip>:9222'` the context opens in a Chrome somebody else started with remote debugging (a VM's browser: `vmRun` gives the address) and the test only disconnects at the end; it cannot be combined with `profile`.
448
448
  */
449
- declare function newContext(): number;
449
+ declare function newContext(options?: { profile?: string; cdpEndpoint?: string }): number;
450
450
 
451
451
  /**
452
452
  * setContext(index)
@@ -1113,6 +1113,13 @@ declare function waitForRequest(glob: string, options?: { timeoutMs?: number }):
1113
1113
  */
1114
1114
  declare function waitForWebSocket(glob: string, options?: { timeoutMs?: number }): any;
1115
1115
 
1116
+ /**
1117
+ * networkEntries({ since?, glob? }) → [{ url, method, status, ok, failureText?, mocked?, requestJson, responseJson, responseText, truncated?, at }]
1118
+ *
1119
+ * What the active page requested and was answered, oldest first: the status and, for `fetch` / `xhr` with a text or JSON content type, the bodies (`requestJson` as `postDataJson` of `waitForRequest`; `responseJson` is null when the body is not JSON; at most 64 KB each, then `truncated`). Other resources have a status only; a request that failed has status 0 and `failureText`. Recorded from the moment the page opened, but a response is entered when it finishes, so wait for it. options: {since} (epoch ms of sending, from nowMs()), {glob} (a mask; one starting with `/` is read on the site's origin).
1120
+ */
1121
+ declare function networkEntries(options?: { since?: number; glob?: any }): any;
1122
+
1116
1123
  /**
1117
1124
  * assertNoRequest(glob, { since? })
1118
1125
  *
@@ -1121,65 +1128,93 @@ declare function waitForWebSocket(glob: string, options?: { timeoutMs?: number }
1121
1128
  declare function assertNoRequest(glob: string, options?: { since?: number }): void;
1122
1129
 
1123
1130
  /**
1124
- * openTerminal(app, { host? }) → number
1131
+ * openTerminal(app?, { host?, leaveOpen?, env?, cwd?, shell?, cols?, rows?, term?, locale?, cleanProfile? }) → number
1125
1132
  *
1126
- * 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. On this Mac by default (it takes the keyboard while the test types); {host: 'user@address'} opens it on another Mac over ssh, a Tart VM, whose logged-in session runs it — the key comes from your ssh agent or ~/.ssh. Every window closes when the test ends.
1133
+ * Open a terminal and make it the one the terminal steps act on; returns its index for setTerminal. No app, or 'shell': your shell on a pty of this machine read through a terminal emulator — headless, so it runs on Linux, in CI and in a container (needs the optional node-pty; without it the step names the install command). 'Terminal' (Terminal.app) or 'iTerm2': a real macOS window, on this Mac by default (it takes the keyboard while the test types); {host: 'user@address'} opens it on another Mac over ssh, a Tart VM, whose logged-in session runs it — the key comes from your ssh agent or ~/.ssh. Every terminal closes when the test ends: the processes on its tty get HUP, then KILL if they ignore it, and a note lists what was stopped; a process nothing stops fails the test's end. {leaveOpen: true} leaves the terminal and its processes running, to look at afterwards. The shell terminal also takes {env, cwd, shell, cols, rows, term, locale, cleanProfile} — how its shell starts (cleanProfile: no rc files, a fixed `$ ` prompt, a minimal environment); a GUI window refuses them. openTerminal('ssh', {host: 'user@address'}) opens a session over ssh -tt on a Linux host with no GUI: a [Y/n] or a password prompt of the host reaches the steps; a password is never passed (key from the ssh agent or ~/.ssh).
1127
1134
  */
1128
- declare function openTerminal(app: string, options?: { host?: any }): number;
1135
+ declare function openTerminal(app?: string, options?: { host?: any; leaveOpen?: boolean; env?: any; cwd?: string; shell?: string; cols?: number; rows?: number; term?: string; locale?: string; cleanProfile?: boolean }): number;
1129
1136
 
1130
1137
  /**
1131
1138
  * setTerminal(index)
1132
1139
  *
1133
- * Make the terminal window `index` (from openTerminal) the one the terminal steps act on.
1140
+ * Make the terminal `index` (from openTerminal) the one the terminal steps act on.
1134
1141
  */
1135
1142
  declare function setTerminal(index: number): void;
1136
1143
 
1137
1144
  /**
1138
1145
  * closeTerminal()
1139
1146
  *
1140
- * Close the active terminal window and stop what runs in it. Windows left open close when the test ends anyway.
1147
+ * Close the active terminal and stop what runs in it: HUP to the processes on its tty and their children, KILL for those that ignore it; a note lists them. Terminals left open close when the test ends anyway.
1141
1148
  */
1142
1149
  declare function closeTerminal(): void;
1143
1150
 
1144
1151
  /**
1145
1152
  * terminalType(text, { echo? })
1146
1153
  *
1147
- * 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. Each line must show on the screen within 2 s, or the step fails quoting the screen's last rows; {echo: false} skips that wait for input a program does not echo (a password). Nothing is sent when another window took the focus — the step fails instead.
1154
+ * Put `text` into the active terminal as a paste, line by line with Return between the lines, so the keyboard layout does not change it (a window's clipboard is restored after). Each line must show on the screen within 2 s, or the step fails quoting the screen's last rows; {echo: false} skips that wait for input a program does not echo (a password). A window gets nothing when another one took the focus — the step fails instead.
1148
1155
  */
1149
1156
  declare function terminalType(text: string, options?: { echo?: boolean }): void;
1150
1157
 
1158
+ /**
1159
+ * terminalClipboardWrite(text)
1160
+ *
1161
+ * Put `text` on the active terminal's clipboard: for a window, the clipboard of its machine (this Mac, or the VM of {host}), concealed and transient; for the 'shell' terminal, its own — the answer a program gets to an OSC 52 query. The text is passed as an argument, never logged or quoted in an error.
1162
+ */
1163
+ declare function terminalClipboardWrite(text: string): void;
1164
+
1165
+ /**
1166
+ * terminalClipboardRead() → string
1167
+ *
1168
+ * What is on the active terminal's clipboard ('' when empty): for a window, its machine's; for the 'shell' terminal, what a program set with OSC 52. A value the shell copied, such as a token, goes into the test.
1169
+ */
1170
+ declare function terminalClipboardRead(): string;
1171
+
1151
1172
  /**
1152
1173
  * terminalPress(key)
1153
1174
  *
1154
- * 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. A single character alone is pasted as terminalType does, without the echo wait. A real key event — the terminal encodes it itself (iTerm2 under the kitty keyboard protocol sends Shift+Enter as CSI 13;2 u).
1175
+ * Press a key in the active terminal, 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. A single character alone is pasted as terminalType does, without the echo wait. In a window, a real key event — the app encodes it itself (iTerm2 under the kitty keyboard protocol sends Shift+Enter as CSI 13;2 u); in the 'shell' terminal, the bytes an xterm sends (arrows follow the program's cursor mode, Alt is ESC before the key, Meta is refused).
1155
1176
  */
1156
1177
  declare function terminalPress(key: string): void;
1157
1178
 
1158
1179
  /**
1159
- * terminalWaitForText(text, { not?, timeoutMs? })
1180
+ * terminalWaitForText(text, { not?, timeoutMs? }) → match
1181
+ *
1182
+ * Wait until `text` (a substring, or a /regex/) is on the active terminal's screen; {not: true} waits for it to go. Default timeout 30 s. Returns what it saw: a regex gives the match array (`[0]` the match, then the groups), a string the first screen row that holds it, {not: true} null. On a timeout the error quotes the last 10 non-empty rows of the screen, secrets masked; a failed test keeps the terminal's last frame and the whole screen text (terminal.png, terminal.txt).
1183
+ */
1184
+ declare function terminalWaitForText(text: string | RegExp, options?: { timeout?: number; not?: boolean; timeoutMs?: number }): any;
1185
+
1186
+ /**
1187
+ * terminalWaitForExit({ code?, timeoutMs? }) → { exitCode, signal }
1160
1188
  *
1161
- * Wait until `text` (a substring, or a /regex/) is on the active terminal's screen; {not: true} waits for it to go. Default timeout 30 s. A failed test keeps the window's last frame and screen text (terminal.png, terminal.txt).
1189
+ * Wait until the shell of the active terminal exits and return how it ended: `exitCode`, and `signal` — its name (`SIGTERM`) when a signal ended it, else null. End the command with `exit $?`, or start the program with `exec`. With `code`, any other exit code fails and the error quotes the end of the screen. Default timeout 30 s. Only the shell terminal can report it: a Terminal / iTerm2 window cannot. After the exit, typing and pressing keys are refused; the last screen is still there.
1162
1190
  */
1163
- declare function terminalWaitForText(text: string | RegExp, options?: { timeout?: number; not?: boolean; timeoutMs?: number }): void;
1191
+ declare function terminalWaitForExit(options?: { timeout?: number; code?: number; timeoutMs?: number }): any;
1164
1192
 
1165
1193
  /**
1166
1194
  * terminalAssertText(text, { not?, timeoutMs? })
1167
1195
  *
1168
- * 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.
1196
+ * 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. The error quotes the last 10 non-empty rows of the screen, secrets masked.
1169
1197
  */
1170
1198
  declare function terminalAssertText(text: string | RegExp, options?: { timeout?: number; not?: boolean; timeoutMs?: number }): void;
1171
1199
 
1172
1200
  /**
1173
1201
  * terminalResize(cols, rows)
1174
1202
  *
1175
- * Resize the active terminal window to `cols` × `rows` character cells.
1203
+ * Resize the active terminal to `cols` × `rows` character cells.
1176
1204
  */
1177
1205
  declare function terminalResize(cols: number, rows: number): void;
1178
1206
 
1207
+ /**
1208
+ * terminalText() → string
1209
+ *
1210
+ * The active terminal's screen as text, rows without their padding — what a failed test keeps as terminal.txt.
1211
+ */
1212
+ declare function terminalText(): string;
1213
+
1179
1214
  /**
1180
1215
  * terminalScreenshot(name?) → string
1181
1216
  *
1182
- * A PNG of the active terminal window, saved with the run; returns its project-relative path.
1217
+ * A PNG of the active terminal, saved with the run — a window's own picture, or the 'shell' terminal's screen drawn by the headless browser; returns its project-relative path. A registered secret on the screen saves the masked screen text (.txt) instead.
1183
1218
  */
1184
1219
  declare function terminalScreenshot(name?: string): string;
1185
1220