@unotest/web 0.52.0 → 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.
@@ -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 (macOS)](#terminal-macos) — a real Terminal.app / iTerm2 window
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 (macOS)
2603
+ ## Terminal
2508
2604
 
2509
- A real terminal window: Terminal.app or iTerm2, driven by real key
2510
- events, read as screen text, framed as a picture. For a CLI or a TUI
2511
- (an agent in a terminal, an installer, a `--watch` mode) the bugs a
2512
- pseudo-terminal hides live here: a key the terminal encodes itself
2513
- (Shift+Enter under the kitty keyboard protocol), the window's width, the
2514
- `PATH` of the shell the user actually has.
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 real terminal", () => {
2523
- openTerminal('Terminal');
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 app, on which host).
2537
-
2538
- **Where it runs.** macOS, through `osascript` and `screencapture`.
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
- - A Linux terminal is not driven yet.
2558
-
2559
- ### `openTerminal(app, options?)` → `number`
2560
-
2561
- Opens a window of `'Terminal'` or `'iTerm2'` with a login shell, makes it
2562
- active, returns its index. Options: `{host: 'user@address'}` — the Mac to
2563
- open it on. Every window the test opened closes when it ends, green or
2564
- red; its shell and what runs in it are stopped.
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: a line goes on
2575
- the clipboard, then ⌘V, and a line break presses Return. The Mac's
2576
- keyboard layout does not change what arrives — Cyrillic and emoji
2577
- included — and the clipboard holds what you copied again when the step
2578
- ends. A program in the terminal sees a paste, not typing: a TUI that
2579
- turned bracketed paste on gets the text as one paste.
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 window's visible text, rows without their padding. A
2605
- string matches anywhere on it, a `/regex/` is tested against it.
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 window to `cols` × `rows` character cells.
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 window, saved with the run like `screenshot()`.
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
- - Long values are cut at 4 KB (marked `truncated`); secrets are masked
3126
- like everywhere in the run directory.
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: string, options?: { host?: any }): number`
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 }): void` (alias: timeout → timeoutMs)
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`