@unotest/web 0.45.0 → 0.47.0

package/types/unotest-dsl.d.ts

@@ -92,7 +92,7 @@ interface Locator {
 }
 
 /**
- * click(locator, { force?, timeout?, noWaitAfter? })
+ * click(locator, { force?, timeout?, position?, modifiers?, button?, clickCount? })
  *
  * Click an element.
  */
@@ -134,7 +134,7 @@ declare function hover(locator: Locator, options?: any): void;
 declare function scrollIntoView(locator: Locator, options?: any): void;
 
 /**
- * fill(locator, value, { timeout?, noWaitAfter? })
+ * fill(locator, value, { force?, timeout? })
  *
  * Clear and type a value into an input.
  */
@@ -176,11 +176,25 @@ declare function uploadFile(input: Locator, files: any): void;
 declare function clipboardPaste(target: Locator, text: string): void;
 
 /**
- * assertText(locator, expected, { exact?, timeout? })
+ * assertText(locator, expected, { exact?, not?, timeout? })
  *
- * Element's text equals/contains `expected`.
+ * Element's text equals `expected` (a string; exact: false — contains it) or matches it (a /regex/). {not: true} waits until it no longer does. Empty: assertText(loc, ''); not empty: assertText(loc, '', {not: true}).
  */
-declare function assertText(locator: Locator, text: string, options?: any): void;
+declare function assertText(locator: Locator, text: string | RegExp, options?: any): void;
+
+/**
+ * assertTexts(locator, expected, { exact?, timeout? })
+ *
+ * The locator matches exactly expected.length elements, and element i's text matches expected[i] (string or /regex/, same rules as assertText), in order.
+ */
+declare function assertTexts(locator: Locator, texts: unknown[], options?: any): void;
+
+/**
+ * assertAttribute(locator, name, expected, { exact?, not?, timeout? })
+ *
+ * Polls the attribute `name` until it equals `expected` (exact: false — contains) or matches a /regex/. An absent attribute matches nothing. {not: true} waits until it no longer matches or is gone.
+ */
+declare function assertAttribute(locator: Locator, name: string, value: string | RegExp, options?: any): void;
 
 /**
  * assertVisible(locator, { timeout? })
@@ -220,9 +234,9 @@ declare function assertCount(locator: Locator, count: number): void;
 /**
  * assertUrl(pattern, { timeout? })
  *
- * Current URL contains `pattern`.
+ * Current URL contains `pattern` (a string) or matches it (a /regex/, unanchored). A failure names the pattern as /source/flags.
  */
-declare function assertUrl(pattern: string): void;
+declare function assertUrl(pattern: string | RegExp, options?: any): void;
 
 /**
  * assertJudge(locator, rubric)
@@ -252,6 +266,27 @@ declare function assertEqual(actual: any, expected: any): void;
  */
 declare function assertTrue(condition: boolean, message?: string): void;
 
+/**
+ * assertSchema(value, schema)
+ *
+ * Check a value against a JSON Schema (draft 2020-12), e.g. one your app generates from its zod schemas: assertSchema(res.body, readJson('unotest/fixtures/message.schema.json')). FAILS naming every broken field by path (`/items/0/id`) with what is wrong. External $ref is refused; `format` is not checked.
+ */
+declare function assertSchema(value: any, schema: any): void;
+
+/**
+ * skip(reason, condition?)
+ *
+ * End the test as skipped when the condition is true (always, without one) — it does not apply here: skip('no live API configured', env('LIVE_API') == null). The run reports skipped with the reason, not passed and not failed; teardown blocks already registered still play. A test guard: at the level of the test_* body, next to its steps, not inside one.
+ */
+declare function skip(reason: string, condition?: boolean): void;
+
+/**
+ * setTestTimeout(ms)
+ *
+ * This test's own time budget, counted from its start (Playwright's test.setTimeout). Replaces config testTimeoutMs and UNOTEST_MAX_DURATION_MS for this test. A deadline: an action still running when it runs out is cut, the test fails naming the budget, teardown blocks still play. Only in a test_* body.
+ */
+declare function setTestTimeout(ms: number): void;
+
 /**
  * filter(locator, { hasText?, hasNotText?, has?, hasNot? })
  *
@@ -301,6 +336,27 @@ declare function screenshot(name?: string, options?: any): string;
  */
 declare function note(label: string, value: any): void;
 
+/**
+ * consoleEntries({ level?, since? }) → [{ level, text, url }]
+ *
+ * What the active page wrote to its console, oldest first: `level` is log, info, warn, error or debug. Recorded from the moment the page opened, so act first, then ask. Extension pages (chrome-extension://) too. options: {level} (one level or a list), {since} (epoch ms, from nowMs()).
+ */
+declare function consoleEntries(options?: any): any;
+
+/**
+ * pageErrors({ since? }) → [{ message, stack }]
+ *
+ * Errors the active page threw and nothing caught (an uncaught exception, a rejected promise), oldest first; `stack` is empty when the browser gave none. options: {since} (epoch ms, from nowMs()).
+ */
+declare function pageErrors(options?: any): any;
+
+/**
+ * assertNoConsoleErrors({ includePageErrors?, since? })
+ *
+ * FAIL when the active page logged console errors, or threw uncaught ones (unless {includePageErrors: false}), quoting the first three. With `since` (epoch ms, from nowMs()) only from then on.
+ */
+declare function assertNoConsoleErrors(options?: any): void;
+
 /**
  * evaluate(js, arg?) → any
  *
@@ -357,6 +413,13 @@ declare function closePage(index?: number): void;
  */
 declare function setViewport(size: any): void;
 
