@unotest/web 0.43.2 → 0.44.0

package/guides/dsl-reference.md

@@ -545,6 +545,116 @@ Semantics:
   parsing rubric lines `must contain: <substring>` /
   `must not contain: <substring>`.
 
+### `assertScreenshot(name, options?)` / `assertScreenshot(loc, name, options?)`
+
+Since 0.44.0.
+
+The page — or one element — against a PNG baseline in the repo: a mockup
+exported from Figma, or a snapshot you accepted earlier.
+
+```js
+function test_chat_matches_figma() {
+  step("Chat screen matches the mockup", () => {
+    goto('/demo/chat');
+    waitForText('Hi!');
+    assertScreenshot('chat-empty', {
+      maxDiffRatio: 0.05,                                  // share of pixels, 0..1
+      threshold: 32,                                       // per channel, 0..255
+      mask: [getByTestId('clock'), getByTestId('avatar')], // elements on the page
+      ignore: [{x: 0, y: 0, width: 780, height: 94}],      // areas of the baseline
+    });
+  });
+}
+```
+
+**The metric** is the one you would count by hand. A pixel *differs* when
+any of its R, G, B, A channels differs by more than `threshold` (default
+32). The assert fails when the share of differing pixels among the
+compared ones is **more than** `maxDiffRatio` (default 0 — every pixel
+within the threshold). Exactly the limit passes: 5.0% differing at
+`maxDiffRatio: 0.05` is green, 5.1% is red. No perceptual colour model —
+the number in the report is the number you get.
+
+**Masks.** `mask: [locator…]` — the boxes of those elements at the moment
+of the snapshot; a locator that matches nothing is an error, not a
+skipped mask. `ignore: [{x, y, width, height}…]` — rectangles in the
+baseline's pixels, for what the page does not have (a phone's status bar
+in a mockup). Everything masked is left out on both sides and out of the
+share.
+
+**Password fields** — `type="password"`, or `autocomplete` of
+`current-password`, `new-password` or `one-time-code` — are painted over
+in magenta (`#FF00FF`) on the snapshot, as on every screenshot the tool
+takes, so a baseline accepted from a snapshot has them painted over too. A
+mockup that shows such a field needs it covered with `ignore`.
+
+**Size.** Snapshot and baseline are compared pixel for pixel, never
+resampled. A different size fails at once with both sizes: match the
+viewport and `deviceScaleFactor` to the baseline — a 780×1688 Figma
+export at 2x is `viewport: {width: 390, height: 844, deviceScaleFactor: 2}`.
+
+**The snapshot** is taken the way `screenshot()` takes one — after the
+page settles — with animations finished and the caret hidden, and the
+page's time frozen if you froze it. By default it is the viewport;
+`fullPage: true` takes the whole page (not for an element). An image may
+have at most 25 megapixels — a larger baseline or snapshot is refused
+before it is read.
+
+**The baseline** lives next to the scenario:
+`unotest/e2e/<scenario path without .js>.screenshots/<name>.png` (the
+name is lower-cased and dashed, as for `screenshot()`), and travels with
+the scenario into a box bundle. Two names that become the same file in one
+scenario (`"Checkout Page"` and `"checkout/page"`) are refused at the
+second one; the same name twice in one run of `--update-screenshots` is
+written twice, and the runner says that the last one wins. A symlink on
+the way to a baseline is followed while it stays inside the project (a
+shared directory of the suite); one that leads outside is refused.
+
+- **Unreadable baseline** — a file that is not a PNG, or one over the
+  ceiling, fails the assert (not the run); the snapshot is saved as a
+  candidate to replace it.
+
+- **No baseline yet** — the assert fails; the snapshot is saved in the
+  run's artifacts as a candidate under the baseline's own file name, and
+  the message says where it goes. Nothing is written into the repo on its
+  own: a first run that turned green by writing its own baseline would
+  check nothing.
+- **Accept the current page** — `npx @unotest/web e2e <name>
+  --update-screenshots` (MCP: `run_test {updateScreenshots: true}`)
+  writes every snapshot of the run as its baseline; the asserts pass and
+  the journal marks them `updated`. Refused on a box.
+- **It failed** — the run keeps three pictures: `expected`, `actual` and
+  `diff` (differing pixels red over a greyed-out snapshot, masked areas
+  grey). The viewer shows them side by side on the failed step; the
+  failure bundle and `run_test` (`next.visual`) point at them. A retried
+  attempt keeps its own pictures.
+
+**Baselines for a box.** Fonts render differently on macOS and on the
+box (Linux), so a baseline recorded on your laptop will not match there.
+Take recorded baselines where the suite runs:
+
+1. Push the scenario with `assertScreenshot` and no baseline.
+2. The run on the box is red: `no baseline at …`, the candidate is in
+   the run's artifacts.
+3. Download it — the viewer's **Download as baseline** on the failed
+   step, or `npx @unotest/web box run <runId> --env <project>/<env>
+   --download` (MCP: `box_run_download`), which unpacks the candidates
+   next to the zip. The file is already named as the assert expects.
+4. Put it in `unotest/e2e/<scenario>.screenshots/`, commit, push — the
+   next run on the box is green.
+
+A Figma export is the same on every platform: commit it as is.
+
+Baselines count towards the bundle. Boxes accept 128 MB by default; a
+larger suite is warned about before the upload, with its biggest files
+and baselines — compare an element instead of a full page to keep them
+small.
+
+**Secrets and personal data.** A baseline is a file in your repo. Mask
+every area that shows a secret, a token or someone's personal data
+before the first snapshot is written — once committed, it is in the
+history.
+
 ---
 
 ## Queries
