@unotest/web 0.5.0 → 0.6.2

package/guides/dsl-reference.md

@@ -0,0 +1,670 @@
+---
+status: stable
+last_updated: 2026-05-14
+---
+
+# DSL Reference
+
+Complete catalog of the built-in DSL functions registered by
+`src/dsl/default-registry.ts` — what your
+`.js` scenarios in `unotest/e2e/` can call out of the box.
+
+Naming follows Playwright vocab (D-1). Where a function has dual semantics
+(bare call vs. chained on a locator receiver), both shapes are valid:
+
+```js
+click(getByRole('button', {name: 'Save'}))                    // bare
+click(getByRole('button').filter({hasText: 'Save'}))          // chained
+```
+
+A scenario file looks like:
+
+```js
+function test_my_scenario() {
+  //@collapse("Sign in and land on the dashboard")
+  goto('https://example.com');
+  fill(getByLabel('Email'), 'a@b.c');
+  click(getByRole('button', {name: 'Sign in'}));
+  assertUrl('/dashboard');
+  //@endcollapse
+}
+```
+
+> **Every step must sit inside a `//@collapse("...")` block** in a `test_*`
+> entry (the AST validator enforces it; `flow_*` composites and helpers are
+> exempt). The title is the plain-English intent of the group — what the
+> agent reads back to repair a step when a selector drifts. Group by intent,
+> one block per logical chunk; anything is allowed inside a block (nested
+> blocks, control flow, comments).
+
+> **Locator quality matters (D-22).** Prefer `getByTestId` →
+> `getByRole(name)` → `getByLabel` → `getByText` → `locator(css)`. The AST
+> linter (`unotest-web lint`) flags brittle selectors — see
+> `docs/manuals/troubleshooting.md`.
+
+## Categories
+
+- [Builders](#builders) — root locators
+- [Chain helpers](#chain-helpers) — refine a locator
+- [Actions](#actions) — drive interactions
+- [Assertions](#assertions) — wait + verify
+- [Queries](#queries) — read state without asserting
+- [Navigation](#navigation) — load + wait
+- [Multi-context](#multi-context) — multi-tab / iframes
+- [Storage](#storage) — localStorage / cookies
+- [Edge actions](#edge-actions) — drag, upload, paste
+- [Sandbox primitives](#sandbox-primitives) — shell / db / HTTP
+- [Typed getters](#typed-getters) — page properties
+- [`evaluate`](#evaluate) — escape hatch into the page
+- [Logging](#logging)
+
+---
+
+## Matcher arguments — `string | RegExp`
+
+Selectors that map onto Playwright's `string | RegExp` matcher
+parameter (`getByRole({name})`, `getByText`, `getByLabel`,
+`getByPlaceholder`, `getByAltText`, `getByTitle`, `filter({hasText,
+hasNotText})`) accept either:
+
+- A string literal — matched as substring by default, exactly with
+  `{exact: true}`.
+- A regex literal `/pattern/flags` — ECMA-262 5.1 subset.
+
+```js
+getByRole("link", {name: /^Sets/})
+getByText(/Items \d+/i)
+filter({hasText: /done/i})
+```
+
+**Supported regex flags:** `g`, `i`, `m`. Post-ES5 flags (`s u y d v`)
+are rejected at parse time with a message naming the spec they came
+from — write a separate plan if you need them
+(`docs/dsl/regex-literal-es5.md` out-of-scope section).
+
+**Escape rules:** standard ECMA-262 5.1 grammar — `\` introduces
+escape sequences, `[...]` is a character class where `/` does not
+close the literal. No literal line breaks inside a regex body.
+
+---
+
+## Builders
+
+### `locator(selector)`
+
+CSS selector, last-resort escape hatch. Use only when nothing else works
+— the linter discourages this with `lint:deep-css` for `>`-bearing
+selectors.
+
+```js
+locator('.error-banner')
+```
+
+### `getByRole(role, options?)`
+
+ARIA role. `options.name` is the accessible name — string or regex
+(see [Matcher arguments](#matcher-arguments--string--regexp)).
+Substring by default, exact with `{exact: true}`.
+
+```js
+getByRole('button', {name: 'Save'})
+getByRole('heading', {name: 'Welcome', exact: true})
+getByRole('link', {name: /^Sets/})        // regex matcher
+```
+
+### `getByText(text, options?)`
+
+Visible text content.
+
+```js
+getByText('Submit')
+getByText('Save', {exact: true})
+```
+
+### `getByLabel(text, options?)`
+
+Form control by associated `<label>`.
+
+```js
+getByLabel('Email')
+```
+
+### `getByPlaceholder(text, options?)`
+
+Input by its placeholder.
+
+```js
+getByPlaceholder('Search…')
+```
+
+### `getByTestId(id)`
+
+`data-testid` attribute. **Preferred** for stable selection.
+
+```js
+getByTestId('checkout-submit')
+```
+
+### `getByAltText(text, options?)`
+
+Image / area by `alt`.
+
+```js
+getByAltText('Company logo')
+```
+
+### `getByTitle(text, options?)`
+
+Element by its `title` attribute.
+
+```js
+getByTitle('Close')
+```
+
+---
+
+## Chain helpers
+
+Each requires a locator as the receiver / first argument.
+
+### `filter(options)`
+
+Narrow down a locator. `hasText`, `hasNotText`, `has`, `hasNot`.
+
+```js
+getByRole('row').filter({hasText: 'Alice'})
+getByRole('row').filter({has: getByTestId('admin-badge')})
+```
+
+### `first()`, `last()`, `nth(index)`
+
+Pick a single element from a multi-match.
+
+```js
+getByRole('row').first()
+getByRole('row').nth(2)
+```
+
+Prefer `getByRole` + `filter({hasText})` over `nth()` — `nth()`-by-index is
+flagged by `lint:disambig-by-index` because element order in the DOM is
+brittle.
+
+### `contentFrame()`
+
+Treat the matched element as an iframe and return a locator scoped to
+its content document.
+
+```js
+contentFrame(getByTestId('payment-iframe'))
+```
+
+See also [`enterFrame`](#enterframeloc) for the active-context model.
+
+---
+
+## Actions
+
+All wait for actionability (visible + stable + enabled).
+
+### `click(loc, options?)`
+
+```js
+click(getByRole('button', {name: 'Save'}))
+click(getByText('Submit'), {force: true})
+```
+
+**Options:** `force?`, `timeout?`, `position?`, `modifiers?`.
+
+### `doubleClick(loc, options?)`
+
+Same shape as `click`.
+
+### `fill(loc, value, options?)`
+
+Sets the value of an `<input>`, `<textarea>`, or `[contenteditable]`.
+Replaces existing content.
+
+```js
+fill(getByLabel('Email'), 'a@b.c')
+```
+
+### `press(loc, key, options?)`
+
+Send a key press. `key` follows the Playwright/Web key spec:
+`'Enter'`, `'Tab'`, `'ArrowDown'`, `'Control+A'`, etc.
+
+```js
+press(getByLabel('Search'), 'Enter')
+press(getByLabel('Body'), 'Control+A')
+```
+
+### `check(loc, options?)` / `uncheck(loc, options?)`
+
+Idempotent — no-op if already in the target state.
+
+```js
+check(getByRole('checkbox', {name: 'Subscribe'}))
+```
+
+### `hover(loc, options?)`
+
+```js
+hover(getByRole('button', {name: 'Help'}))
+```
+
+### `selectOption(loc, value, options?)`
+
+Native `<select>` only. `value` can be a string, an array of strings, or
+`{label}` / `{value}` / `{index}`.
+
+```js
+selectOption(getByLabel('Country'), 'US')
+selectOption(getByLabel('Tags'), ['a', 'b'])
+```
+
+### `scrollIntoView(loc)`
+
+```js
+scrollIntoView(getByText('Footer'))
+```
+
+---
+
+## Assertions
+
+Each polls until the condition holds or the timeout fires (default 5s;
+override per-call with `{timeout}`). Throw `AssertionError` on failure.
+
+### `assertText(loc, expected, options?)`
+
+Default is exact match. Use `{exact: false}` for substring.
+
+```js
+assertText(getByTestId('success-banner'), 'Saved successfully')
+assertText(getByRole('heading'), 'Welcome', {exact: false})
+```
+
+**Options:** `timeout?`, `exact?` (default `true`).
+
+### `assertVisible(loc, options?)` / `assertHidden(loc, options?)`
+
+```js
+assertVisible(getByTestId('toast'))
+assertHidden(getByTestId('spinner'))
+```
+
+### `assertValue(loc, expected, options?)`
+
+Compares `inputValue()` (`<input>`, `<textarea>`, native `<select>`).
+
+```js
+assertValue(getByLabel('Email'), 'a@b.c')
+```
+
+### `assertCount(loc, expected, options?)`
+
+```js
+assertCount(getByRole('listitem'), 5)
+```
+
+### `assertUrl(pattern, options?)`
+
+Substring match against the active page's URL.
+
+```js
+assertUrl('/dashboard')
+assertUrl('https://example.com/checkout')
+```
+
+### `assertTrue(value, message)`
+
+Generic boolean assert. Throws with `message` when `value` is falsy.
+
+```js
+result = shell('echo', 'ok');
+assertTrue(result.code == 0, 'shell exit code should be 0');
+```
+
+---
+
+## Queries
+
+Read state without asserting. No polling.
+
+### `count(loc)` → `number`
+
+### `textContent(loc)` → `string`
+
+Empty string when the element has no text node (does not throw).
+
+### `inputValue(loc)` → `string`
+
+### `isVisible(loc)` → `boolean`
+
+```js
+n = count(getByRole('row'));
+if (n > 10) {
+  log('too many rows:', n);
+}
+```
+
+---
+
+## Navigation
+
+### `goto(url, options?)`
+
+```js
+goto('https://example.com')
+goto('/dashboard')                          // relative — resolved against the active page
+```
+
+**Options:** `waitUntil?` (`'load'` | `'domcontentloaded'` |
+`'networkidle'`), `timeout?`.
+
+### `reload(options?)` / `goBack(options?)` / `goForward(options?)`
+
+### `waitForUrl(pattern, options?)`
+
+Wait until the active page URL contains `pattern`. Useful after a click
+that triggers navigation.
+
+```js
+click(getByRole('link', {name: 'Settings'}));
+waitForUrl('/settings');
+```
+
+### `waitForNavigation(options?)`
+
+Wait for the next navigation event.
+
+### `waitFor(loc, options?)`
+
+Wait for a locator to be visible (default state).
+
+```js
+waitFor(getByTestId('content-loaded'))
+```
+
+### `waitForText(text, options?)`
+
+Wait for any element on the active page to contain `text`.
+
+### `pause(ms)`
+
+Hard sleep. **Avoid** — the linter flags it (`lint:pause-explicit`). Use
+`waitFor` / `waitForText` / assertion polling instead. Allowed only with
+a justifying `// reason:` comment.
+
+```js
+// reason: third-party widget has no completion signal we can hook into
+pause(500);
+```
+
+---
+
+## Multi-context
+
+### `setPage(index)`
+
+Make tab `index` active. After this, every locator and assertion
+targets that tab. Resets the frame stack — a `setPage` always lands on
+the new tab's root document, never inside a frame inherited from the
+previous tab.
+
+Tabs open asynchronously: a click that triggers `window.open` (often
+after a `fetch`) registers the new tab a beat later. `setPage` waits for
+the tab at `index` to appear, then for its document to load, before
+switching — up to `UNOTEST_DEFAULT_NAVIGATION_TIMEOUT_MS`. You do **not**
+need a manual wait between the click and `setPage`. Only if the tab never
+appears within that budget does it fail with `page index out of range`.
+
+```js
+click(getByRole('link', {name: 'Open in new tab'}));   // opens tab 1
+setPage(1);
+assertText(getByRole('heading'), 'Detail view');
+setPage(0);
+```
+
+**Recording shortcut.** During `explore_step` recording, popup-watcher
+emits `setPage(N);` automatically when a click opens a new tab — the
+generated DSL ends up with the right `setPage` call without the agent
+having to track tab indexes. See
+`docs/auto-page-switch/README.md`
+and `UNOTEST_POPUP_GRACE_MS` in `unotest/.env`.
+
+### `enterFrame(loc)`
+
+Enter an iframe scope. Subsequent calls run inside the frame's document.
+
+```js
+enterFrame(getByTestId('payment-iframe'));
+fill(getByLabel('Card number'), '4242 4242 4242 4242');
+exitFrame();
+```
+
+### `exitFrame()`
+
+Pop one iframe scope. Idempotent at depth 0.
+
+---
+
+## Storage
+
+### `setLocalStorage(key, value)` / `getLocalStorage(key)` → `string`
+
+Returns empty string when key is absent.
+
+```js
+setLocalStorage('feature-flag', 'enabled');
+v = getLocalStorage('feature-flag');
+```
+
+### `setCookie(name, value, options?)` / `getCookie(name)` → `string`
+
+**Options:** `domain?`, `path?`, `expires?`, `httpOnly?`, `secure?`,
+`sameSite?`.
+
+```js
+setCookie('session', 'abc123', {path: '/', sameSite: 'Lax'});
+```
+
+---
+
+## Edge actions
+
+### `dragAndDrop(from, to, options?)`
+
+Uses Playwright `loc.dragTo()` — mouse-event drag. Works for most
+draggables; native HTML5 drag-and-drop (real `DragEvent`) is a known
+limitation — see `KNOWN_ISSUES.md`.
+
+```js
+dragAndDrop(getByTestId('todo-1'), getByTestId('list-done'))
+```
+
+### `uploadFile(loc, paths)`
+
+`paths` can be a single string or an array.
+
+```js
+uploadFile(getByLabel('Avatar'), '/abs/path/to/photo.png')
+uploadFile(getByLabel('Documents'), ['/a.pdf', '/b.pdf'])
+```
+
+### `clipboardPaste(loc, text)`
+
+Focuses the element and sets its value via the input-event path
+(`input` / `change` dispatch). **Does not** dispatch a real
+`ClipboardEvent`, so contenteditable rich-text targets that require the
+real event won't accept formatting.
+
+```js
+clipboardPaste(getByLabel('Notes'), 'pasted text');
+```
+
+---
+
+## Sandbox primitives
+
+Project-agnostic core (D-13, D-27). Consumers wire connection / base-URL
+config in `unotest.config.{js,mjs,ts}` under `sandbox.{shellCwd, database,
+apiBaseUrl}` — the scenario **cannot** override.
+
+```js
+// unotest.config.mjs
+export default {
+  sandbox: {
+    shellCwd: process.cwd(),
+    database: 'postgres://app:app@localhost:5432/myapp_test',
+    apiBaseUrl: 'http://localhost:3000/api',
+  },
+};
+```
+
+### `shell(cmd, ...args)` → `{stdout, stderr, code}`
+
+`execFile`-style — **no shell interpretation**, no `&&` / `|` /
+redirection. cwd from `sandbox.shellCwd`.
+
+```js
+out = shell('pnpm', 'db:create-user', 'alice');
+assertTrue(out.code == 0, out.stderr);
+```
+
+### `dbQuery(sql, ...params)` → `rows[]`
+
+Parameterized SELECT. Driver picked by URL scheme:
+
+- `postgres://…` / `postgresql://…` — needs `pg` peer dep
+- `mysql://…` — needs `mysql2`
+- `sqlite:…` / `*.db` / `*.sqlite` — needs `better-sqlite3`
+
+```js
+rows = dbQuery('select id from users where email = ?', 'a@b.c');
+```
+
+### `dbExec(sql, ...params)` → `number` (affected rows)
+
+INSERT / UPDATE / DELETE.
+
+```js
+dbExec('delete from sessions where user_id = ?', userId);
+```
+
+### `apiCall(method, path, body?, headers?)` → `{status, body, headers}`
+
+HTTP via global `fetch`. **`path` must be relative** (starts with `/`) —
+absolute URLs throw to prevent scenarios from hitting arbitrary hosts.
+
+```js
+res = apiCall('POST', '/auth/login', {email: 'a@b.c', password: 'x'});
+assertTrue(res.status == 200, 'login failed');
+```
+
+---
+
+## Typed getters
+
+Read page properties directly into a local variable.
+
+### `getAttribute(loc, name)` → `string`
+
+```js
+href = getAttribute(getByRole('link', {name: 'Docs'}), 'href');
+```
+
+### `getInnerText(loc)` → `string`
+
+Like `textContent` but trimmed and rendered (display-aware).
+
+### `getInputValue(loc)` → `string`
+
+Identical to `inputValue`; kept under typed-getters for symmetry with
+agent prompts that prefer the `get*` prefix.
+
+### `getTitle()` → `string`
+
+Active page title.
+
+### `getUrl()` → `string`
+
+Active page URL.
+
+---
+
+## `evaluate`
+
+`evaluate(js, ...args)` — escape hatch. Runs `js` in the active page
+context. Discouraged (`lint:evaluate-discouraged`) — prefer typed
+getters or the action API.
+
+```js
+height = evaluate(`document.documentElement.scrollHeight`);
+```
+
+Multi-arg form (args destructured in the page-side function):
+
+```js
+result = evaluate(
+  `function([a, b]) { return window.myApp.compute(a, b); }`,
+  10, 20
+);
+```
+
+Backticks are **raw** — `${…}` interpolation is rejected at parse time
+(see `vendor/dsl/EXTENSIONS.md`).
+
+---
+
+## Logging
+
+### `log(...args)`
+
+Routes through the runtime's `Logger.info`. Non-string args are
+`JSON.stringify`'d.
+
+```js
+log('user id:', userId);
+```
+
+---
+
+## Variables, control flow, types
+
+The DSL is JavaScript-shaped but parsed by a small AST engine
+(`vendor/dsl/`), not V8. What's supported in scenario files:
+
+- **`function test_*(): { … }`** — scenario entry; each top-level
+  `function test_*` is a separately runnable test.
+- **Assignments** — `name = expression;` (no `let`/`const`/`var`).
+- **`if` / `else`**, **`while`**, **`for (a; b; c)`**,
+  **`do { … } while (cond)`**, **`break`**, **`continue`**.
+- **Increment / decrement** — `i++`, `i--`, `++i`, `--i` (numeric
+  variables only; postfix returns the old value, prefix the new).
+- **Object / array literals** — `{name: 'x'}`, `[1, 2, 3]`.
+- **Member access** — `row.email`, `result.headers['content-type']`.
+- **Method chains** — `getByRole('row').filter({hasText:'X'}).click()`.
+- **Backticks** — multi-line raw strings, no `${}` interpolation.
+- **Booleans, numbers, strings, `null`**.
+
+Not supported (and intentionally so): 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.
+
+See `vendor/dsl/EXTENSIONS.md` for the
+exact grammar deltas from the upstream parser.
+
+---
+
+## Conventions
+
+- **Snake-case test names** — `function test_login_happy_path()`.
+- **One scenario file = one feature.** Multiple `test_*` entries are
+  fine when they share a feature surface.
+- **Helpers stay in `unotest/e2e/_helpers/`** — these are project-owned,
+  not part of the core surface. Use sandbox primitives there.
+- **Lint before you ship** — `npx @unotest/web lint` runs the AST
+  linter across `unotest/e2e/**/*.js`.