@unotest/web 0.16.0 → 0.18.0

package/types/unotest-dsl.d.ts

@@ -0,0 +1,714 @@
+// GENERATED by scripts/build-dsl-types.ts from the DSL vocabulary — do not edit.
+// Ambient declarations for the unotest DSL: every scenario function is a
+// global, so the editor resolves calls, shows signatures and hover docs.
+
+/** A reference to element(s) on the page. Produced by the builders
+ *  (getByRole, getByTestId, …) and refined by chaining. */
+interface Locator {
+  /**
+   * filter(locator, { hasText?, hasNotText?, has?, hasNot? })
+   *
+   * Keep matches by contained text or a nested child locator.
+   */
+  filter(options: any): Locator;
+  /**
+   * first(locator)
+   *
+   * First match.
+   */
+  first(): Locator;
+  /**
+   * last(locator)
+   *
+   * Last match.
+   */
+  last(): Locator;
+  /**
+   * nth(locator, index)
+   *
+   * The N-th match (0-indexed). Index-only refinement is fragile (linter info).
+   */
+  nth(index: number): Locator;
+  /**
+   * randomNth(locator)
+   *
+   * A random one of the matches — for flows where any item will do.
+   */
+  randomNth(): Locator;
+  /**
+   * locator(css)
+   *
+   * Match by raw CSS selector. Last resort — the linter warns on deep/brittle CSS.
+   */
+  locator(selector: string): Locator;
+  /**
+   * getByRole(role, { name?, exact? })
+   *
+   * Match by ARIA role + accessible name. `name` accepts a string or `/regex/`.
+   */
+  getByRole(role: string, options?: any): Locator;
+  /**
+   * getByText(text, { exact? })
+   *
+   * Match by visible text content.
+   */
+  getByText(text: string | RegExp, options?: any): Locator;
+  /**
+   * getByLabel(text, { exact? })
+   *
+   * Match a form control by its associated label.
+   */
+  getByLabel(text: string | RegExp, options?: any): Locator;
+  /**
+   * getByPlaceholder(text, { exact? })
+   *
+   * Match an input by its placeholder.
+   */
+  getByPlaceholder(text: string | RegExp, options?: any): Locator;
+  /**
+   * getByAltText(text, { exact? })
+   *
+   * Match an image by its `alt` text.
+   */
+  getByAltText(text: string | RegExp, options?: any): Locator;
+  /**
+   * getByTitle(text, { exact? })
+   *
+   * Match by `title` attribute.
+   */
+  getByTitle(text: string | RegExp, options?: any): Locator;
+  /**
+   * getByTestId(id)
+   *
+   * Match by `data-testid`. Most stable — prefer this.
+   */
+  getByTestId(id: string): Locator;
+  /**
+   * contentFrame(locator)
+   *
+   * Resolve an `<iframe>` element to its content frame.
+   */
+  contentFrame(frame?: Locator): Locator;
+}
+
+/**
+ * click(locator, { force?, timeout?, noWaitAfter? })
+ *
+ * Click an element.
+ */
+declare function click(locator: Locator, options?: any): void;
+
+/**
+ * doubleClick(locator, { force?, timeout? })
+ *
+ * Double-click an element.
+ */
+declare function doubleClick(locator: Locator, options?: any): void;
+
+/**
+ * check(locator, { force?, timeout? })
+ *
+ * Check a checkbox/radio.
+ */
+declare function check(locator: Locator, options?: any): void;
+
+/**
+ * uncheck(locator, { force?, timeout? })
+ *
+ * Uncheck a checkbox.
+ */
+declare function uncheck(locator: Locator, options?: any): void;
+
+/**
+ * hover(locator, { force?, timeout? })
+ *
+ * Hover over an element.
+ */
+declare function hover(locator: Locator, options?: any): void;
+
+/**
+ * scrollIntoView(locator)
+ *
+ * Scroll an element into the viewport.
+ */
+declare function scrollIntoView(locator: Locator, options?: any): void;
+
+/**
+ * fill(locator, value, { timeout?, noWaitAfter? })
+ *
+ * Clear and type a value into an input.
+ */
+declare function fill(locator: Locator, text: string, options?: any): void;
+
+/**
+ * press(locator, key, { delay?, timeout? })
+ *
+ * Press a key (e.g. 'Enter', 'Control+A').
+ */
+declare function press(locator: Locator, key: string, options?: any): void;
+
+/**
+ * selectOption(locator, value, { timeout? })
+ *
+ * Select option(s) in a `<select>`. `value` is a string or string[].
+ */
+declare function selectOption(locator: Locator, value: any): void;
+
+/**
+ * dragAndDrop(from, to, { force?, timeout? })
+ *
+ * Drag one element onto another. Uses synthetic mouse events (not native HTML5 DragEvent).
+ */
+declare function dragAndDrop(source: Locator, target: Locator): void;
+
+/**
+ * uploadFile(locator, files)
+ *
+ * Set files on a file input. `files` is a path or path[].
+ */
+declare function uploadFile(input: Locator, files: any): void;
+
+/**
+ * clipboardPaste(locator, text)
+ *
+ * Paste text. Synthetic, not a native ClipboardEvent.
+ */
+declare function clipboardPaste(target: Locator, text: string): void;
+
+/**
+ * assertText(locator, expected, { exact?, timeout? })
+ *
+ * Element's text equals/contains `expected`.
+ */
+declare function assertText(locator: Locator, text: string, options?: any): void;
+
+/**
+ * assertVisible(locator, { timeout? })
+ *
+ * Element is visible.
+ */
+declare function assertVisible(locator: Locator): void;
+
+/**
+ * assertHidden(locator, { timeout? })
+ *
+ * Element is hidden or detached.
+ */
+declare function assertHidden(locator: Locator): void;
+
+/**
+ * assertNeverAppears(locator, { withinMs })
+ *
+ * Negative window assert: FAIL the moment the locator becomes visible; pass when the whole window elapsed clean. withinMs required; the step always costs that long.
+ */
+declare function assertNeverAppears(locator: Locator, options: any): void;
+
+/**
+ * assertValue(locator, expected, { timeout? })
+ *
+ * Input's value equals `expected`. On a checkbox/radio/switch: its checked state — pass 'true' or 'false'.
+ */
+declare function assertValue(locator: Locator, value: string): void;
+
+/**
+ * assertCount(locator, expected, { timeout? })
+ *
+ * Number of matches equals `expected`.
+ */
+declare function assertCount(locator: Locator, count: number): void;
+
+/**
+ * assertUrl(pattern, { timeout? })
+ *
+ * Current URL contains `pattern`.
+ */
+declare function assertUrl(pattern: string): void;
+
+/**
+ * assertTrue(condition, message?)
+ *
+ * Assert a boolean condition.
+ */
+declare function assertTrue(condition: boolean, message?: string): void;
+
+/**
+ * filter(locator, { hasText?, hasNotText?, has?, hasNot? })
+ *
+ * Keep matches by contained text or a nested child locator.
+ */
+declare function filter(receiver: Locator, options: any): Locator;
+
+/**
+ * first(locator)
+ *
+ * First match.
+ */
+declare function first(receiver: Locator): Locator;
+
+/**
+ * last(locator)
+ *
+ * Last match.
+ */
+declare function last(receiver: Locator): Locator;
+
+/**
+ * nth(locator, index)
+ *
+ * The N-th match (0-indexed). Index-only refinement is fragile (linter info).
+ */
+declare function nth(receiver: Locator, index: number): Locator;
+
+/**
+ * randomNth(locator)
+ *
+ * A random one of the matches — for flows where any item will do.
+ */
+declare function randomNth(receiver: Locator): Locator;
+
+/**
+ * screenshot(name?, { fullPage? }) → string
+ *
+ * Capture the active page into the run's artifact dir; returns the project-relative path.
+ */
+declare function screenshot(name?: string, options?: any): string;
+
+/**
+ * evaluate(js, ...args) → any
+ *
+ * Run raw JS in the page context. Last resort — prefer typed helpers. Returns JSON-serializable values only.
+ */
+declare function evaluate(jsBody: string, ...args: unknown[]): any;
+
+/**
+ * setPage(index)
+ *
+ * Switch the active tab/page by index (0-based).
+ */
+declare function setPage(indexOrTitle: string | number): void;
+
+/**
+ * enterFrame(locator)
+ *
+ * Scope subsequent calls to an iframe (persists until exitFrame).
+ */
+declare function enterFrame(frame: Locator): void;
+
+/**
+ * exitFrame()
+ *
+ * Exit the innermost iframe scope.
+ */
+declare function exitFrame(): void;
+
+/**
+ * goto(url, { waitUntil?, timeout? })
+ *
+ * Navigate to a URL. `waitUntil`: 'load' | 'domcontentloaded' | 'networkidle'. Relative paths resolve against `baseUrl`.
+ */
+declare function goto(url: string, options?: any): void;
+
+/**
+ * reload({ waitUntil?, timeout? })
+ *
+ * Reload the current page.
+ */
+declare function reload(options?: any): void;
+
+/**
+ * goBack({ timeout? })
+ *
+ * Navigate back in history.
+ */
+declare function goBack(): void;
+
+/**
+ * goForward({ timeout? })
+ *
+ * Navigate forward in history.
+ */
+declare function goForward(): void;
+
+/**
+ * waitForUrl(pattern, { timeout? })
+ *
+ * Wait until the URL contains `pattern` (substring match).
+ */
+declare function waitForUrl(pattern: string): void;
+
+/**
+ * waitForNavigation({ timeout? })
+ *
+ * Wait for the next navigation event.
+ */
+declare function waitForNavigation(options?: any): void;
+
+/**
+ * count(locator) → number
+ *
+ * Number of matching elements.
+ */
+declare function count(locator: Locator): number;
+
+/**
+ * textContent(locator) → string
+ *
+ * Text content ("" if none).
+ */
+declare function textContent(locator: Locator): string;
+
+/**
+ * inputValue(locator) → string
+ *
+ * Current input value.
+ */
+declare function inputValue(locator: Locator): string;
+
+/**
+ * isVisible(locator) → boolean
+ *
+ * Whether the element is visible.
+ */
+declare function isVisible(locator: Locator): boolean;
+
+/**
+ * isDisabled(locator) → boolean
+ *
+ * Whether the element is disabled (native :disabled incl. fieldset, or aria-disabled).
+ */
+declare function isDisabled(locator: Locator): boolean;
+
+/**
+ * isEnabled(locator) → boolean
+ *
+ * Negation of isDisabled.
+ */
+declare function isEnabled(locator: Locator): boolean;
+
+/**
+ * hasAttribute(locator, name) → boolean
+ *
+ * Whether the attribute is present at all — the honest probe for boolean attributes.
+ */
+declare function hasAttribute(locator: Locator, name: string): boolean;
+
+/**
+ * randomFirstName() → string
+ *
+ * Random first name for fixture data.
+ */
+declare function randomFirstName(): string;
+
+/**
+ * randomLastName() → string
+ *
+ * Random last name for fixture data.
+ */
+declare function randomLastName(): string;
+
+/**
+ * randomEmail() → string
+ *
+ * Random unique email address for fixture data.
+ */
+declare function randomEmail(): string;
+
+/**
+ * randomText(length) → string
+ *
+ * Lorem-style prose cut to `length` characters.
+ */
+declare function randomText(length: number): string;
+
+/**
+ * randomWord(length?) → string
+ *
+ * Random lowercase letters (default 8) — digit-free unique markers.
+ */
+declare function randomWord(length?: number): string;
+
+/**
+ * json(value) → string
+ *
+ * Serialize any value to a JSON string — readable assert messages for API/data steps: assertTrue(res.status == 202, json(res.body)).
+ */
+declare function json(value: any): string;
+
+/**
+ * textContains(haystack, needle) → boolean
+ *
+ * Substring probe for strings (shell stdout, api bodies): assertTrue(textContains(out.stdout, 'ready'), out.stderr).
+ */
+declare function textContains(haystack: string, needle: string): boolean;
+
+/**
+ * textJoin(parts) → string
+ *
+ * Concatenate an array of parts (numbers coerced). `+` with a string literal also works; only literal-free `a + b` string addition is rejected (looks like arithmetic).
+ */
+declare function textJoin(parts: unknown[]): string;
+
+/**
+ * nowMs() → number
+ *
+ * Current epoch milliseconds.
+ */
+declare function nowMs(): number;
+
+/**
+ * today() → string
+ *
+ * Local date as YYYY-MM-DD.
+ */
+declare function today(): string;
+
+/**
+ * daysFromNow(n) → string
+ *
+ * Local date n days ahead (negative = past) as YYYY-MM-DD.
+ */
+declare function daysFromNow(days: number): string;
+
+/**
+ * shell(cmd, ...args, options?) → { stdout, stderr, code }
+ *
+ * Run a binary (execFile, no shell interpretation). cwd from config `shellCwd`. Non-zero exit FAILS the step unless {allowNonZero: true}; wall-clock budget {timeoutMs} (default 120s).
+ */
+declare function shell(cmd: string, ...args: unknown[]): any;
+
+/**
+ * waitForFile(path, pattern?, options?) → string
+ *
+ * Poll a file (relative to config `shellCwd`) until it exists / contains a substring or regex, then return its content. options: {timeoutMs} (default 20s). The waitForText of background processes.
+ */
+declare function waitForFile(path: string, pattern?: any, options?: any): string;
+
+/**
+ * assertNoFile(path, pattern?, { withinMs })
+ *
+ * Mirror of waitForFile with inverted polarity: FAIL the moment the file exists (and matches pattern); pass when the window elapsed clean. withinMs required.
+ */
+declare function assertNoFile(path: string, pattern?: any, options?: any): void;
+
+/**
+ * waitForJsonLine(path, filter, options?) → object
+ *
+ * Wait for a LINE of a JSONL file that matches every key of `filter` (strict equality, dot paths for nesting), then return it parsed. What a substring cannot express: JSON key order is not guaranteed. options: {timeoutMs} (default 20s).
+ */
+declare function waitForJsonLine(path: string, filter: any, options?: any): any;
+
+/**
+ * assertNoJsonLine(path, filter, { withinMs })
+ *
+ * Negative twin of waitForJsonLine: FAIL the moment a matching line appears; pass when the window elapsed clean. withinMs required.
+ */
+declare function assertNoJsonLine(path: string, filter: any, options?: any): void;
+
+/**
+ * waitForFileCount(path, pattern, count, options?) → number
+ *
+ * Wait until AT LEAST `count` lines match, then return how many there are. `pattern` is a substring, a regex or a JSON key filter. options: {timeoutMs} (default 20s).
+ */
+declare function waitForFileCount(path: string, pattern: any, count: number, options?: any): number;
+
+/**
+ * assertFileCount(path, pattern, count)
+ *
+ * Snapshot count of matching lines, strict equality — 'exactly N happened'. Pair it with waitForFileCount, which awaits the window.
+ */
+declare function assertFileCount(path: string, pattern: any, count: number): void;
+
+/**
+ * dbQuery(sql, ...params) → rows[]
+ *
+ * Parameterized SELECT. Dialect from the config `database` URL (postgres/mysql/sqlite).
+ */
+declare function dbQuery(sql: string, ...args: unknown[]): any;
+
+/**
+ * dbExec(sql, ...params) → number
+ *
+ * Parameterized INSERT/UPDATE/DELETE. Returns affected row count.
+ */
+declare function dbExec(sql: string, ...args: unknown[]): number;
+
+/**
+ * apiCall(method, path, body?, headers?) → { status, body, headers }
+ *
+ * HTTP call. `path` is relative — base is the config `apiBaseUrl`. Multipart: pass upload(...) as the body.
+ */
+declare function apiCall(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS", path: string, body?: any, headers?: any, options?: any): any;
+
+/**
+ * upload(path, options?) → UploadRef
+ *
+ * Multipart marker for apiCall's body (options: field, fields). Path is relative to the project root / config `uploadDir`.
+ */
+declare function upload(path: string, options?: any): any;
+
+/**
+ * locator(css)
+ *
+ * Match by raw CSS selector. Last resort — the linter warns on deep/brittle CSS.
+ */
+declare function locator(selector: string): Locator;
+
+/**
+ * getByRole(role, { name?, exact? })
+ *
+ * Match by ARIA role + accessible name. `name` accepts a string or `/regex/`.
+ */
+declare function getByRole(role: string, options?: any): Locator;
+
+/**
+ * getByText(text, { exact? })
+ *
+ * Match by visible text content.
+ */
+declare function getByText(text: string | RegExp, options?: any): Locator;
+
+/**
+ * getByLabel(text, { exact? })
+ *
+ * Match a form control by its associated label.
+ */
+declare function getByLabel(text: string | RegExp, options?: any): Locator;
+
+/**
+ * getByPlaceholder(text, { exact? })
+ *
+ * Match an input by its placeholder.
+ */
+declare function getByPlaceholder(text: string | RegExp, options?: any): Locator;
+
+/**
+ * getByAltText(text, { exact? })
+ *
+ * Match an image by its `alt` text.
+ */
+declare function getByAltText(text: string | RegExp, options?: any): Locator;
+
+/**
+ * getByTitle(text, { exact? })
+ *
+ * Match by `title` attribute.
+ */
+declare function getByTitle(text: string | RegExp, options?: any): Locator;
+
+/**
+ * getByTestId(id)
+ *
+ * Match by `data-testid`. Most stable — prefer this.
+ */
+declare function getByTestId(id: string): Locator;
+
+/**
+ * contentFrame(locator)
+ *
+ * Resolve an `<iframe>` element to its content frame.
+ */
+declare function contentFrame(frame?: Locator): Locator;
+
+/**
+ * getAttribute(locator, name) → string
+ *
+ * Attribute value ("" if missing). Boolean attributes (disabled, readonly) read "" whether present or absent — use isDisabled / hasAttribute for those.
+ */
+declare function getAttribute(locator: Locator, attribute: string): string;
+
+/**
+ * getInnerText(locator) → string
+ *
+ * Rendered inner text.
+ */
+declare function getInnerText(locator: Locator): string;
+
+/**
+ * getInputValue(locator) → string
+ *
+ * Input value (alias of inputValue).
+ */
+declare function getInputValue(locator: Locator): string;
+
+/**
+ * getTitle() → string
+ *
+ * Document title of the active page.
+ */
+declare function getTitle(): string;
+
+/**
+ * getUrl() → string
+ *
+ * URL of the active page.
+ */
+declare function getUrl(): string;
+
+/**
+ * log(...args)
+ *
+ * Write to the run trace.
+ */
+declare function log(message: any, ...args: unknown[]): void;
+
+/**
+ * setLocalStorage(key, value)
+ *
+ * Set a localStorage item.
+ */
+declare function setLocalStorage(key: string, value: string): void;
+
+/**
+ * getLocalStorage(key) → string
+ *
+ * Read a localStorage item ("" if missing).
+ */
+declare function getLocalStorage(key: string): string;
+
+/**
+ * setCookie(name, value, options?)
+ *
+ * Set a cookie (options: path, domain, expires, httpOnly, secure, sameSite).
+ */
+declare function setCookie(name: string, value: string, options?: any): void;
+
+/**
+ * getCookie(name) → string
+ *
+ * Read a cookie value ("" if missing).
+ */
+declare function getCookie(name: string): string;
+
+/**
+ * waitFor(locator, { state?, timeout? })
+ *
+ * Wait for an element state: DOM presence ('visible' default, 'hidden', 'attached', 'detached') or interaction ('enabled' / 'disabled' — same probe as isEnabled, so aria-disabled counts).
+ */
+declare function waitFor(locator: Locator, options?: any): void;
+
+/**
+ * waitForText(text, { first?, timeout? })
+ *
+ * Wait until `text` appears anywhere on the page. `first: true` waits for the first VISIBLE occurrence when the text is duplicated (otherwise duplicates fail strict mode).
+ */
+declare function waitForText(text: string | RegExp, options?: any): void;
+
+/**
+ * waitForCount(locator, count, { exact?, timeout? })
+ *
+ * Poll until the locator matches AT LEAST `count` elements (`{exact: true}` for exactly). Default timeout 5000 ms.
+ */
+declare function waitForCount(locator: Locator, count: number, options?: any): void;
+
+/**
+ * pause(ms)
+ *
+ * Explicit delay. Discouraged — the linter wants a `// reason:` comment. Prefer a `waitFor*`.
+ */
+declare function pause(ms: number): void;
+
+/** step(label, body)
+ *
+ *  Groups statements under a labelled block. Every direct child of a
+ *  test_* function must sit inside a step(...). */
+declare function step(label: string, body: () => void): void;