very-happy-dom 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+[Compare changes](https://github.com/stacksjs/very-happy-dom/compare/v0.2.0...HEAD)
+
+## 🚀 Features
+
+- **matchers**: add the aria, CSS and property matchers ([7e203bd](https://github.com/stacksjs/very-happy-dom/commit/7e203bd)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1618](https://github.com/stacksjs/very-happy-dom/issues/1618), [#1608](https://github.com/stacksjs/very-happy-dom/issues/1608), [#1602](https://github.com/stacksjs/very-happy-dom/issues/1602))
+- **page**: add dialog events for alert, confirm and prompt ([5de9417](https://github.com/stacksjs/very-happy-dom/commit/5de9417)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1612](https://github.com/stacksjs/very-happy-dom/issues/1612), [#1602](https://github.com/stacksjs/very-happy-dom/issues/1602))
+- **locator**: add filter({has}), or() and and() ([c10931d](https://github.com/stacksjs/very-happy-dom/commit/c10931d)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1619](https://github.com/stacksjs/very-happy-dom/issues/1619))
+- **locator**: add boundingBox and scrollIntoViewIfNeeded ([9f9055b](https://github.com/stacksjs/very-happy-dom/commit/9f9055b)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1609](https://github.com/stacksjs/very-happy-dom/issues/1609), [#1600](https://github.com/stacksjs/very-happy-dom/issues/1600), [#1617](https://github.com/stacksjs/very-happy-dom/issues/1617))
+- **page**: add setContent, and fix the document parse it exposed ([a5e2bd4](https://github.com/stacksjs/very-happy-dom/commit/a5e2bd4)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1610](https://github.com/stacksjs/very-happy-dom/issues/1610), [#1595](https://github.com/stacksjs/very-happy-dom/issues/1595))
+- **locator**: add the form-control actions ([d1068b0](https://github.com/stacksjs/very-happy-dom/commit/d1068b0)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1608](https://github.com/stacksjs/very-happy-dom/issues/1608), [#1615](https://github.com/stacksjs/very-happy-dom/issues/1615), [#1616](https://github.com/stacksjs/very-happy-dom/issues/1616))
+- **locator**: add evaluate, evaluateAll and the all*Text helpers ([3549710](https://github.com/stacksjs/very-happy-dom/commit/3549710)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1607](https://github.com/stacksjs/very-happy-dom/issues/1607))
+- **page**: add the waitFor* family for page events ([4039cb7](https://github.com/stacksjs/very-happy-dom/commit/4039cb7)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1606](https://github.com/stacksjs/very-happy-dom/issues/1606))
+
+## 🐛 Bug Fixes
+
+- **dom**: collapse whitespace in innerText, and resolve its visibility ([6589fe0](https://github.com/stacksjs/very-happy-dom/commit/6589fe0)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1614](https://github.com/stacksjs/very-happy-dom/issues/1614), [#1600](https://github.com/stacksjs/very-happy-dom/issues/1600), [#1607](https://github.com/stacksjs/very-happy-dom/issues/1607))
+- **css**: apply @media rules, and add emulateMedia ([f67bf7a](https://github.com/stacksjs/very-happy-dom/commit/f67bf7a)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1611](https://github.com/stacksjs/very-happy-dom/issues/1611), [#1600](https://github.com/stacksjs/very-happy-dom/issues/1600))
+- **page**: make waitForSelector throw on timeout ([32c5f0e](https://github.com/stacksjs/very-happy-dom/commit/32c5f0e)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1605](https://github.com/stacksjs/very-happy-dom/issues/1605))
+- **keyboard**: parse modifier combinations and populate code ([ada3489](https://github.com/stacksjs/very-happy-dom/commit/ada3489)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1615](https://github.com/stacksjs/very-happy-dom/issues/1615))
+- **aria**: treat a declared zero size as hidden ([480899c](https://github.com/stacksjs/very-happy-dom/commit/480899c)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1617](https://github.com/stacksjs/very-happy-dom/issues/1617), [#1604](https://github.com/stacksjs/very-happy-dom/issues/1604), [#1601](https://github.com/stacksjs/very-happy-dom/issues/1601))
+- **aria**: read checked state through aria-checked ([524698f](https://github.com/stacksjs/very-happy-dom/commit/524698f)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1616](https://github.com/stacksjs/very-happy-dom/issues/1616))
+- **routing**: stop setRequestInterception(false) from killing routes ([7537569](https://github.com/stacksjs/very-happy-dom/commit/7537569)) _(by glennmichael123 <gtorregosa@gmail.com>)_ ([#1613](https://github.com/stacksjs/very-happy-dom/issues/1613))
+
+## Contributors
+
+- _glennmichael123 <gtorregosa@gmail.com>_
+
 [Compare changes](https://github.com/stacksjs/very-happy-dom/compare/v0.1.12...HEAD)
 
 ## 🚀 Features

package/README.md

@@ -146,11 +146,37 @@ The one-shot rewrite — `expect(await page.getByRole('alert').textContent()).to
 drains is a race. `.not` waits for the opposite to become true rather than
 inverting a single sample.
 
+Checked state is read through ARIA, so a design system's
+`<div role="checkbox" aria-checked>` answers truthfully — `isChecked()`,
+`getByRole({ checked })`, `check()`/`uncheck()` and `toBeChecked()` all go through
+one predicate. `locator.checkedState()` returns `'mixed'` for a tri-state control,
+and `toBeChecked({ indeterminate: true })` asserts it. `toBeChecked()` refuses an
+element with no checked state rather than answering `false`, so
+`.not.toBeChecked()` cannot pass against a plain `<div>`.
+
 Locators: `toBeAttached`, `toBeVisible`, `toBeHidden`, `toHaveCount`,
-`toHaveText`, `toContainText`, `toHaveValue`, `toHaveAttribute`, `toHaveClass`,
-`toBeEnabled`, `toBeDisabled`, `toBeChecked`, `toBeEditable`, `toBeFocused`,
-`toBeEmpty`. Pages: `toHaveURL`, `toHaveTitle`. Each takes an optional
-`{ timeout }`, defaulting to `page.setDefaultTimeout()`.
+`toHaveText`, `toContainText`, `toHaveValue`, `toHaveValues`, `toHaveAttribute`,
+`toHaveClass`, `toHaveId`, `toHaveCSS`, `toHaveJSProperty`, `toHaveRole`,
+`toHaveAccessibleName`, `toHaveAccessibleDescription`, `toBeEnabled`,
+`toBeDisabled`, `toBeChecked`, `toBeEditable`, `toBeFocused`, `toBeEmpty`.
+Pages: `toHaveURL`, `toHaveTitle`. Each takes an optional `{ timeout }`,
+defaulting to `page.setDefaultTimeout()`.
+
+`toHaveRole` and `toHaveAccessibleName` assert what `getByRole` queries on, which
+is how a failing role query becomes diagnosable. `toHaveCSS` compares values **as
+the engine reports them**, so `'red'` will not match a computed `'rgb(255, 0, 0)'`
+— use a RegExp. `toHaveJSProperty` takes a path, so `validity.valueMissing` works.
+
+`toBeInViewport` is deliberately absent: with no layout pass a bounding box has no
+position, so it could only ever answer "yes".
+
+An element is hidden by `display: none`, `visibility: hidden`, the `hidden`
+attribute, or a **declared** zero size — `height: 0`, `max-height: 0` and the
+like, which is how a closed accordion or drawer is built when the author wants a
+transition. Declared is the operative word: with no layout pass an element nobody
+sized also measures `0 x 0`, so a zero box means *unknown* rather than
+*collapsed*, and only a declaration is trusted. That is narrower than
+Playwright's non-empty-bounding-box rule, deliberately.
 
 Locator actions auto-wait on the same terms — present, rendered and not
 disabled — and `locator.waitFor({ state })` covers `attached`, `detached`,
@@ -158,6 +184,196 @@ disabled — and `locator.waitFor({ state })` covers `attached`, `detached`,
 stable (not mid-animation) and receives-events (not covered by another element).
 Both need a layout pass.
 
+### Rendered Text
+
+`innerText` returns text as rendered: hidden subtrees left out, whitespace
+collapsed, block elements separated by newlines, `<br>` honoured. Visibility is
+resolved through the cascade, so a `display: none` from a stylesheet is excluded —
+not only an inline one. `white-space: pre`, `pre-wrap` and `break-spaces` keep
+their text verbatim, `pre-line` keeps newlines, and a `<pre>` element counts as
+`pre` with no rule needed.
+
+`textContent` is unchanged: raw, untrimmed, uncollapsed.
+
+```typescript
+document.body.innerHTML = '<p>  Save   changes  </p>'
+document.querySelector('p').textContent   // '  Save   changes  '
+document.querySelector('p').innerText     // 'Save changes'
+```
+
+### Dialogs
+
+```typescript
+page.on('dialog', dialog => dialog.accept())          // confirm() returns true
+page.on('dialog', dialog => dialog.accept('Ridge'))   // prompt() returns 'Ridge'
+page.on('dialog', dialog => dialog.dismiss())         // false / null
+```
+
+Without a handler every dialog is dismissed, which is Playwright's default and
+what the old hardcoded `false`/`null` did — so nothing changes unless you opt in.
+`dialog` carries `type`, `message` and `defaultValue`, so a test can assert *which*
+dialog appeared, including an `alert()`.
+
+The decision must be made **synchronously**: `confirm()` is a synchronous DOM API,
+so a handler that awaits before deciding answers after the page has already acted
+on the default. That throws rather than letting the wrong answer through.
+`dialog.accept()` records the decision immediately, so `async dialog =>
+await dialog.accept()` is fine — it is awaiting *before* deciding that is not.
+
+### Combining Locators
+
+```typescript
+// Pick a row by what is inside it, then act within that row
+const row = page.getByRole('row').filter({ has: page.getByText('Ridge Loop') })
+await row.getByRole('button', { name: 'Delete' }).click()
+
+// Two possible outcomes, without racing them
+await expect(page.getByRole('alert').or(page.getByText('Saved'))).toBeVisible()
+
+// Only the elements both match
+await page.getByRole('button').and(page.locator('.primary')).click()
+```
+
+`filter({ has })` and `{ hasNot }` query the inner locator **from each candidate**,
+not from the page — so a match elsewhere does not qualify a row. `hasText` is not
+a substitute: it compares the candidate's whole text, so a neighbouring column
+containing the string matches too, and it cannot ask about a role.
+
+`filter()` throws on an unrecognised key. Ignoring one is how `filter({ has })`
+used to look like it worked while matching every candidate. `or()` returns
+document order with duplicates removed.
+
+### Media Queries
+
+```typescript
+await page.emulateMedia({ colorScheme: 'dark' })
+await page.emulateMedia({ media: 'print' })
+await page.emulateMedia({ reducedMotion: 'reduce', forcedColors: 'active' })
+await page.emulateMedia({ colorScheme: null })   // back to the browser's setting
+```
+
+`@media` blocks are parsed into real `CSSMediaRule`s and applied when their
+condition holds, so a dark-mode or responsive stylesheet takes effect in
+`getComputedStyle`, in `getBoundingClientRect` and in the locator queries that
+read visibility. `matchMedia` and the cascade evaluate the query with the same
+code, so they cannot disagree about the same document.
+
+Understood features: `prefers-color-scheme`, `prefers-reduced-motion`,
+`forced-colors`, `orientation`, and the `width`/`height` family with `px`, `em`
+and `rem`. Media types (`screen`, `print`, `all`), `and`, comma lists, `not` and
+`only` all work. Any other feature — `(hover: hover)`, for instance — makes its
+query false, as an unrecognised feature does in a browser.
+
+### Geometry
+
+```typescript
+const box = await page.locator('.card').boundingBox()   // { x, y, width, height } | null
+```
+
+Width and height are real — the rect resolves through the cascade, so a size from
+a stylesheet is reported. **`x` and `y` are always `0`**: there is no layout pass,
+so position is not computed, and overlap, ordering and is-this-above-the-fold
+cannot be asked here. `null` is returned for an element that is not rendered.
+`scrollIntoViewIfNeeded()` resolves and fires a `scroll` event, which is as much
+as is meaningful without layout.
+
+### Setting Page Content
+
+```typescript
+await page.setContent('<button>Save</button>')
+await expect(page.getByRole('button')).toBeVisible()
+```
+
+A bare fragment becomes the body; a full `<!DOCTYPE html><html><head>…` string
+lands intact. It replaces the whole document rather than filling the body, fires
+`domcontentloaded` and `load` so an assertion straight afterwards needs no wait,
+and leaves the URL alone — setting content is not navigating.
+
+### Form Controls
+
+```typescript
+await page.locator('#area').selectOption('north')            // by value
+await page.locator('#area').selectOption({ label: 'North' }) // by option text
+await page.locator('#photos').setInputFiles({ name: 'trail.gpx', buffer: gpx })
+await page.locator('#photos').setInputFiles('./fixtures/trail.gpx')   // read from disk
+await page.locator('#search').press('Control+Enter')
+await page.locator('#search').clear()
+await page.locator('#row').dblclick()
+await page.locator('#terms').setChecked(true)
+```
+
+`selectOption` fires `input` then `change`, which is the point: assigning
+`select.value` by hand fires neither, so a component listening for it never
+updates and the test passes against a DOM the app never saw. `setInputFiles`
+builds the `FileList` that assigning `input.files` requires. Passing several
+values to a non-`multiple` control is refused rather than silently truncated.
+`press` focuses the element first — `page.keyboard` only reaches whatever already
+has focus.
+
+### Keyboard
+
+```typescript
+await page.keyboard.press('Control+Enter')   // key 'Enter', ctrlKey true
+await page.keyboard.press('Shift+a')         // types 'A'
+await page.keyboard.down('Shift')
+await page.keyboard.press('Tab')             // shiftKey true
+await page.keyboard.up('Shift')
+```
+
+`Control`/`Ctrl`, `Shift`, `Alt`/`Option` and `Meta`/`Cmd`/`Command` are
+recognised, several at a time; modifiers go down in order and come up in reverse.
+`event.code` is populated (`KeyA`, `Digit1`, `ArrowDown`, `ShiftLeft`). A key held
+with Control, Alt or Meta does not insert text — `Control+A` selects rather than
+typing an "a" — while Shift produces the capital. Only a known modifier name is
+consumed, so `press('Enter')` and even a nonsense `press('a+b')` are passed
+through as literal keys.
+
+### Running Code Against a Locator
+
+```typescript
+const ids = await page.locator('tbody tr').evaluateAll(els => els.map(el => el.dataset.id))
+const label = await page.getByRole('button').evaluate(el => el.dataset.state)
+
+await page.locator('li').allTextContents()   // raw textContent, per match
+await page.locator('li').allInnerTexts()     // rendered text: hidden subtrees left out
+```
+
+`evaluate()` is strict and waits for the element to be attached; `evaluateAll()`
+is neither, because many matches is its expected case and none is a legitimate
+`[]`. The element is the real node, so writing through it changes the document.
+
+Callbacks are recompiled against the frame's window and **cannot see their
+closure**, the same as in Playwright — pass anything they need as the second
+argument. `page.$eval` / `page.$$eval` exist for ports, but take the first match
+rather than refusing an ambiguous selector.
+
+### Waiting on Page Events
+
+```typescript
+const [response] = await Promise.all([
+  page.waitForResponse('**/api/trails'),
+  page.getByRole('button', { name: 'Search' }).click(),
+])
+
+expect((await response.json()).trails).toHaveLength(3)
+```
+
+Subscribe *before* the action, as above. An event that has already fired is not
+replayed — the same as Playwright, and it matters more here because `goto()`
+emits synchronously and returns, so there is no window at all.
+
+- `page.waitForEvent(event, predicateOrOptions)` — the primitive, for any of the
+  six page events.
+- `page.waitForResponse(urlOrPredicate)` / `waitForRequest(...)` — a glob or
+  RegExp matches the URL through the same matcher `route()` uses; a function
+  receives the event itself, so it can read `status` too. Responses are reported
+  for navigations *and* for `fetch` calls made by page code. Requests need
+  interception on, which `page.route()` does as a side effect.
+- `page.waitForLoadState('load' | 'domcontentloaded')` — returns at once if the
+  state has already been reached. `networkidle` throws rather than pretending:
+  nothing here tracks in-flight requests.
+- `page.waitForURL(urlOrPredicate)` — polled, so a `pushState` counts.
+
 ### Browser Context
 
 ```typescript

package/dist/aria/roles.d.ts

@@ -11,6 +11,19 @@ export declare function computeRole(element: ElementLike): string | null;
  * that allow it, then `title`, and `placeholder` as a last resort for fields.
  */
 export declare function accessibleName(element: ElementLike): string;
+/**
+ * The description a screen reader would announce after the name.
+ *
+ * `aria-describedby` first, resolved through the document the same way
+ * `accessibleName` resolves `aria-labelledby`; then `aria-description`, then
+ * `title`. An element with no description answers with an empty string rather than
+ * null, matching `accessibleName`.
+ *
+ * `title` is last because it is also a name source: an element whose only text is
+ * a `title` uses it as its name, and using it as the description too would have
+ * the same string answer both questions.
+ */
+export declare function accessibleDescription(element: ElementLike): string;
 /** Heading depth, or null when the element is not a heading. */
 export declare function headingLevel(element: ElementLike): number | null;
 /**

package/dist/aria/state.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The element's checked state, or `undefined` when it is not checkable at all.
+ *
+ * The native property wins where there is one: it is the live state, and an
+ * author who writes `aria-checked` on a real `<input type=checkbox>` is
+ * duplicating something the browser already tracks.
+ */
+export declare function checkedState(element: ElementLike): CheckedState | undefined;
+/**
+ * Checked as a plain boolean, which is what `isChecked()` reports.
+ *
+ * `mixed` is neither checked nor unchecked, and a boolean cannot say so, so it
+ * answers `false` here. `toBeChecked({ checked: 'mixed' })` is where the third
+ * state can be asked about without lying.
+ */
+export declare function isChecked(element: ElementLike): boolean;
+/**
+ * The element's selected state, or `undefined` when it is not selectable.
+ *
+ * `<option selected>` keeps a live property, the same as a native checkbox;
+ * everything else goes through `aria-selected`.
+ */
+export declare function selectedState(element: ElementLike): boolean | undefined;
+/** Selected as a plain boolean. */
+export declare function isSelected(element: ElementLike): boolean;
+declare interface ElementLike {
+  tagName?: string
+  checked?: boolean
+  selected?: boolean
+  getAttribute?: (name: string) => string | null
+}
+/** `mixed` is a real third state, for a tri-state checkbox. */
+export type CheckedState = boolean | 'mixed';

package/dist/aria/visibility.d.ts

@@ -1,8 +1,18 @@
 /**
  * Whether the element is painted: nothing in its ancestor chain hides it with
- * `display: none`, `visibility: hidden|collapse` or the `hidden` attribute.
+ * `display: none`, `visibility: hidden|collapse`, the `hidden` attribute, or a
+ * declared zero size.
  */
 export declare function isRendered(element: ElementLike): boolean;
+/**
+ * Whether the element's own style hides it, ignoring its ancestors.
+ *
+ * @internal Shared with `innerText`, which walks the tree itself and so has
+ * already dealt with ancestors by not descending into a hidden one. Calling the
+ * ancestor-walking form per node would make that walk quadratic, and having two
+ * definitions of "hidden" is the thing #1601 set out to avoid.
+ */
+export declare function hidesItself(element: ElementLike, style?: any): boolean;
 /**
  * Whether the element reaches the accessibility tree: painted, and not marked
  * `aria-hidden` on itself or an ancestor.
@@ -23,6 +33,19 @@ export declare function isExposedToAria(element: ElementLike): boolean;
  * Both walk the ancestor chain, because hiding a container hides everything
  * inside it, and both resolve through `getComputedStyle()` so a rule from a
  * stylesheet counts, not only an inline style.
+ *
+ * Collapsing an element to nothing hides it too (#1617). `height: 0` is how a
+ * closed accordion, disclosure or drawer is built when the author wants a
+ * transition, since `display: none` cannot be animated — and that markup was
+ * fully reachable, so a role query matched a button inside a shut drawer and,
+ * since #1604, clicking it succeeded.
+ *
+ * This is narrower than Playwright's rule, deliberately. Playwright asks whether
+ * the bounding box is non-empty; there is no layout pass here, so an element
+ * nobody sized reports `0 × 0` — a plain `<button>Save</button>` with no CSS has
+ * an empty box. Zero therefore means *unknown*, not *collapsed*, and only a
+ * declared zero can be trusted to mean the latter. A reader who knows
+ * Playwright's definition should not assume the box is being consulted.
  */
 declare interface ElementLike {
   nodeType?: number

package/dist/browser/BrowserContext.d.ts

@@ -19,6 +19,12 @@ export declare class BrowserContext {
   grantPermissions(permissions: string[], _options?: { origin?: string }): Promise<void>;
   clearPermissions(): Promise<void>;
   setGeolocation(geolocation: { latitude: number, longitude: number, accuracy?: number } | null): Promise<void>;
+  emulateMedia(options?: {
+    media?: 'screen' | 'print' | null
+    colorScheme?: 'light' | 'dark' | null
+    reducedMotion?: 'reduce' | 'no-preference' | null
+    forcedColors?: 'active' | 'none' | null
+  }): Promise<void>;
   setOffline(offline: boolean): Promise<void>;
   setExtraHTTPHeaders(headers: Record<string, string>): Promise<void>;
   addInitScript(script: string | ((...args: any[]) => any)): Promise<void>;
@@ -27,6 +33,12 @@ export declare class BrowserContext {
     permissions: string[] | null
     geolocation: { latitude: number, longitude: number, accuracy?: number } | null
     offline: boolean
+    media: {
+      type?: 'screen' | 'print'
+      colorScheme?: 'light' | 'dark'
+      reducedMotion?: 'reduce' | 'no-preference'
+      forcedColors?: 'active' | 'none'
+    }
   };
   _extraHTTPHeaders(): Record<string, string>;
   _initScriptSources(): Array<string | ((...args: any[]) => any)>;

package/dist/browser/BrowserFrame.d.ts

@@ -23,6 +23,8 @@ export declare class BrowserFrame {
   waitForNavigation(): Promise<void>;
   abort(): Promise<void>;
   evaluate(code: string | ((...args: any[]) => any), arg?: any): any;
+  _evaluateWith(code: string | ((...args: any[]) => any), args: any[]): any;
+  setContent(html: string): void;
   goto(url: string, options?: { referer?: string }): Promise<Response | null>;
   reload(): Promise<Response | null>;
   goBack(): Promise<Response | null>;

package/dist/browser/BrowserPage.d.ts

@@ -1,16 +1,39 @@
 import { BrowserFrame } from './BrowserFrame';
 import { Buffer } from 'node:buffer';
+import { isChecked } from '../aria/state';
 import { Locator } from './Locator';
 import type { BrowserContext } from './BrowserContext';
-import type { GetByRoleOptions, GetByTextOptions } from './Locator';
+import type { DialogOutcome, DialogType } from './Dialog';
+import type { GetByRoleOptions, GetByTextOptions, WaitForState } from './Locator';
 import type { RouteHandler, RoutePattern } from '../network/routing';
 export declare interface IBrowserPageViewport {
   width: number
   height: number
 }
-export type PageEventType = 'console' | 'request' | 'response' | 'error' | 'load' | 'domcontentloaded';
+export declare interface WaitForEventOptions {
+  predicate?: (event: any) => boolean
+  timeout?: number
+}
+export type PageEventType = 'console' | 'request' | 'response' | 'error' | 'load' | 'domcontentloaded' | 'dialog';
 // eslint-disable-next-line pickier/no-unused-vars
 export type PageEventHandler = (event: any) => void;
+/**
+ * Which event to settle on.
+ *
+ * A string is a Playwright glob and a RegExp is used as written, both against
+ * the URL. A function receives the event itself — the `Response` or the request
+ * — rather than its URL, so it can look at the status too. That is Playwright's
+ * split, and it is why this cannot simply be a `RoutePattern`, whose function
+ * form takes a URL.
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+export type EventTarget<T = any> = string | RegExp | ((event: T) => boolean);
+/** The load states this page can actually report. */
+export type LoadState = 'load' | 'domcontentloaded';
+/** How a caller can name an `<option>`: by value, label, index, or bare value. */
+export type SelectOptionValue = string | { value?: string, label?: string, index?: number }
+/** A file to attach: a path on disk, or bytes with a name. */
+export type InputFile = string | { name: string, mimeType?: string, buffer: Uint8Array | ArrayBuffer | string }
 /**
  * BrowserPage represents a browser page (tab or popup window)
  * Compatible with Happy DOM's BrowserPage API
@@ -31,6 +54,7 @@ export declare class BrowserPage {
   waitUntilComplete(): Promise<void>;
   waitForNavigation(): Promise<void>;
   abort(): Promise<void>;
+  _evaluateWith(code: string | ((...args: any[]) => any), args: any[]): any;
   evaluate(code: string | ((...args: any[]) => any), arg?: any): any;
   setViewport(viewport: IBrowserPageViewport): void;
   goto(url: string, options?: { referer?: string }): Promise<Response | null>;
@@ -41,21 +65,45 @@ export declare class BrowserPage {
   _applyEmulation(): void;
   _runInitScripts(): void;
   setDefaultTimeout(timeout: number): void;
+  setContent(html: string): Promise<void>;
+  emulateMedia(options?: {
+    media?: 'screen' | 'print' | null
+    colorScheme?: 'light' | 'dark' | null
+    reducedMotion?: 'reduce' | 'no-preference' | null
+    forcedColors?: 'active' | 'none' | null
+  }): Promise<void>;
   _defaultTimeoutMs(): number;
-  waitForSelector(selector: string, options?: { timeout?: number, visible?: boolean }): Promise<any | null>;
+  waitForSelector(selector: string, options?: { timeout?: number, state?: WaitForState, visible?: boolean }): Promise<any | null>;
   waitForFunction(options?: { timeout?: number, polling?: number | 'raf' }): Promise<any>;
   waitForTimeout(ms: number): Promise<void>;
+  waitForEvent(event: PageEventType, optionsOrPredicate?: WaitForEventOptions | ((event: any) => boolean)): Promise<any>;
+  waitForResponse(urlOrPredicate: EventTarget, options?: { timeout?: number }): Promise<any>;
+  waitForRequest(urlOrPredicate: EventTarget, options?: { timeout?: number }): Promise<any>;
+  waitForLoadState(state?: LoadState, options?: { timeout?: number }): Promise<void>;
+  waitForURL(urlOrPredicate: EventTarget<string>, options?: { timeout?: number }): Promise<void>;
   click(selector: string, options?: { delay?: number, button?: 'left' | 'right' | 'middle' }): Promise<void>;
   type(selector: string, text: string, options?: { delay?: number }): Promise<void>;
   _typeIntoElement(element: any, text: string, options?: { delay?: number }): Promise<void>;
   fill(selector: string, value: string): Promise<void>;
+  _selectOptions(element: any, wanted: SelectOptionValue[]): Promise<string[]>;
+  _setInputFiles(element: any, files: InputFile[]): Promise<void>;
+  _dblclickElement(element: any): Promise<void>;
   _fillElement(element: any, value: string): Promise<void>;
+  selectOption(selector: string, values: SelectOptionValue | SelectOptionValue[] | null): Promise<string[]>;
+  setInputFiles(selector: string, files: InputFile | InputFile[] | null): Promise<void>;
+  press(selector: string, key: string, options?: { delay?: number }): Promise<void>;
+  clear(selector: string): Promise<void>;
+  dblclick(selector: string): Promise<void>;
+  check(selector: string): Promise<void>;
+  uncheck(selector: string): Promise<void>;
   focus(selector: string): Promise<void>;
   blur(selector: string): Promise<void>;
   hover(selector: string): Promise<void>;
   _hoverElement(element: any): Promise<void>;
   get keyboard(): {
     press: (key: string, options?: { delay?: number }) => Promise<void>
+    down: (key: string) => Promise<void>
+    up: (key: string) => Promise<void>
     type: (text: string, options?: { delay?: number }) => Promise<void>
   };
   get mouse(): {
@@ -72,6 +120,8 @@ export declare class BrowserPage {
   getByAltText(text: string | RegExp, options?: GetByTextOptions): Locator;
   getByTitle(text: string | RegExp, options?: GetByTextOptions): Locator;
   getByTestId(testId: string | RegExp): Locator;
+  $eval(selector: string, fn: string | ((element: any, arg?: any) => any), arg?: any): Promise<any>;
+  $$eval(selector: string, fn: string | ((elements: any[], arg?: any) => any), arg?: any): Promise<any>;
   title(): Promise<string>;
   textContent(selector: string): Promise<string | null>;
   innerText(selector: string): Promise<string>;
@@ -87,6 +137,7 @@ export declare class BrowserPage {
   on(event: PageEventType, handler: PageEventHandler): void;
   off(event: PageEventType, handler: PageEventHandler): void;
   emit(event: PageEventType, data: any): void;
+  _requestDialog(type: DialogType, message: string, defaultValue?: string): DialogOutcome;
   _emitConsole(type: string, ...args: any[]): void;
   _emitRequest(request: any): void;
   _emitResponse(response: any): void;
@@ -94,7 +145,7 @@ export declare class BrowserPage {
   dragAndDrop(source: string, target: string, options?: { delay?: number }): Promise<void>;
   route(url: RoutePattern, handler: RouteHandler): Promise<void>;
   unroute(url?: RoutePattern, handler?: RouteHandler): Promise<void>;
-  _ensureRouting(): void;
+  _syncRouting(): void;
   setRequestInterception(enabled: boolean): Promise<void>;
   screenshot(options?: {
     type?: 'png' | 'jpeg' | 'webp'

package/dist/browser/Dialog.d.ts

@@ -0,0 +1,36 @@
+/** What a dialog was answered with. */
+export declare interface DialogOutcome {
+  accepted: boolean
+  text: string | null
+}
+/**
+ * A dialog the page opened, and the decision a handler makes about it (#1612).
+ *
+ * `confirm()` returned a hardcoded `false`, so a confirm-gated action could only
+ * ever be cancelled:
+ *
+ *     deleteButton.addEventListener('click', () => {
+ *       if (!confirm('Delete this trail?')) return
+ *       removeTrail()                                 // unreachable, always
+ *     })
+ *
+ * The test clicked the button, nothing happened, and the assertion failed with no
+ * hint that a dialog was involved. The "delete" half of every destructive flow
+ * was untestable, and destructive flows are the ones most worth a test.
+ *
+ * `alert()` was the benign one — a no-op is close enough to auto-dismissing —
+ * except that there was no way to assert an alert had happened at all.
+ */
+/** `beforeunload` is deliberately absent: nothing here fires it. */
+export type DialogType = 'alert' | 'confirm' | 'prompt';
+export declare class Dialog {
+  readonly type: DialogType;
+  readonly message: string;
+  readonly or an empty string. */
+    defaultValue?: string;
+  constructor(type: DialogType, message: string);
+  accept(promptText?: string): Promise<void>;
+  dismiss(): Promise<void>;
+  get _wasSettled(): boolean;
+  _outcome(): DialogOutcome;
+}

package/dist/browser/Locator.d.ts

@@ -1,4 +1,6 @@
-import { accessibleName } from '../aria/roles';
+import { accessibleDescription, accessibleName } from '../aria/roles';
+import { checkedState, isChecked } from '../aria/state';
+import type { InputFile, SelectOptionValue } from './BrowserPage';
 /** @internal Collapse whitespace, the way Playwright compares rendered text. */
 export declare function normalize(value: string | null | undefined): string;
 /**
@@ -43,6 +45,8 @@ export declare interface GetByTextOptions {
 export declare interface FilterOptions {
   hasText?: string | RegExp
   hasNotText?: string | RegExp
+  has?: Locator
+  hasNot?: Locator
 }
 export declare interface WaitForOptions {
   state?: WaitForState
@@ -52,8 +56,16 @@ export declare interface WaitForOptions {
 export declare interface ActionOptions {
   timeout?: number
 }
-/** Returns the current matches, re-evaluated on each call. */
-declare type Resolver = () => any[];
+/**
+ * Returns the current matches, re-evaluated on each call.
+ *
+ * The optional root is what makes `filter({ has })` work. Playwright queries an
+ * inner locator *starting from the outer match*, not from the document, so a
+ * locator has to be answerable against an arbitrary element rather than only
+ * against the page. Every derived locator threads it through to its parent.
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+declare type Resolver = (root?: any) => any[];
 /**
  * What a wait is waiting for.
  *
@@ -70,6 +82,9 @@ export declare class Locator {
   elementHandles(): Promise<any[]>;
   locator(selector: string): Locator;
   filter(options: FilterOptions): Locator;
+  or(other: Locator): Locator;
+  and(other: Locator): Locator;
+  get page(): any;
   nth(index: number): Locator;
   first(): Locator;
   last(): Locator;
@@ -87,11 +102,16 @@ export declare class Locator {
   innerHTML(): Promise<string>;
   inputValue(): Promise<string>;
   getAttribute(name: string): Promise<string | null>;
+  allTextContents(): Promise<string[]>;
+  allInnerTexts(): Promise<string[]>;
   ariaRole(): Promise<string | null>;
   accessibleName(): Promise<string>;
+  accessibleDescription(): Promise<string>;
+  selectedValues(): Promise<string[]>;
   isVisible(): Promise<boolean>;
   isHidden(): Promise<boolean>;
   isChecked(): Promise<boolean>;
+  checkedState(): Promise<boolean | 'mixed' | undefined>;
   isEnabled(): Promise<boolean>;
   isDisabled(): Promise<boolean>;
   isEditable(): Promise<boolean>;
@@ -102,5 +122,15 @@ export declare class Locator {
   fill(value: string, options?: ActionOptions): Promise<void>;
   type(text: string, options?: { delay?: number, timeout?: number }): Promise<void>;
   check(options?: ActionOptions): Promise<void>;
+  selectOption(values: SelectOptionValue | SelectOptionValue[] | null, options?: ActionOptions): Promise<string[]>;
+  setInputFiles(files: InputFile | InputFile[] | null, options?: ActionOptions): Promise<void>;
+  press(key: string, options?: ActionOptions & { delay?: number }): Promise<void>;
+  clear(options?: ActionOptions): Promise<void>;
+  dblclick(options?: ActionOptions): Promise<void>;
+  setChecked(checked: boolean, options?: ActionOptions): Promise<void>;
   uncheck(options?: ActionOptions): Promise<void>;
+  boundingBox(options?: ActionOptions): Promise<{ x: number, y: number, width: number, height: number } | null>;
+  scrollIntoViewIfNeeded(options?: ActionOptions): Promise<void>;
+  evaluate(fn: string | ((element: any, arg?: any) => any), arg?: any, options?: ActionOptions): Promise<any>;
+  evaluateAll(fn: string | ((elements: any[], arg?: any) => any), arg?: any): Promise<any>;
 }