@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/CHANGELOG.md +168 -3
- package/README.md +5 -3
- package/dist/config/schema.d.ts +11 -11
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +7 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +333 -92
- 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 +11 -3
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +5 -2
- package/dist/inspection/page-inject.js +11 -0
- package/dist/{interfaces-BSGmF_Tv.d.ts → interfaces-BU-PQbt4.d.ts} +48 -2
- package/dist/{linter-CYRlmOLy.d.ts → linter-BpaIstU3.d.ts} +11 -1
- 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/guides/agent-integration.md +1 -1
- package/guides/dsl-reference.md +485 -40
- package/llms.txt +14 -9
- package/package.json +13 -8
- package/src/mcp/prompts/agent-test-author.md +3 -1
- package/types/unotest-dsl.d.ts +52 -17
package/guides/dsl-reference.md
CHANGED
|
@@ -180,7 +180,7 @@ Two squiggle sources remain that typings cannot fix, both cosmetic:
|
|
|
180
180
|
- [Sandbox primitives](#sandbox-primitives) — shell / db / HTTP / files
|
|
181
181
|
- [MCP client](#mcp-client) — start an MCP server, call it, wait for it
|
|
182
182
|
- [Network mocks](#network-mocks) — what the page's requests get
|
|
183
|
-
- [Terminal
|
|
183
|
+
- [Terminal](#terminal) — a headless shell on a pty, or a real Terminal.app / iTerm2 window
|
|
184
184
|
- [Typed getters](#typed-getters) — page properties
|
|
185
185
|
- [Generators](#generators) — random fixture data + time
|
|
186
186
|
- [`evaluate`](#evaluate) — escape hatch into the page
|
|
@@ -838,6 +838,13 @@ page's time frozen if you froze it. By default it is the viewport;
|
|
|
838
838
|
have at most 25 megapixels — a larger baseline or snapshot is refused
|
|
839
839
|
before it is read.
|
|
840
840
|
|
|
841
|
+
**WebKit and `backdrop-filter`.** Playwright's WebKit does not draw
|
|
842
|
+
`backdrop-filter` (blurred panels, frosted headers), although it reports
|
|
843
|
+
the property as supported: a snapshot has the area sharp, and a baseline
|
|
844
|
+
taken in Chromium will not match it. Compare such designs in Chromium. On
|
|
845
|
+
WebKit, when the page has an element with a backdrop filter, the run says
|
|
846
|
+
so in one warning line, once.
|
|
847
|
+
|
|
841
848
|
**The baseline** lives next to the scenario:
|
|
842
849
|
`unotest/e2e/<scenario path without .js>.screenshots/<name>.png` (the
|
|
843
850
|
name is lower-cased and dashed, as for `screenshot()`), and travels with
|
|
@@ -1370,7 +1377,7 @@ assertUrl('/report');
|
|
|
1370
1377
|
setPage(0);
|
|
1371
1378
|
```
|
|
1372
1379
|
|
|
1373
|
-
### `newContext()` → `number` / `setContext(index)`
|
|
1380
|
+
### `newContext({profile?, cdpEndpoint?})` → `number` / `setContext(index)`
|
|
1374
1381
|
|
|
1375
1382
|
A second browser context: another client of the same app, with its own
|
|
1376
1383
|
cookies, localStorage, sessionStorage and tabs. For anything that takes
|
|
@@ -1433,7 +1440,8 @@ own.
|
|
|
1433
1440
|
capture Playwright traces or video today.
|
|
1434
1441
|
- **Browser profile:** with `launch.userDataDir` every page shares one
|
|
1435
1442
|
context, and with `launch.profile: 'per-test'` the test is one browser,
|
|
1436
|
-
so `newContext()` is refused in both.
|
|
1443
|
+
so a plain `newContext()` is refused in both. `newContext({profile})`
|
|
1444
|
+
(below) works in both.
|
|
1437
1445
|
- **Debugging:** an agent that joins a paused run (`take_wheel`,
|
|
1438
1446
|
`attach_debug_session`) lands in the context the run is on (Chromium).
|
|
1439
1447
|
- **Names:** a function or variable of your own called `newContext` /
|
|
@@ -1441,6 +1449,78 @@ own.
|
|
|
1441
1449
|
— your function wins a call by that name, so the DSL's is out of reach
|
|
1442
1450
|
until you rename it.
|
|
1443
1451
|
|
|
1452
|
+
#### Two devices: `newContext({profile: '<dir>'})`
|
|
1453
|
+
|
|
1454
|
+
`{profile: '<dir>'}` opens the context on a persistent browser profile of
|
|
1455
|
+
its own in `<dir>`: its cookies and storage live in that directory, apart
|
|
1456
|
+
from every other context, and stay there after the test. That is how two
|
|
1457
|
+
devices of one app run at the same time in one test, each on a profile of
|
|
1458
|
+
its own, without a second `e2e` process (the run queue lets only one run
|
|
1459
|
+
at a time).
|
|
1460
|
+
|
|
1461
|
+
```js
|
|
1462
|
+
function test_two_devices() {
|
|
1463
|
+
let a;
|
|
1464
|
+
step("Device A opens the pairing page", () => {
|
|
1465
|
+
a = newContext({profile: '.profiles/device-a'});
|
|
1466
|
+
goto('/pair');
|
|
1467
|
+
});
|
|
1468
|
+
step("Device B opens it too", () => {
|
|
1469
|
+
newContext({profile: '.profiles/device-b'});
|
|
1470
|
+
goto('/pair');
|
|
1471
|
+
});
|
|
1472
|
+
step("Back to A, which kept what it stored", () => {
|
|
1473
|
+
setContext(a);
|
|
1474
|
+
});
|
|
1475
|
+
}
|
|
1476
|
+
```
|
|
1477
|
+
|
|
1478
|
+
- **The directory:** a relative one starts at the project root (the
|
|
1479
|
+
folder that holds `unotest/`), as `launch.userDataDir` does; it is made
|
|
1480
|
+
if it does not exist and never removed — it is yours. Keep it out of
|
|
1481
|
+
version control.
|
|
1482
|
+
- **Once per run:** the same directory twice — or the run's own profile —
|
|
1483
|
+
is refused (`ProfileInUseError`), naming the directory and who holds it.
|
|
1484
|
+
- **Same rules as any context:** the ceiling, closing at the end of the
|
|
1485
|
+
test in any outcome, `setContext`, the journal's `contextIndex`.
|
|
1486
|
+
- **Not in an explore session:** over MCP, `newContext({profile})` is
|
|
1487
|
+
refused — profiles open in an `e2e` run.
|
|
1488
|
+
|
|
1489
|
+
#### A browser somebody else runs: `newContext({cdpEndpoint})`
|
|
1490
|
+
|
|
1491
|
+
`{cdpEndpoint: 'http://<ip>:9222'}` (or a `ws://` URL) opens the context in
|
|
1492
|
+
a Chrome that is already running with remote debugging — the browser inside
|
|
1493
|
+
a VM, say — and every locator, assertion and `setContext` then drives it.
|
|
1494
|
+
Your own browser stays context 0.
|
|
1495
|
+
|
|
1496
|
+
```js
|
|
1497
|
+
function test_vm_browser() {
|
|
1498
|
+
let vmBrowser;
|
|
1499
|
+
step("Start the VM and join its browser", () => {
|
|
1500
|
+
const vm = vmClone('macos-base');
|
|
1501
|
+
const ip = vmRun(vm);
|
|
1502
|
+
vmBrowser = newContext({cdpEndpoint: `http://${ip}:9222`});
|
|
1503
|
+
goto('https://app.example.com');
|
|
1504
|
+
});
|
|
1505
|
+
step("Back to the host's browser", () => {
|
|
1506
|
+
setContext(0);
|
|
1507
|
+
});
|
|
1508
|
+
}
|
|
1509
|
+
```
|
|
1510
|
+
|
|
1511
|
+
- **Reachable from this machine:** the endpoint must be reachable from the
|
|
1512
|
+
host (a tunnel to the VM is fine), and Chrome must run with
|
|
1513
|
+
`--remote-debugging-port` and a `--user-data-dir` of its own — Chrome
|
|
1514
|
+
refuses the port on its default profile.
|
|
1515
|
+
- **Unreachable:** the call fails within 10 s with one line naming the
|
|
1516
|
+
endpoint.
|
|
1517
|
+
- **The end of the test only disconnects:** the browser is not yours to
|
|
1518
|
+
close. The contexts you opened in it are closed; the browser and its
|
|
1519
|
+
other windows stay.
|
|
1520
|
+
- **Not with `profile`:** the two are refused together.
|
|
1521
|
+
- **Not in an explore session:** over MCP, `newContext({cdpEndpoint})` is
|
|
1522
|
+
refused — a remote browser joins in an `e2e` run.
|
|
1523
|
+
|
|
1444
1524
|
Over MCP, record it with `explore_step {action: "newContext"}` and
|
|
1445
1525
|
`{action: "setContext", index}`; they become the same two calls in the
|
|
1446
1526
|
saved test. The `new_context` tool is different: it resets the browser.
|
|
@@ -2335,6 +2415,22 @@ for your image: the VM the step reached is a clone the run deletes, so
|
|
|
2335
2415
|
the key goes into the image. `ssh-copy-id` asks for the image's password
|
|
2336
2416
|
(`admin` on Tart's images).
|
|
2337
2417
|
|
|
2418
|
+
The rest of what a scenario uses goes into the image the same way, once,
|
|
2419
|
+
not per run: the apps it drives (iTerm2, a browser, the CLI under test),
|
|
2420
|
+
and the macOS permissions a terminal window needs there — Accessibility
|
|
2421
|
+
and Screen Recording for Terminal, and Automation from Terminal to System
|
|
2422
|
+
Events and to iTerm2 when the test opens one. Granted in the image, they
|
|
2423
|
+
hold in every clone; missing, the first run waits on a permission dialog
|
|
2424
|
+
in the VM. To drive Chrome in the VM from the host, start it there with a
|
|
2425
|
+
profile of its own — `--remote-debugging-port=9222
|
|
2426
|
+
--user-data-dir=<dir>`, since Chrome opens no debugging port on its
|
|
2427
|
+
default profile — and forward that port to the VM's address (Chrome
|
|
2428
|
+
listens on `127.0.0.1` only), for example with `socat
|
|
2429
|
+
TCP-LISTEN:9223,fork TCP:127.0.0.1:9222`; then
|
|
2430
|
+
`newContext({cdpEndpoint: 'http://' + ip + ':9223'})`. A credential the
|
|
2431
|
+
CLI needs is not part of the image: type it at run time from `env(…)`
|
|
2432
|
+
with `terminalType(value, {echo: false})`.
|
|
2433
|
+
|
|
2338
2434
|
```js
|
|
2339
2435
|
function test_install_on_clean_mac() {
|
|
2340
2436
|
skip('no tart on this host', !vmAvailable());
|
|
@@ -2504,23 +2600,32 @@ assertNoRequest('**/*');
|
|
|
2504
2600
|
|
|
2505
2601
|
---
|
|
2506
2602
|
|
|
2507
|
-
## Terminal
|
|
2603
|
+
## Terminal
|
|
2508
2604
|
|
|
2509
|
-
A
|
|
2510
|
-
|
|
2511
|
-
|
|
2512
|
-
|
|
2513
|
-
(
|
|
2514
|
-
|
|
2605
|
+
A terminal a test drives like a user: keys in, the screen read as text,
|
|
2606
|
+
framed as a picture. For a CLI or a TUI (an agent in a terminal, an
|
|
2607
|
+
installer, a `--watch` mode). Two kinds, the same steps:
|
|
2608
|
+
|
|
2609
|
+
- **`openTerminal()`** — the `shell` terminal: your shell on a
|
|
2610
|
+
pseudo-terminal of this machine, its output run through a terminal
|
|
2611
|
+
emulator (xterm), so cursor moves, colours, the alternate screen and
|
|
2612
|
+
wide characters land on the screen as they would in a window. No app
|
|
2613
|
+
opens, nothing takes the keyboard or the screen: it runs on Linux, in
|
|
2614
|
+
CI and in a container as on a Mac.
|
|
2615
|
+
- **`openTerminal('Terminal')`, `openTerminal('iTerm2')`** — a real window
|
|
2616
|
+
on macOS, driven by real key events. The bugs only a terminal app
|
|
2617
|
+
shows live here: a key the app encodes itself (Shift+Enter under the
|
|
2618
|
+
kitty keyboard protocol), the window's own width, the `PATH` of the
|
|
2619
|
+
login shell the user actually has.
|
|
2515
2620
|
|
|
2516
2621
|
The verbs are the page's ones with a `terminal` prefix:
|
|
2517
2622
|
`terminalType`, `terminalPress`, `terminalWaitForText`,
|
|
2518
|
-
`terminalAssertText`, `terminalScreenshot`. The bare names act on the
|
|
2623
|
+
`terminalAssertText`, `terminalText`, `terminalScreenshot`. The bare names act on the
|
|
2519
2624
|
page, and a test can drive both.
|
|
2520
2625
|
|
|
2521
2626
|
```js
|
|
2522
|
-
step("The CLI answers in a
|
|
2523
|
-
openTerminal(
|
|
2627
|
+
step("The CLI answers in a terminal", () => {
|
|
2628
|
+
openTerminal();
|
|
2524
2629
|
terminalResize(100, 30);
|
|
2525
2630
|
terminalType('my-cli --version');
|
|
2526
2631
|
terminalPress('Enter');
|
|
@@ -2533,16 +2638,52 @@ of the terminal per step: frames are taken by `terminalScreenshot()`
|
|
|
2533
2638
|
and on failure. A failed test
|
|
2534
2639
|
keeps the active window in the failure bundle: `terminal.png` (its last
|
|
2535
2640
|
frame), `terminal.txt` (its screen text, secrets redacted) and
|
|
2536
|
-
`terminal.json` (which
|
|
2537
|
-
|
|
2538
|
-
**
|
|
2641
|
+
`terminal.json` (which terminal, on which host).
|
|
2642
|
+
|
|
2643
|
+
**Secrets on the screen.** A picture cannot be redacted, so a frame of a
|
|
2644
|
+
screen that shows a secret registered in `unotest/.secrets` is never
|
|
2645
|
+
saved as one. `terminalScreenshot()` saves the screen text instead, the
|
|
2646
|
+
secret replaced by `‹secret:NAME›`, and the viewer shows it as text; the
|
|
2647
|
+
failure bundle keeps no `terminal.png` and says why in
|
|
2648
|
+
`terminal-frame-error.txt`. A value the terminal wrapped onto the next
|
|
2649
|
+
row is still found and masked. Only registered values count: a token
|
|
2650
|
+
that merely looks like one is not known to be secret, and is shown —
|
|
2651
|
+
register every credential a terminal test may print.
|
|
2652
|
+
|
|
2653
|
+
**Where it runs.**
|
|
2654
|
+
|
|
2655
|
+
- **`shell`** — macOS, Linux (glibc, x64 and arm64) and Windows hosts
|
|
2656
|
+
that `node-pty` has a prebuilt binary for, the Playwright Docker image
|
|
2657
|
+
included. `node-pty` is an optional dependency of `@unotest/web` and is
|
|
2658
|
+
loaded only when a test opens a `shell` terminal; where it did not
|
|
2659
|
+
install, that step fails with the command that installs it
|
|
2660
|
+
(`npm install --save-dev node-pty@<version>`), and every other test
|
|
2661
|
+
runs as before. Its frames are drawn by the headless Chromium the
|
|
2662
|
+
runner uses for pages (the suite's `channel` if one is set), so
|
|
2663
|
+
`terminalScreenshot()` needs a browser installed:
|
|
2664
|
+
`npx @unotest/web install-chromium`.
|
|
2665
|
+
- **`Terminal`, `iTerm2`** — macOS, through `osascript` and
|
|
2666
|
+
`screencapture`.
|
|
2667
|
+
|
|
2668
|
+
The rest of this part is about the windows.
|
|
2539
2669
|
|
|
2540
2670
|
- On this Mac, the default. macOS asks once to let the app the run starts
|
|
2541
2671
|
from (Terminal, iTerm2, your editor) control the computer and record
|
|
2542
2672
|
the screen. While the test types, **it has the keyboard**: keys go to
|
|
2543
2673
|
the terminal window only while it is in front, and a step fails rather
|
|
2544
2674
|
than type into a window that took the focus. Leave the machine alone,
|
|
2545
|
-
or run it in a VM.
|
|
2675
|
+
or run it in a VM. Two permissions, both given to the app the run
|
|
2676
|
+
starts from:
|
|
2677
|
+
- **Accessibility** (System Events): keys, and the second way to bring
|
|
2678
|
+
the window to the front. macOS may refuse a plain `activate` to a
|
|
2679
|
+
process that is not your current app, so after one second the run
|
|
2680
|
+
asks System Events to put the terminal in front; if neither works in
|
|
2681
|
+
2 s, the step fails naming the app that kept the focus (a
|
|
2682
|
+
full-screen app or a dialog).
|
|
2683
|
+
- **Screen Recording**: only the frames, `terminalScreenshot()` and the
|
|
2684
|
+
`terminal.png` of a failure. Without it the error names the app to
|
|
2685
|
+
allow under System Settings → Privacy & Security → Screen & System
|
|
2686
|
+
Audio Recording; the other terminal steps work.
|
|
2546
2687
|
- On another Mac, a Tart VM: `openTerminal('Terminal', {host:
|
|
2547
2688
|
'admin@192.168.64.38'})`. The run reaches it over ssh with your key
|
|
2548
2689
|
(ssh agent or `~/.ssh`; a password is never passed) and drives the
|
|
@@ -2551,17 +2692,69 @@ frame), `terminal.txt` (its screen text, secrets redacted) and
|
|
|
2551
2692
|
A VM just booted by `vmRun` answers ssh before its automatic login
|
|
2552
2693
|
is done: the run waits up to 90 s for that session, and an image that
|
|
2553
2694
|
logs no one in fails the step saying so.
|
|
2695
|
+
A step the controller does not answer in time fails and is withdrawn —
|
|
2696
|
+
it does not run later. "Busy with `<program>` for N s" means
|
|
2697
|
+
Terminal in the VM is held, most often by a dialog or a sheet some
|
|
2698
|
+
other `osascript` left open: close it, or restart the VM. "Not
|
|
2699
|
+
running (pid N gone)" means the controller died; the next step starts
|
|
2700
|
+
it again, and a step that was still waiting is sent once more, while
|
|
2701
|
+
one that may have run (typing) is not repeated. A program that runs
|
|
2702
|
+
past its step's time is killed in the VM.
|
|
2554
2703
|
A clean Tart macOS image needs no extra permission for Terminal.app,
|
|
2555
2704
|
but it needs your key once: see
|
|
2556
2705
|
[Preparing the image](#virtual-machines).
|
|
2557
|
-
-
|
|
2558
|
-
|
|
2559
|
-
|
|
2560
|
-
|
|
2561
|
-
|
|
2562
|
-
|
|
2563
|
-
|
|
2564
|
-
|
|
2706
|
+
- On Linux, in CI or a container: the `shell` terminal.
|
|
2707
|
+
- On a Linux host with no GUI (a VM, a server): `openTerminal('ssh', {host:
|
|
2708
|
+
'admin@10.0.0.5'})`. The run starts `ssh -tt -o BatchMode=yes` on a
|
|
2709
|
+
terminal of its own, so a `[Y/n]`, a device code or a password prompt of
|
|
2710
|
+
the host reaches the steps as it reaches a person. The key comes from
|
|
2711
|
+
your ssh agent or `~/.ssh` and a password is never passed: a login that
|
|
2712
|
+
fails shows on the screen and in the first wait's error. `{host}` is
|
|
2713
|
+
required. `cols`, `rows` and `term` set the window; `env`, `cwd`,
|
|
2714
|
+
`shell`, `locale` and `cleanProfile` set up a shell on this machine and
|
|
2715
|
+
are refused — type the command there: `terminalType('cd /srv && …')`.
|
|
2716
|
+
Closing the terminal stops the local `ssh`; the host's shell gets HUP
|
|
2717
|
+
from sshd.
|
|
2718
|
+
|
|
2719
|
+
### `openTerminal(app?, options?)` → `number`
|
|
2720
|
+
|
|
2721
|
+
Opens a terminal, makes it active, returns its index. Without `app`, or
|
|
2722
|
+
with `'shell'`: your shell (`$SHELL`; `/bin/bash` or `/bin/sh` where it
|
|
2723
|
+
is not set) on a pty of this machine, 80 × 24 cells, `TERM=xterm-256color`,
|
|
2724
|
+
in the project directory. With `'Terminal'` or `'iTerm2'`: a window of
|
|
2725
|
+
that app with a login shell. Options: `{host: 'user@address'}` — the Mac
|
|
2726
|
+
to open a window on (a GUI app only; the `shell` terminal refuses it);
|
|
2727
|
+
`{leaveOpen: true}` — keep the terminal and what runs in it after the
|
|
2728
|
+
test, to look at it by hand.
|
|
2729
|
+
|
|
2730
|
+
The shell terminal (`openTerminal()`, or `'shell'`) also takes the keys
|
|
2731
|
+
that set up how its shell starts. A GUI window takes none of them and
|
|
2732
|
+
refuses them by name — it opens the user's login shell, and is resized with
|
|
2733
|
+
`terminalResize`.
|
|
2734
|
+
|
|
2735
|
+
| Key | Meaning |
|
|
2736
|
+
| --- | --- |
|
|
2737
|
+
| `env` | `{NAME: 'value'}`, strings only, over the base environment. Values are never printed in an error or a note; one that is a registered secret is masked on the screen as everywhere. |
|
|
2738
|
+
| `cwd` | Start directory, relative to the project root; it must exist. |
|
|
2739
|
+
| `shell` | A path, or a name found on `PATH`; it must exist. Default: your `$SHELL` (bash, then sh, where none is set); with `cleanProfile`, bash (sh where there is no bash). |
|
|
2740
|
+
| `cols`, `rows` | Whole numbers above 0; default 80 × 24. |
|
|
2741
|
+
| `term` | `TERM` and the pty's terminal type; default `xterm-256color`. |
|
|
2742
|
+
| `locale` | Sets `LANG` and `LC_ALL`. |
|
|
2743
|
+
| `cleanProfile` | `true`: the shell reads none of your rc files, gets only `PATH`, `HOME`, `USER` and `TMPDIR` of the runner's environment (plus `TERM`, the locale and `env`), and its prompt is `$ `, the same on every machine. Started as `bash --noprofile --norc`, `zsh -f`, `fish --no-config`, or `sh` / `dash` with no `ENV`; any other shell is refused. `fish` keeps its own prompt. |
|
|
2744
|
+
|
|
2745
|
+
```js
|
|
2746
|
+
openTerminal('shell', {cleanProfile: true, cwd: 'unotest', env: {GREETING: 'hi'}, cols: 100, rows: 30});
|
|
2747
|
+
terminalType('echo $GREETING $COLUMNS');
|
|
2748
|
+
```
|
|
2749
|
+
|
|
2750
|
+
Every other terminal the test opened closes when it ends, green or red.
|
|
2751
|
+
The processes on its tty and everything they started get HUP; those that
|
|
2752
|
+
ignore it (a `trap '' HUP`, a program with its own handler) get KILL two
|
|
2753
|
+
seconds later. The step's record notes the result — `closed window 0 on
|
|
2754
|
+
admin@192.168.64.38; stopped 4312 sh -c … (HUP), 4320 unopipe host
|
|
2755
|
+
install (KILL)` — and a process that outlived KILL fails the test's end,
|
|
2756
|
+
naming its pid and command. `closeTerminal()` does the same and notes it
|
|
2757
|
+
the same way.
|
|
2565
2758
|
|
|
2566
2759
|
### `setTerminal(index)` / `closeTerminal()`
|
|
2567
2760
|
|
|
@@ -2571,12 +2764,13 @@ does for browser contexts; indices stay put when a window closes.
|
|
|
2571
2764
|
|
|
2572
2765
|
### `terminalType(text)` / `terminalPress(key)`
|
|
2573
2766
|
|
|
2574
|
-
`terminalType` puts the text in as a paste, line by line
|
|
2575
|
-
|
|
2576
|
-
|
|
2577
|
-
|
|
2578
|
-
|
|
2579
|
-
|
|
2767
|
+
`terminalType` puts the text in as a paste, line by line, and a line
|
|
2768
|
+
break presses Return. A program in the terminal sees a paste, not
|
|
2769
|
+
typing: a TUI that turned bracketed paste on gets the text as one paste.
|
|
2770
|
+
In a window, a line goes on the clipboard, then ⌘V: the Mac's keyboard
|
|
2771
|
+
layout does not change what arrives — Cyrillic and emoji included — and
|
|
2772
|
+
the clipboard holds what you copied again when the step ends. In the
|
|
2773
|
+
`shell` terminal the text goes down the pty as it is.
|
|
2580
2774
|
|
|
2581
2775
|
Each line must show on the screen within 2 s, or the step fails and its
|
|
2582
2776
|
message ends with the screen's last rows — what arrived instead. Input a
|
|
@@ -2599,20 +2793,219 @@ does it, without the wait for the echo: a shell prompt (`y/n`) takes it
|
|
|
2599
2793
|
as the key, while a TUI with bracketed paste on (vim in normal mode)
|
|
2600
2794
|
sees a paste.
|
|
2601
2795
|
|
|
2796
|
+
In the `shell` terminal a key goes as an xterm sends it: the arrows
|
|
2797
|
+
follow the mode the program set (`ESC O A` in application cursor mode,
|
|
2798
|
+
`ESC [ A` otherwise), a modifier on an arrow, edit or function key is
|
|
2799
|
+
xterm's parameter (`Control+ArrowUp` → `ESC [ 1 ; 5 A`), `Control` on a
|
|
2800
|
+
letter is its control character, `Alt` sends `ESC` before the key.
|
|
2801
|
+
`Shift+Enter` is a plain CR, as in Terminal.app. `Meta` is refused: it is
|
|
2802
|
+
a terminal app's own shortcut key, and the `shell` terminal has no app.
|
|
2803
|
+
|
|
2804
|
+
### `terminalClipboardWrite(text)` / `terminalClipboardRead()`
|
|
2805
|
+
|
|
2806
|
+
The clipboard of the active terminal. `terminalClipboardWrite` puts the
|
|
2807
|
+
text there, `terminalClipboardRead` returns the text that is on it (`''`
|
|
2808
|
+
when there is none): a token read in the terminal goes into a field of
|
|
2809
|
+
the page under test, and the other way round.
|
|
2810
|
+
|
|
2811
|
+
- A window: the clipboard of the machine it is on — this Mac, or the VM
|
|
2812
|
+
when the window was opened with `{host}`.
|
|
2813
|
+
- The `shell` terminal: the terminal's own clipboard, the one a program
|
|
2814
|
+
in a remote or CI terminal reaches — OSC 52. What a program sets with
|
|
2815
|
+
`ESC ] 52 ; c ; <base64> BEL` is what `terminalClipboardRead` returns;
|
|
2816
|
+
what `terminalClipboardWrite` put there is the terminal's answer to
|
|
2817
|
+
`ESC ] 52 ; c ; ? BEL`. The machine's own clipboard is not touched.
|
|
2818
|
+
|
|
2819
|
+
```js
|
|
2820
|
+
openTerminal('Terminal', { host: 'admin@192.168.64.38' });
|
|
2821
|
+
terminalType('my-cli login --print-token');
|
|
2822
|
+
terminalPress('Enter');
|
|
2823
|
+
terminalType('my-cli token | pbcopy');
|
|
2824
|
+
terminalPress('Enter');
|
|
2825
|
+
fill(getByLabel('Token'), terminalClipboardRead());
|
|
2826
|
+
|
|
2827
|
+
terminalClipboardWrite('clip-4821'); // the shell's pbpaste prints it
|
|
2828
|
+
```
|
|
2829
|
+
|
|
2830
|
+
- Without an open window the step fails as the other terminal steps do:
|
|
2831
|
+
"no terminal is open".
|
|
2832
|
+
- The text written is marked concealed and transient, so a clipboard
|
|
2833
|
+
manager does not keep it. It stays on the clipboard until something
|
|
2834
|
+
replaces it; `terminalType` puts the clipboard back as it found it.
|
|
2835
|
+
- Neither step logs the text or quotes it in an error. It is masked in the
|
|
2836
|
+
run like any value of the scenario that is a registered secret.
|
|
2837
|
+
- On a VM the text travels as an argument of a job the controller runs, and
|
|
2838
|
+
the job's file (`~/.unotest-terminal/jobs/<id>`) holds it until the
|
|
2839
|
+
answer comes back, as for `terminalType`.
|
|
2840
|
+
|
|
2841
|
+
### `terminalWaitForExit({code?, timeoutMs?})` → `{exitCode, signal}`
|
|
2842
|
+
|
|
2843
|
+
Waits until the shell of the active terminal exits and returns how it
|
|
2844
|
+
ended: `exitCode`, and `signal` — the signal's name (`'SIGTERM'`) when one
|
|
2845
|
+
ended it, otherwise `null`. It is the way to check a command-line tool's
|
|
2846
|
+
exit code: end the command with `exit $?`, or start the program with
|
|
2847
|
+
`exec`, so that the shell ends with it.
|
|
2848
|
+
|
|
2849
|
+
```js
|
|
2850
|
+
function test_cli_fails_on_a_bad_flag() {
|
|
2851
|
+
step("The tool exits with 2 on a flag it does not know", () => {
|
|
2852
|
+
openTerminal();
|
|
2853
|
+
terminalType('my-cli --nope; exit $?');
|
|
2854
|
+
terminalPress('Enter');
|
|
2855
|
+
terminalWaitForExit({code: 2});
|
|
2856
|
+
});
|
|
2857
|
+
}
|
|
2858
|
+
```
|
|
2859
|
+
|
|
2860
|
+
- **`code`:** any other exit code fails with `expected exit code 0, got 2
|
|
2861
|
+
(no signal)` and the end of the screen — the last 10 non-empty rows,
|
|
2862
|
+
registered secrets masked.
|
|
2863
|
+
- **Time:** waits up to 30 s; `{timeoutMs}` sets it. A shell that is still
|
|
2864
|
+
running fails with the end of the screen.
|
|
2865
|
+
- **Again:** after the exit, a second call answers at once with the same
|
|
2866
|
+
result.
|
|
2867
|
+
- **After the exit:** `terminalType` and `terminalPress` are refused
|
|
2868
|
+
(`the shell exited (code N) — open another terminal`); the last screen
|
|
2869
|
+
stays for `terminalText()` and the waits.
|
|
2870
|
+
- **Only the shell terminal:** a Terminal.app or iTerm2 window shows a
|
|
2871
|
+
screen, not the process behind it, and the call is refused with the way
|
|
2872
|
+
out (`openTerminal()`).
|
|
2873
|
+
|
|
2602
2874
|
### `terminalWaitForText(text, options?)` / `terminalAssertText(text, options?)`
|
|
2603
2875
|
|
|
2604
|
-
The screen is the
|
|
2605
|
-
string matches
|
|
2876
|
+
The screen is the terminal's visible text, rows without their padding. A
|
|
2877
|
+
string matches within one row, a `/regex/` is tested against the whole
|
|
2878
|
+
screen as it is. `{not: true}` with a string is stricter: whitespace and
|
|
2879
|
+
row breaks do not count, so a token the terminal wrapped onto the next row
|
|
2880
|
+
is still shown and the assertion fails. The screen does not say where the
|
|
2881
|
+
terminal wrapped, so a positive check never joins rows (`'Passed 10'` is
|
|
2882
|
+
not found on `Passed 1` above `0 failed`), and a `/regex/` with
|
|
2883
|
+
`{not: true}` does not see across a wrapped row.
|
|
2606
2884
|
`{not: true}` waits for the text to go. `terminalWaitForText` waits up to
|
|
2607
2885
|
30 s, `terminalAssertText` 5000 ms; `{timeoutMs}` sets either.
|
|
2608
2886
|
|
|
2887
|
+
`terminalWaitForText` returns what it saw, so a value on the screen can go
|
|
2888
|
+
on into the test:
|
|
2889
|
+
|
|
2890
|
+
- a `/regex/` → the match array, as `textMatches` gives it: `[0]` is the
|
|
2891
|
+
match, then the groups (a group that took no part is `null`);
|
|
2892
|
+
- a string → the first screen row that holds it (`'code:'` gives
|
|
2893
|
+
`'Your code: ABCD-1234'`). A line the terminal wrapped gives only its
|
|
2894
|
+
first screen row;
|
|
2895
|
+
- `{not: true}` → `null`.
|
|
2896
|
+
|
|
2897
|
+
What it returns comes from the screen with every value registered in
|
|
2898
|
+
`.secrets` masked as `‹secret:NAME›`, wrapped or not; whether the text is
|
|
2899
|
+
there is decided on the screen as it is, so a wait for a secret, or an
|
|
2900
|
+
assertion that one is `{not: true}` shown, tells the truth. A `/regex/`
|
|
2901
|
+
that matches only the secret itself returns a one-element array: the
|
|
2902
|
+
masked screen row where the match begins.
|
|
2903
|
+
|
|
2904
|
+
`terminalAssertText` returns nothing.
|
|
2905
|
+
|
|
2906
|
+
When either one runs out of time, the error carries the end of the screen
|
|
2907
|
+
— the last 10 rows that are not empty — so the prompt it is stuck at (a
|
|
2908
|
+
`[Y/n]`, an error line) is in the message, not only in the failure bundle.
|
|
2909
|
+
A value registered from `.secrets` is masked there, wrapped or not. The
|
|
2910
|
+
whole screen is `terminal.txt` in the failure bundle.
|
|
2911
|
+
|
|
2912
|
+
A wait never runs past the test's own time budget: with less than the
|
|
2913
|
+
requested `{timeoutMs}` left, it stops 2 s short of the budget and fails with
|
|
2914
|
+
the screen and the line "cut to N ms", instead of the test ending on its
|
|
2915
|
+
budget with neither. `lint:wait-exceeds-test-budget` warns about a literal
|
|
2916
|
+
wait as long as the whole budget.
|
|
2917
|
+
|
|
2918
|
+
```js
|
|
2919
|
+
terminalType('my-cli login');
|
|
2920
|
+
terminalPress('Enter');
|
|
2921
|
+
const m = terminalWaitForText(/code: ([A-Z]{4}-\d{4})/);
|
|
2922
|
+
fill(getByLabel('Device code'), m[1]);
|
|
2923
|
+
```
|
|
2924
|
+
|
|
2925
|
+
### `terminalText()` → `string`
|
|
2926
|
+
|
|
2927
|
+
The active terminal's screen as text, what a failed test keeps as
|
|
2928
|
+
`terminal.txt`: every value registered in `.secrets` is masked as
|
|
2929
|
+
`‹secret:NAME›`, a value the terminal wrapped onto the next row too, so a
|
|
2930
|
+
`note()` or `log()` of it shows no part of a secret.
|
|
2931
|
+
|
|
2609
2932
|
### `terminalResize(cols, rows)`
|
|
2610
2933
|
|
|
2611
|
-
Resizes the active
|
|
2934
|
+
Resizes the active terminal to `cols` × `rows` character cells; the
|
|
2935
|
+
program in it gets the new size as from a window resized by hand.
|
|
2612
2936
|
|
|
2613
2937
|
### `terminalScreenshot(name?)` → `string`
|
|
2614
2938
|
|
|
2615
|
-
A PNG of the active
|
|
2939
|
+
A PNG of the active terminal, saved with the run like `screenshot()`: a
|
|
2940
|
+
window's own picture, or the `shell` terminal's screen drawn in its
|
|
2941
|
+
colours.
|
|
2942
|
+
Returns its project-relative path. When a registered secret is on the
|
|
2943
|
+
screen, it saves the masked screen text (`.txt`) instead and returns
|
|
2944
|
+
that path — see "Secrets on the screen" above.
|
|
2945
|
+
|
|
2946
|
+
## Three surfaces in one test
|
|
2947
|
+
|
|
2948
|
+
One test can drive the web app on the host, a terminal in a VM, and the
|
|
2949
|
+
VM's browser, and let go of all three when it ends — green or red. There
|
|
2950
|
+
is no function for it: the pieces are the ones above, and they close in
|
|
2951
|
+
an order that keeps the VM for last.
|
|
2952
|
+
|
|
2953
|
+
```js
|
|
2954
|
+
function test_three_surfaces() {
|
|
2955
|
+
skip('no VM host', !vmAvailable());
|
|
2956
|
+
setTestTimeout(900000);
|
|
2957
|
+
let ip;
|
|
2958
|
+
|
|
2959
|
+
step("Boot a clean VM", () => {
|
|
2960
|
+
ip = vmRun(vmClone('clean-mac'));
|
|
2961
|
+
});
|
|
2962
|
+
|
|
2963
|
+
step("A terminal in the VM prints a code, the host's page shows it", () => {
|
|
2964
|
+
openTerminal('Terminal', {host: 'admin@' + ip});
|
|
2965
|
+
terminalType('echo code-$((40 + 2))');
|
|
2966
|
+
terminalPress('Enter');
|
|
2967
|
+
const code = terminalWaitForText(/code-(\d+)/, {timeoutMs: 20000})[1];
|
|
2968
|
+
mockRoute('**/status', {contentType: 'text/html', body: '<p>agent says ' + code + '</p>'});
|
|
2969
|
+
goto('/status');
|
|
2970
|
+
assertVisible(getByText('agent says 42'));
|
|
2971
|
+
});
|
|
2972
|
+
|
|
2973
|
+
step("The VM's browser is context 1", () => {
|
|
2974
|
+
newContext({cdpEndpoint: 'http://' + ip + ':9223'});
|
|
2975
|
+
goto('https://example.com');
|
|
2976
|
+
setContext(0);
|
|
2977
|
+
});
|
|
2978
|
+
|
|
2979
|
+
step("Both surfaces in one wait", () => {
|
|
2980
|
+
waitUntil(() => textContains(terminalText(), 'agent-answered') && isVisible(getByText('agent says 42')),
|
|
2981
|
+
{timeoutMs: 20000, label: 'terminal and web'});
|
|
2982
|
+
});
|
|
2983
|
+
}
|
|
2984
|
+
```
|
|
2985
|
+
|
|
2986
|
+
- **Time:** a test has 5 minutes unless you say otherwise, and a VM alone
|
|
2987
|
+
takes about one to boot. Start with `setTestTimeout(ms)` sized for the
|
|
2988
|
+
boot, an install and the answer you wait for.
|
|
2989
|
+
- **The VM's browser:** `newContext({cdpEndpoint})` joins a Chrome that
|
|
2990
|
+
already listens for remote debugging, and needs an address the host can
|
|
2991
|
+
reach. The `clean-mac` image forwards the browser's debugging port to
|
|
2992
|
+
port 9223 on the VM's own address; with another image, forward it
|
|
2993
|
+
yourself, or put a tunnel in front.
|
|
2994
|
+
- **One wait on two surfaces:** the active terminal and the active browser
|
|
2995
|
+
context are two separate choices, so one `waitUntil` condition can read
|
|
2996
|
+
both without switching. It fails with its `label` and the last value,
|
|
2997
|
+
not with a screen. When the order is known, two waits in a row
|
|
2998
|
+
(`terminalWaitForText`, then `assertVisible`) are better: each one quotes
|
|
2999
|
+
its own surface when it times out.
|
|
3000
|
+
- **Letting go:** when the test ends, what it opened is closed newest
|
|
3001
|
+
first: the VM's browser is closed and disconnected (the browser itself
|
|
3002
|
+
stays; it belongs to the VM), then the terminal window, and the VM
|
|
3003
|
+
last — stopped and deleted even when the test failed. A browser that
|
|
3004
|
+
already went away with its VM does not hold the test up for long.
|
|
3005
|
+
- **Evidence:** the failure bundle holds the page of the active context and
|
|
3006
|
+
the screen of the active terminal at the moment of the failure. To keep a
|
|
3007
|
+
frame of the other surface, take it before switching:
|
|
3008
|
+
`screenshot('host')` or `terminalScreenshot('vm')`.
|
|
2616
3009
|
|
|
2617
3010
|
## Typed getters
|
|
2618
3011
|
|
|
@@ -3055,6 +3448,49 @@ assertTrue(consoleEntries({ level: ['warn', 'error'], since: before }).length ==
|
|
|
3055
3448
|
- A service worker's console is not a page's: it is not here.
|
|
3056
3449
|
- Independent of `UNOTEST_CONSOLE`, which decides only whether a run
|
|
3057
3450
|
also writes `console.json` into its artifacts and failure bundles.
|
|
3451
|
+
Without the flag a run keeps no console file, passing or not: ask
|
|
3452
|
+
`consoleEntries()` in the scenario, or set the flag (a box's variables
|
|
3453
|
+
too) before the run you want to read. With it, the run directory's
|
|
3454
|
+
`console.json` holds the lines of every browser context, each with its
|
|
3455
|
+
`contextIndex`, the last 500 by time.
|
|
3456
|
+
|
|
3457
|
+
### `networkEntries(options?)` → `[{ url, method, status, ok, requestJson, responseJson, responseText, at }]`
|
|
3458
|
+
|
|
3459
|
+
What the active page requested and was answered, oldest first. Like the
|
|
3460
|
+
console, it is recorded from the moment the page opened, so the usual
|
|
3461
|
+
order works: act, then ask. A response is entered when it finishes, so
|
|
3462
|
+
wait for it.
|
|
3463
|
+
|
|
3464
|
+
```js
|
|
3465
|
+
click(getByRole('button', { name: 'Verify' }));
|
|
3466
|
+
waitUntil(() => networkEntries({ glob: '/api/contacts/verify*' }).length > 0);
|
|
3467
|
+
const answer = networkEntries({ glob: '/api/contacts/verify*' })[0];
|
|
3468
|
+
assertEqual(answer.status, 200);
|
|
3469
|
+
assertEqual(answer.responseJson.kind, 'mobile');
|
|
3470
|
+
```
|
|
3471
|
+
|
|
3472
|
+
- `status` / `ok` — the response; a request that failed before any
|
|
3473
|
+
response (refused, aborted) has `status` 0, `ok` false and
|
|
3474
|
+
`failureText`.
|
|
3475
|
+
- `mocked` — `true` when a `mockRoute` answered or aborted it.
|
|
3476
|
+
- Bodies are read for `fetch` and `xhr` requests with a text or JSON
|
|
3477
|
+
content type, at most 64 KB each; a longer one is cut, `truncated` is
|
|
3478
|
+
`true` and its `responseJson` is `null`. Other resources (documents,
|
|
3479
|
+
images, scripts) have a status only.
|
|
3480
|
+
- `requestJson` — the request body read as JSON, as `postDataJson` of
|
|
3481
|
+
[`waitForRequest`](#waitforrequestglob-options--url-method-headers-postdata-postdatajson);
|
|
3482
|
+
`null` when there is none or it is not JSON. `responseJson` — the same
|
|
3483
|
+
for the response; `responseText` — the response body of a text
|
|
3484
|
+
content type, `null` otherwise.
|
|
3485
|
+
- `at` — when the request was sent, epoch ms as `nowMs()` gives.
|
|
3486
|
+
- `{since}` — epoch ms: only requests sent from then on.
|
|
3487
|
+
- `{glob}` — a URL mask as in `waitForRequest`; one starting with `/` is
|
|
3488
|
+
read on the site's origin (`/api/**` is `https://<site>/api/**`).
|
|
3489
|
+
- The last 500 requests of the context are kept, the oldest go first.
|
|
3490
|
+
- Secrets are masked in the bodies like in any value of the run.
|
|
3491
|
+
- A service worker's own requests are not a page's: they are not here.
|
|
3492
|
+
- Independent of `UNOTEST_NETWORK`, which decides only whether a run
|
|
3493
|
+
also writes `network.json` into its artifacts and failure bundles.
|
|
3058
3494
|
|
|
3059
3495
|
### `pageErrors(options?)` → `[{ message, stack }]`
|
|
3060
3496
|
|
|
@@ -3122,8 +3558,12 @@ step.soft("Question", {tag: q.id}, () => {
|
|
|
3122
3558
|
|
|
3123
3559
|
- `label` is a string; `value` is anything — a string as it is, a
|
|
3124
3560
|
number, an object or array serialized as JSON.
|
|
3125
|
-
-
|
|
3126
|
-
|
|
3561
|
+
- The journal keeps the first 4 KB of a value (marked `truncated`). The
|
|
3562
|
+
whole value, secrets masked, is written to `notes/<n>.txt` in the run
|
|
3563
|
+
directory (up to 1 MB), and the event carries `full` (that path) and
|
|
3564
|
+
`fullLength`. `--notes` ends a cut value with
|
|
3565
|
+
`… (+N chars, full: <path>)`. Secrets are masked like everywhere in the
|
|
3566
|
+
run directory.
|
|
3127
3567
|
- Each `note` / `log` event records where it was called (`file`, `line`,
|
|
3128
3568
|
`col`) and the nearest statement of the entry file (`entryLine`,
|
|
3129
3569
|
`entryCol`) — a note from inside a helper lands under the entry step
|
|
@@ -3290,7 +3730,7 @@ per option; an older spelling it still takes is named after the line.
|
|
|
3290
3730
|
- `closePage(index?: number): void`
|
|
3291
3731
|
- `setViewport(size: { width?: number; height?: number } | null): void`
|
|
3292
3732
|
- `emulateMedia(media: { reducedMotion?: "reduce" | "no-preference"; colorScheme?: "light" | "dark" | "no-preference" }): void`
|
|
3293
|
-
- `newContext(): number`
|
|
3733
|
+
- `newContext(options?: { profile?: string; cdpEndpoint?: string }): number`
|
|
3294
3734
|
- `setContext(index: number): void`
|
|
3295
3735
|
- `enterFrame(frame: Locator): void`
|
|
3296
3736
|
- `exitFrame(): void`
|
|
@@ -3324,15 +3764,20 @@ per option; an older spelling it still takes is named after the line.
|
|
|
3324
3764
|
- `unmockRoute(glob?: string): void`
|
|
3325
3765
|
- `waitForRequest(glob: string, options?: { timeoutMs?: number }): any`
|
|
3326
3766
|
- `waitForWebSocket(glob: string, options?: { timeoutMs?: number }): any`
|
|
3767
|
+
- `networkEntries(options?: { since?: number; glob?: any }): any`
|
|
3327
3768
|
- `assertNoRequest(glob: string, options?: { since?: number }): void`
|
|
3328
|
-
- `openTerminal(app
|
|
3769
|
+
- `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`
|
|
3329
3770
|
- `setTerminal(index: number): void`
|
|
3330
3771
|
- `closeTerminal(): void`
|
|
3331
3772
|
- `terminalType(text: string, options?: { echo?: boolean }): void`
|
|
3773
|
+
- `terminalClipboardWrite(text: string): void`
|
|
3774
|
+
- `terminalClipboardRead(): string`
|
|
3332
3775
|
- `terminalPress(key: string): void`
|
|
3333
|
-
- `terminalWaitForText(text: string | RegExp, options?: { not?: boolean; timeoutMs?: number }):
|
|
3776
|
+
- `terminalWaitForText(text: string | RegExp, options?: { not?: boolean; timeoutMs?: number }): any` (alias: timeout → timeoutMs)
|
|
3777
|
+
- `terminalWaitForExit(options?: { code?: number; timeoutMs?: number }): any` (alias: timeout → timeoutMs)
|
|
3334
3778
|
- `terminalAssertText(text: string | RegExp, options?: { not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3335
3779
|
- `terminalResize(cols: number, rows: number): void`
|
|
3780
|
+
- `terminalText(): string`
|
|
3336
3781
|
- `terminalScreenshot(name?: string): string`
|
|
3337
3782
|
- `mcpStart(command: string, args?: string[], options?: { env?: any; cwd?: any; timeoutMs?: number }): any`
|
|
3338
3783
|
- `mcpCall(server: any, tool: string, args?: any, options?: { timeoutMs?: number; allowError?: any }): any`
|