@@ -710,6 +820,63 @@ pause(500); // lint-ok: third-party widget has no completion signal to hook into
 helpers with known warnings stop drowning out new ones). Error-severity
 diagnostics are never suppressible.
 
+### `clockFreeze(iso)` / `clockTick(ms)` / `clockRun()`
+
+The page clock. Stops time on the page, moves it by hand, lets it go.
+For anything that animates on timers — a "typing…" indicator, a
+countdown, a relative "5 minutes ago" — so a screenshot of it is the
+same pixels on every run.
+
+```js
+goto('/chat');
+clockFreeze('2026-01-15T10:00:00Z');   // Date reads this; no timer fires
+screenshot('chat-typing');              // same pixels every run
+clockTick(1500);                        // 1.5 s pass: due timers fire
+clockRun();                             // time runs by itself again
+```
+
+- `clockFreeze(iso)` — `Date.now()` and `new Date()` on the page read
+  `iso`; `setTimeout`, `setInterval` and `requestAnimationFrame` stand
+  still. Any instant, past or future: no timer fires on the way to it.
+- `clockTick(ms)` — frozen time moves forward by `ms`, and every timer
+  due in that span fires, in order.
+- `clockRun()` — time runs by itself again, from where it stands.
+
+**When the clock is installed.** A fake clock only controls timers set
+after it is in place, so a run puts it on the browser before the first
+page loads — and only for a scenario that can reach a clock call
+(directly, or through a helper it calls). Every other scenario keeps the
+page's real time, as before. So `clockFreeze` works at any point of the
+scenario, after `goto` included. Over MCP the browser has to be opened
+with the clock: `new_context {clock: true}` (or `explore_start {clock:
+true}`), then `explore_step` actions `clock_freeze {time}`,
+`clock_tick {ms}`, `clock_run`.
+
+**Coming from Playwright.** The names are flat: `clock.freeze(...)`,
+`clock.tick(...)`, `clock.run()` (and `pauseAt`, `setFixedTime`,
+`runFor`, `resume`) are refused with the name to use instead. Where
+Playwright's `pauseAt` only moves forward, `clockFreeze` also takes a
+date in the past.
+
+Not with `launch.userDataDir`, once its shared context is open: the
+pages already loaded in it keep real timers, so the clock is refused
+there rather than half-applied.
+
+### Time zone and locale
+
+`timezone` and `locale` in `unotest.config.mjs` set them for every page:
+
+```js
+export default {
+  timezone: 'Europe/Madrid',   // Date#toString, Intl, getTimezoneOffset
+  locale: 'es-ES',             // navigator.language, Intl defaults, Accept-Language
+};
+```
+
+Unset, the page gets the machine's zone and the browser's locale.
+`UNOTEST_TIMEZONE` / `UNOTEST_LOCALE` override the config for one run.
+An unknown zone or a malformed locale is refused when the config loads.
+
 ---
 
 ## Multi-context
@@ -742,6 +909,133 @@ having to track tab indexes. See
 `docs/auto-page-switch/README.md`
 and `UNOTEST_POPUP_GRACE_MS` in `unotest/.env`.
 