+/**
+ * emulateMedia({ reducedMotion?, colorScheme? })
+ *
+ * Change the media features the current tab reports from now on — what matchMedia and CSS @media see: reducedMotion 'reduce' | 'no-preference', colorScheme 'light' | 'dark' | 'no-preference'. This tab only: a tab or popup opened later starts without it.
+ */
+declare function emulateMedia(media: any): void;
+
 /**
  * newContext() → number
  *
@@ -416,9 +479,9 @@ declare function goForward(): void;
 /**
  * waitForUrl(pattern, { timeout? })
  *
- * Wait until the URL contains `pattern` (substring match).
+ * Wait until the URL contains `pattern` (a string, substring match) or matches it (a /regex/, unanchored).
  */
-declare function waitForUrl(pattern: string): void;
+declare function waitForUrl(pattern: string | RegExp, options?: any): void;
 
 /**
  * waitForNavigation({ timeout? })
@@ -476,6 +539,20 @@ declare function isEnabled(locator: Locator): boolean;
  */
 declare function hasAttribute(locator: Locator, name: string): boolean;
 
+/**
+ * computedStyle(locator, property) → string
+ *
+ * The element's computed CSS value, as the browser resolved it: computedStyle(card, "opacity") → "0.5", custom properties too ("--accent"). "" when the property is not set.
+ */
+declare function computedStyle(locator: Locator, property: string): string;
+
+/**
+ * hasAnimation(locator) → bool
+ *
+ * Whether the element or a descendant has an animation still running towards an end. Infinite (spinners) and paused ones do not count — the same rule waitForAnimations waits by.
+ */
+declare function hasAnimation(locator: Locator): boolean;
+
 /**
  * randomFirstName() → string
  *
@@ -574,6 +651,34 @@ declare function parseJson(text: string): any;
  */
 declare function urlParam(url: string, key: string): any;
 
+/**
+ * toNumber(text, { decimal? }) → number
+ *
+ * A number as a page writes it: '1 234,5', '1,234.56', '−12'. Spaces (NBSP too) group digits; with both ',' and '.' the last one is the decimal mark; one mark used twice groups. '1,234' and '1.234' read both ways and FAIL unless {decimal: ',' | '.'} says which. Units and currency ('440px', '€12') FAIL, quoting the input — cut the number out with textMatches first. A number passes through.
+ */
+declare function toNumber(text: any, options?: any): number;
+
+/**
+ * round(n, digits?) → number
+ *
+ * Round to `digits` decimals (0..10, default 0), half away from zero on the decimal as written: round(2.5) → 3, round(-2.5) → -3, round(1.005, 2) → 1.01.
+ */
+declare function round(n: number, digits?: number): number;
+
+/**
+ * formatNumber(n, { locale?, minFractionDigits?, maxFractionDigits? }) → string
+ *
+ * A number as text, via Intl.NumberFormat with digit grouping. Without a locale it is en-US on every machine: formatNumber(1234.5) → '1,234.5'. Another locale's output (its spaces and marks) comes from the ICU of the Node that runs it.
+ */
+declare function formatNumber(n: number, options?: any): string;
+
+/**
+ * env(name) → string | null
+ *
+ * An environment value the test can do without: the ambient environment, unotest/.env or .secrets, as a bare UPPER_SNAKE name reads it — but null when unset instead of failing. For deciding on it: if (env('LIVE_API') == null) { … }. A secret is refused; write its bare name where the value is typed.
+ */
+declare function env(name: string): any;
+
 /**
  * shell(cmd, ...args, options?) → { stdout, stderr, code }
  *
@@ -840,6 +945,13 @@ declare function waitForText(text: string | RegExp, options?: any): void;
  */
 declare function waitForCount(locator: Locator, count: number, options?: any): void;
 
+/**
+ * waitForAnimations(locator, { timeout? })
+ *
+ * Wait until the element and its descendants have no animation still running — a dialog done fading in, a card done sliding. Infinite ones (spinners) and paused ones are not waited for. Default timeout 5000 ms; a timeout names the element and how many were left.
+ */
+declare function waitForAnimations(locator: Locator, options?: any): void;
+
 /**
  * pause(ms)
  *
@@ -878,7 +990,7 @@ declare function clockRun(): void;
 /**
  * mockRoute(glob, response)
  *
- * From now on, requests matching `glob` (a Playwright URL glob: `**\/api/items*`) get a fixed answer: `{status?, body?, headers?, contentType?}` (an object body goes as JSON), `{abort: true, record?}` or `{continue: true}` (to the network). Where several masks match, the one mocked last answers; mocking a mask again replaces its answer. A response to `**\/*` is refused; the site's own page is never aborted. Mocks last until the scenario ends.
+ * From now on, requests matching `glob` (a Playwright URL glob: `**\/api/items*`) get a fixed answer: `{status?, body?, headers?, contentType?}` (an object body goes as JSON), `{abort: true, record?}` or `{continue: true}` (to the network). Where several masks match, the one mocked last answers; mocking a mask again replaces its answer. A response to `**\/*` is refused; the site's own page is never aborted. A mask reaches http(s) and ws(s) only, so an extension's own pages and scripts load under `**\/*`; to mock them, start the mask with their scheme (`chrome-extension://<id>/x.js`). Mocks last until the scenario ends.
  */
 declare function mockRoute(glob: string, response: any): void;