+### `newContext()` → `number` / `setContext(index)`
+
+A second browser context: another client of the same app, with its own
+cookies, localStorage, sessionStorage and tabs. For anything that takes
+two users — one closes a ticket, the other still has it open.
+
+`newContext()` opens one with the same options as the first (base URL,
+viewport and scale, `device`, time zone, locale, page clock), makes it
+active, and returns its number: the test's own context is `0`, the next
+is `1`. Nothing of the first is inherited — no cookie, no storage, no
+`storageState`. `setContext(i)` makes context `i` active; every locator,
+assertion, `setPage`, frame and storage call then acts in it. Each
+context keeps its own active tab and frame stack, so switching away and
+back lands where the scenario left off.
+
+```js
+function test_second_client_writes_to_closed_thread() {
+  step("Client A opens the thread", () => {
+    flow_login(LOGIN, PASSWORD);
+    goto('/support/thread/42');
+  });
+  step("Client B opens the same thread", () => {
+    clientB = newContext();             // returns 1, becomes active
+    flow_login(LOGIN, PASSWORD);
+    goto('/support/thread/42');
+  });
+  step("Client A closes the ticket", () => {
+    setContext(0);                      // client A
+    click(getByRole('button', {name: 'Close ticket'}));
+  });
+  step("Client B cannot write", () => {
+    setContext(clientB);
+    fill(getByRole('textbox', {name: 'Message'}), 'hello');
+    press(getByRole('textbox', {name: 'Message'}), 'Enter');
+    assertVisible(getByText('This ticket is closed'));
+  });
+}
+```
+
+`flow_login` is your project's own sign-in helper (`unotest/e2e/_helpers/`);
+the rest is the DSL. A variable set inside one `step(...)` is visible
+in the next — `clientB` above — because a step block has no scope of its
+own.
+
+- **Ceiling:** 4 contexts per test, `maxContexts` in the config. The next
+  `newContext()` is refused, naming the key — a loop opening one per
+  iteration stops there.
+- **End of the test:** every context is closed, in any outcome. One that
+  fails to close is a warning in the run log.
+- **Journal:** once a second context exists, each step event carries
+  `contextIndex` — the context the step **started** in (so
+  `setContext(0)` issued from context 1 is marked `1`), and the viewer's
+  Trace shows it as a `ctx N` chip. A one-context test writes exactly
+  what it did before.
+- **Failure bundle:** the page, console and network of the context
+  active at the failure, and `contextIndex` in `failure.json`. The other
+  contexts are not in it: to keep a frame of client A, `screenshot()` it
+  before switching.
+- **Traces and video:** not recorded for any context — unotest does not
+  capture Playwright traces or video today.
+- **Browser profile:** with `launch.userDataDir` every page shares one
+  context, so `newContext()` is refused there.
+- **Debugging:** an agent that joins a paused run (`take_wheel`,
+  `attach_debug_session`) lands in the context the run is on (Chromium).
+- **Names:** a function or variable of your own called `newContext` /
+  `setContext` (or any DSL name) is reported by `lint:shadows-dsl-function`
+  — your function wins a call by that name, so the DSL's is out of reach
+  until you rename it.
+
+Over MCP, record it with `explore_step {action: "newContext"}` and
+`{action: "setContext", index}`; they become the same two calls in the
+saved test. The `new_context` tool is different: it resets the browser.
+
+### `setViewport({width, height})`
+
+Resize the browser window mid-scenario. Every open tab is resized in
+place — no reload, the page keeps its state — and a tab opened afterwards
+starts at the same size. The size belongs to the browser, not to one tab.
+
+```js
+setViewport({width: 420, height: 900});   // a phone-width layout
+screenshot('card-narrow');
+setViewport({width: 1280, height: 720});
+```
+
+Both fields are required. Anything else is refused on that line,
+`deviceScaleFactor` included: the scale is fixed when the browser opens,
+and changing it would need a new browser context — the page under test
+would be lost. See [Viewport and scale](#viewport-and-scale).
+
+#### Viewport and scale
+
+Where the window's size and scale come from, first match wins:
+
+1. **The MCP call.** `new_context` and `explore_start` take
+   `viewport: {width, height, deviceScaleFactor}` and `device`. They
+   replace the config's window for that context. `explore_start` with a
+   window while a context is already open is refused — call
+   `new_context` with it instead.
+2. **The config.** `unotest.config.mjs`:
+
+   ```js
+   export default {
+     viewport: { width: 390, height: 844, deviceScaleFactor: 2 },
+   };
+   ```
+
+   `deviceScaleFactor: 2` doubles every screenshot: a 390×844 page
+   becomes a 780×1688 PNG, the scale design mockups are usually drawn
+   at. Every field is optional; a missing one comes from the preset or
+   the default.
+3. **A device preset.** `device: "iPhone 14"` applies Playwright's
+   preset whole: size, scale, touch, mobile mode, user agent. The name
+   is Playwright's, exactly; an unknown name is refused with the
+   nearest ones. `viewport` next to `device` overrides the preset field
+   by field.
+4. **The default:** 1280×720 at scale 1.
+
+A preset's viewport is the page area, smaller than the device's screen:
+`"iPhone 14"` is 390×664 (the browser chrome takes the rest of 844). To
+match a 390×844 mockup, set `viewport` explicitly:
+`{width: 390, height: 844, deviceScaleFactor: 2}`.
+
+A mobile preset lays out a page with no `<meta name="viewport">` tag at
+980 px wide, as a real phone does. Firefox has no mobile mode: a mobile
+preset on Firefox is refused — give it a plain `viewport` instead.
+
 ### `enterFrame(loc)`
 
 Enter an iframe scope. Subsequent calls run inside the frame's document.
@@ -1295,7 +1589,8 @@ screenshot('landing', {fullPage: true}); // full scroll height
   `load`, which on a client-rendered app fires before any content is on
   screen. A page that never goes quiet (polling, live feeds) costs the
   2s cap and is then captured as-is.
-- Not a visual assertion: the test does not compare images. In runtimes
+- Not a visual assertion: `screenshot()` does not compare images — that is
+  [`assertScreenshot`](#assertscreenshotname-options--assertscreenshotloc-name-options). In runtimes
   with no artifact dir (exploration) the call logs a warning, returns
   `null` and does NOT fail the run.
 - **Every step, without calling it:** `UNOTEST_STEP_SCREENSHOTS=1` makes
@@ -1386,13 +1681,12 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
   ```
 
 - **Array literals** — `[1, 2, 3]`.
-- **Index access on data** — `docs[0]`, `docs[0].objectsCount`. The
-  index goes on a **bare variable** (grammar restriction), so pull
-  nested arrays into one first: `docs = res.body; n = docs[0].count;`.
+- **Index access on data** — `docs[0]`, `docs[0].objectsCount`,
+  `res.body.items[0].id`: see [Strings, objects, indexes](#strings-objects-indexes).
   Indexing a **Locator** is rejected — disambiguate with chain methods
   (`.filter(...)`), and `arr[i] = v` assignment stays unsupported.
-- **Object literals — as call arguments only** (`click(loc, {force:
-  true})`); a standalone `x = {name: 'x'}` is rejected.
+- **Object literals** — as call arguments (`click(loc, {force: true})`)
+  and as values in a variable: see [Strings, objects, indexes](#strings-objects-indexes).
 - **Member access** — `row.email` (dot form; `obj['key']` doesn't
   parse).
 - **Method chains** — `getByRole('row').filter({hasText:'X'}).click()`.
@@ -1409,13 +1703,143 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
 Not supported (and intentionally so): `while` / `do…while` /
 `continue` (bound loops keep every scenario terminating), `++`/`--`,
 arrow functions, async/await (everything is sequenced by the AST
-executor), classes, modules, promises, `try/catch`. Errors thrown from
-a primitive abort the scenario; if the runtime is paused (debugger /
-MCP step mode), the failure is captured for inspection.
+executor), classes, modules, promises, `try/catch` — for cleanup that
+must run whatever happens, see [`teardown`](#teardown--give-the-stand-back).
+Errors thrown from a primitive abort the scenario; if the runtime is
+paused (debugger / MCP step mode), the failure is captured for
+inspection.
 
 See `vendor/dsl/EXTENSIONS.md` for the
 exact grammar deltas from the upstream parser.
 
+### Strings, objects, indexes
+
+Since 0.44.0.
+
+**Strings** answer four members — the whole list:
+
+| Member | Returns | |
+|---|---|---|
+| `s.length` | `number` | a property: no parentheses |
+| `s.trim()` | `string` | whitespace off both ends |
+| `s.includes(search)` | `boolean` | substring probe, same as `textContains(s, search)` |
+| `s.startsWith(prefix)` | `boolean` | |
+
+They work wherever an expression does — in `assertTrue`, in `if`, on a
+literal, on a call result:
+
+```js
+title = getTitle();
+assertTrue(title.trim().length > 0, 'empty title');
+if (out.stdout.includes('ready')) { log('up'); }
+assertTrue(getUrl().startsWith('https://'), getUrl());
+```
+
+Any other member is a lint error that names it and lists the four
+(`validator:unsupported-string-member`); `s.padStart(3)` does not
+reach the browser. A member of the list used on a value that turns out
+not to be a string at run time — a number, or `null` from a missing
+field — fails the step with the value's type in the message.
+
+**Object literals** are values: keep one in a variable, read it back by
+field, hand it to a helper.
+
+```js
+user = {name: 'Alice', tags: ['admin'], address: {city: 'Riga'}};
+flow_sign_up(user);
+assertTrue(user.address.city == 'Riga');
+```
+
+Where a function wants a specific kind (a string, a locator), an
+object in that slot is still an `arg-kind` error.
+
+**Indexes** go anywhere in a chain — no temporary variable:
+
+```js
+res = apiCall('GET', '/documents');
+assertTrue(res.body.items[0].status == 'ready', json(res.body));
+first = dbQuery('SELECT id FROM users ORDER BY id')[0].id;
+```
+
+### `teardown` — give the stand back
+
+Since 0.44.0.
+
+```js
+function test_ticket_closed_in_second_client() {
+  step("Enable the stand flag", () => {
+    teardown("Disable the stand flag", () => {
+      apiCall('POST', '/stand/flags', {closeTickets: false});
+    });
+    apiCall('POST', '/stand/flags', {closeTickets: true});
+  });
+  step("…", () => { … });
+}
+```
+
+`teardown("label", () => { … })` **registers** a rollback — nothing in
+it runs where it stands. After the test body every registered block
+runs, **newest first**:
+
+- whatever the outcome — passed, failed, over its time budget, or
+  stopped (Stop in the viewer, `abort_runtime`, Ctrl-C), including a run
+  stopped while paused at its failure in the debugger or in `run_test`;
+- each block even if an earlier one failed.
+
+Put it **before** the call that changes the stand: then a failure in
+that very call is rolled back too. A flow or helper can carry its own
+rollback (`flow_enable_flag` registers the teardown that disables the
+flag); it still runs at the end of the test, not when the helper
+returns, with the helper's variables as they were when it registered.
+A block in the test itself sees the test's variables as they are when
+it runs.
+
+What you see:
+
+- the CLI prints `↺ teardown "Disable the stand flag"` for each block;
+  the journal and the viewer show it as a frame marked **teardown**
+  after the test's last step;
+- the failure bundle is taken **before** the rollback — its screenshot is
+  the page the test broke on;
+- a green test whose teardown failed is **failed** (the stand was not
+  given back); a failed test keeps its own error, and the teardown
+  failures are listed next to it (CLI `↺ teardown "…" failed: …`,
+  `run_test` → `next.teardownFailures`).
+
+Stopping a run: the first Stop gives the stand back and then ends the
+run — the viewer shows **returning the stand…**, `abort_runtime` answers
+`status: "returning the stand…"`. A second Stop (or a second
+`abort_runtime`) skips what is left; the journal records
+`teardown skipped: second stop` with the blocks that did not run.
+
+How long the first Stop can take: the rollback is cut at
+`teardownTimeoutMs` (60 s by default), and the run ends at the latest
+15 s after that, saying so (`stop: the rollback did not finish within
+…`) — a Stop never hangs silently. A viewer that started the run
+force-kills it only if it is still alive 5 minutes after the first
+Stop — a safety net for a stuck process, not a wait for the rollback.
+
+**When the stand is NOT given back.** A process that is killed
+(SIGKILL, a crashed machine) runs no teardown at all. Blocks still
+running when `teardownTimeoutMs` (config, default 60 s for all blocks
+together) runs out are cut, and so is whatever a second Stop skips.
+Each such block is reported in the run result as a teardown failure —
+the stand may be left as the test set it.
+
+**The run's own budget is a deadline.** `UNOTEST_MAX_DURATION_MS`
+(default 5 min) ends the test the moment it runs out: an action still
+running is abandoned there, and one that finished past it fails the
+test on that line — the last action included. The abandoned browser
+call lives on until its own timeout or until the context closes; the
+teardown pass runs anyway, on `teardownTimeoutMs`, not on what the test
+left of its budget.
+
+Rules (lint, `teardown-shape`): the label is a string literal; no
+`return` inside, no `break` out of it (a `break` in a loop inside is
+fine); no `teardown` inside a `teardown`. Allowed in tests, flows and
+helpers. A function, parameter or variable of your own named
+`teardown` is reported as `teardown-name-conflict` — rename it.
+
 ---
 
 ## Conventions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/web",
-  "version": "0.43.2",
+  "version": "0.44.0",
   "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.",
   "license": "MIT",
   "publishConfig": {
@@ -80,21 +80,22 @@
     "chokidar": "^4.0.3",
     "dotenv": "^16.4.5",
     "playwright": "1.62.1",
+    "pngjs": "7.0.0",
     "tsx": "^4.19.2",
     "yaml": "^2.6.0",
     "zod": "^3.23.8",
-    "@unotest/core": "^0.43.2",
-    "@unotest/dsl": "^0.43.2",
-    "@unotest/grounder-client": "^0.43.2",
-    "@unotest/protocol": "^0.43.2",
-    "@unotest/viewer": "^0.43.2"
+    "@unotest/dsl": "^0.44.0",
+    "@unotest/core": "^0.44.0",
+    "@unotest/viewer": "^0.44.0",
+    "@unotest/grounder-client": "^0.44.0",
+    "@unotest/protocol": "^0.44.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "javascript-obfuscator": "^4.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.2",
-    "@unotest/judge": "^0.43.2",
-    "@unotest/grounder": "^0.43.2"
+    "@unotest/judge": "^0.44.0",
+    "@unotest/grounder": "^0.44.0"
   }
 }

package/types/unotest-dsl.d.ts

@@ -231,6 +231,13 @@ declare function assertUrl(pattern: string): void;
  */
 declare function assertJudge(locator: Locator, rubric: string): void;
 
+/**
+ * assertScreenshot(name | locator, name?, { maxDiffRatio?, threshold?, mask?, ignore?, fullPage? })
+ *
+ * The page (or an element) against the PNG baseline unotest/e2e/<scenario>.screenshots/<name>.png. A pixel differs when any channel differs by more than threshold (default 32); fails when the share of differing pixels is MORE than maxDiffRatio (default 0). mask: locators, ignore: rectangles in baseline pixels — both left out of the comparison. No baseline: fails and saves the snapshot as a candidate; accept with e2e --update-screenshots. On failure the run keeps expected / actual / diff.
+ */
+declare function assertScreenshot(nameOrLocator: any, nameOrOptions?: any, options?: any): void;
+
 /**
  * assertTrue(condition, message?)
  *
@@ -301,6 +308,27 @@ declare function evaluate(jsBody: string, ...args: unknown[]): any;
  */
 declare function setPage(indexOrTitle: string | number): void;
 
+/**
+ * setViewport({width, height})
+ *
+ * Resize every tab of the browser, and the ones it opens later, without reloading. The scale (deviceScaleFactor) is set in the config, not here.
+ */
+declare function setViewport(size: any): void;
+
+/**
+ * newContext() → number
+ *
+ * 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).
+ */
+declare function newContext(): number;
+
+/**
+ * setContext(index)
+ *
+ * Make browser context `index` active. Each keeps its own tab and frame, so switching back lands where it was.
+ */
+declare function setContext(index: number): void;
+
 /**
  * enterFrame(locator)
  *
@@ -728,6 +756,27 @@ declare function waitForCount(locator: Locator, count: number, options?: any): v
  */
 declare function pause(ms: number): void;
 
+/**
+ * clockFreeze(iso)
+ *
+ * Stop time on the page at an ISO instant: `Date` reads it and no timer fires until clockTick / clockRun. Any instant, past or future.
+ */
+declare function clockFreeze(iso: string): void;
+
+/**
+ * clockTick(ms)
+ *
+ * Move frozen time forward by ms, firing every timer due in it.
+ */
+declare function clockTick(ms: number): void;
+
+/**
+ * clockRun()
+ *
+ * Let time on the page run again from where it stands.
+ */
+declare function clockRun(): void;
+
 /** step(label, [options,] body)
  *
  *  Groups statements under a labelled block. Every direct child of a