@itmetsam/samurai-framework 0.22.9 → 0.22.11

package/dist/browser/page-actions.js

@@ -0,0 +1,197 @@
+import { printPdf } from "./pdf.js";
+import { applyUse } from "./use-commands.js";
+import { screenshotWithEvidence, } from "./screenshot.js";
+import { traverseHistory } from "./history.js";
+import { grantPermission } from "./page-permissions.js";
+import {} from "./page-settings.js";
+import { readContent, readTitle, readUrl } from "./page-content.js";
+import { evaluateInPage } from "./page-evaluate.js";
+import { PageCore } from "./page-core.js";
+/** @internal Navigation, content, viewport and the other things a page does */
+export class PageActions extends PageCore {
+    /**
+     * Runs `script` before any page script in every document this page loads from now on, and once in
+     * the document that is loaded now. It runs in the page's own realm, so the page sees what it sets.
+     * A function receives `arg` (which must be JSON-serializable) as its only argument;
+     * a string is script source (statements) and takes no argument.
+     * @example
+     *  await page.addInitScript(() => { window.__testMode = true; });
+     *  await page.addInitScript((flags) => { window.flags = flags; }, { beta: true });
+     */
+    async addInitScript(script, arg) {
+        this.assertOpen();
+        return this.initScripts.add(this.biDiConnector, this.id, script, arg);
+    }
+    /** Sets the base that relative `goto` URLs resolve against; `undefined` falls back to the run's baseURL */
+    setBaseURL(url) {
+        this.nav.setBaseURL(url);
+    }
+    /** @internal The full URL `goto` would navigate to: a URL starting with "/", "./" or "../" resolves against the base URL, others stay as given. `method` names the caller in the error */
+    resolveURL(url, method) {
+        return this.nav.resolveURL(url, method);
+    }
+    /**
+     * Navigates like `navigateTo`, but a URL starting with "/", "./" or "../" resolves against the base URL
+     * (`setBaseURL`, else the environment's `baseURL`).
+     * @example
+     *  await page.goto("/products");
+     *  await page.goto("https://example.com", { wait: "interactive" });
+     */
+    goto(url, options) {
+        return this.nav.goto(url, options);
+    }
+    /**
+     * Navigates to `url` and resolves when the page reached `wait` (default "complete", the load event).
+     * A URL without a scheme gets `https://`. Throws NavigationError when the navigation fails or takes too long.
+     * The positional form `navigateTo(url, wait, protocol)` still works.
+     * @example
+     *  await page.navigateTo("example.com");
+     *  await page.navigateTo("localhost:3000", { wait: "interactive", protocol: "http" });
+     */
+    navigateTo(url, options, protocol) {
+        return this.nav.navigateTo(url, options, protocol);
+    }
+    /**
+     * Reloads the page and resolves when it reached `wait` (default like `navigateTo`). Firefox does not support
+     * `ignoreCache`; asking for it throws UnsupportedOperationError.
+     */
+    reload(options = {}) {
+        return this.nav.reload(options);
+    }
+    /** Goes back one entry in the history. False when there is none to go back to */
+    async goBack() {
+        this.assertOpen();
+        return traverseHistory(this.biDiConnector, this.id, -1);
+    }
+    /** Goes forward one entry in the history. False when there is none */
+    async goForward() {
+        this.assertOpen();
+        return traverseHistory(this.biDiConnector, this.id, 1);
+    }
+    /** The URL of the page now */
+    async url() {
+        this.assertOpen();
+        return readUrl(this.biDiConnector, this.id);
+    }
+    /**
+     * Waits until the URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then until the page reached `waitUntil` (default "load"). Also sees `pushState`.
+     * @example
+     *  await page.getByRole("button", { name: "Sign in" }).click();
+     *  await page.waitForURL("**\/dashboard");
+     */
+    waitForURL(url, options) {
+        return this.nav.waitForURL(url, options);
+    }
+    /** The markup of the document now, doctype included */
+    async content() {
+        this.assertOpen();
+        return readContent(this.biDiConnector, this.id);
+    }
+    /**
+     * Replaces the document with `html` and waits for `waitUntil` (default "load"). Scripts and styles in it run and apply;
+     * the page keeps its URL and origin (it is not a `data:` page).
+     * @example
+     *  await page.setContent("<button>Go</button><script>document.title = 'x'</script>");
+     */
+    async setContent(html, options) {
+        return this.nav.setContent(html, options);
+    }
+    /** The title of the document now */
+    async title() {
+        this.assertOpen();
+        return readTitle(this.biDiConnector, this.id);
+    }
+    /**
+     * Runs `fn` in the page, with `arg` as its only argument, and returns the result (a promise is awaited). `fn` is a function,
+     * the source of one (`"async () => ..."`), or any other string, which is an expression (`"document.title"`; it takes no argument).
+     * Values come back as plain JavaScript: Date, Map, Set, RegExp, BigInt, NaN, undefined, nested objects and arrays;
+     * an element as an `ElementHandle`; what cannot be copied (a function, window, error, promise) as a `RemoteObject` with its `type`.
+     * The page's own error message is kept (`ScriptError`). A function written under tsx must not contain named inner functions
+     * (the transpiler adds a `__name` helper the page lacks); a string always works.
+     * @example
+     *  const count = await page.evaluate((min) => document.querySelectorAll("li").length > min, 3);
+     */
+    async evaluate(fn, arg) {
+        this.assertOpen();
+        return evaluateInPage(this.biDiConnector, this.id, fn, arg);
+    }
+    /**
+     * Sets the size of the viewport (and, optionally, the device pixel ratio); `null` puts the browser's own size back.
+     * @example
+     *  await page.setViewport({ width: 390, height: 844, devicePixelRatio: 3 });
+     */
+    async setViewport(viewport) {
+        this.assertOpen();
+        await this.viewport.set(viewport);
+    }
+    /** @internal Chrome: lays this page out like a phone from now on (`use.isMobile`), including the size it has now */
+    async setMobileLayout() {
+        await this.viewport.setMobileLayout();
+    }
+    /** Playwright's name for `setViewport` */
+    setViewportSize(size) {
+        return this.setViewport(size);
+    }
+    /**
+     * The size this page was last given (`setViewport`, `setViewportSize`, or the default from config `use.viewport` when the
+     * browser opened it), read at once; null before one is known, after `setViewport(null)` and when config turns the viewport off.
+     */
+    viewportSize() {
+        return this.viewport.size();
+    }
+    /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
+    async applyDefaultViewport() {
+        await this.viewport.applyDefault();
+    }
+    /**
+     * Takes a screenshot and returns the image (also written to `options.path`).
+     * @example
+     *  await page.screenshot({ path: "out/home.png", fullPage: true });
+     */
+    async screenshot(options = {}) {
+        this.assertOpen();
+        return screenshotWithEvidence(this.biDiConnector, this.id, options, this.evidence);
+    }
+    /** Waits `ms` milliseconds. Prefer waiting for something (an assertion, `waitForNetworkIdle`) when you can */
+    async waitForTimeout(ms) {
+        if (!Number.isFinite(ms) || ms < 0)
+            throw new RangeError(`waitForTimeout(): ms must be 0 or more, got ${ms}`);
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /** Renders the page as a PDF and returns it (also written to `options.path`) */
+    async pdf(options = {}) {
+        this.assertOpen();
+        return printPdf(this.biDiConnector, this.id, options);
+    }
+    /**
+     * Changes the `use` options that can change while the browser runs for this page only: locale, timezone, user
+     * agent, geolocation, offline, orientation, screen, hasTouch, javaScriptEnabled. It wins over what the page's
+     * context says; `null` puts the real (or the context's) value back. Same options as `test.use()`, applied now.
+     * @example
+     *  await page.use({ locale: "nl-NL", offline: true });
+     */
+    async use(options) {
+        this.assertOpen();
+        await applyUse(this.biDiConnector, { contexts: [this.id] }, options);
+    }
+    /**
+     * Grants a browser permission ("geolocation", "notifications", "camera", …) to the origin this page is on,
+     * or to `options.origin`. A geolocation override only answers once this is granted.
+     */
+    async grantPermission(name, options = {}) {
+        this.assertOpen();
+        await grantPermission(this.biDiConnector, () => this.url(), () => this.browserContext, name, options);
+    }
+    /**
+     * Waits until the page's document reached `state` (default "load"): "domcontentloaded" and "load" follow the
+     * document, "networkidle" is "load" plus a quiet network (see `waitForNetworkIdle`). Resolves at once when it
+     * is already there. Call it once the navigation has started; a document that is still the old one counts.
+     * @example
+     *  await page.locator("a[@id='next']").click();
+     *  await page.waitForLoadState("domcontentloaded");
+     */
+    waitForLoadState(state = "load", options = {}) {
+        return this.nav.waitForLoadState(state, options);
+    }
+}

package/dist/browser/page-core.d.ts

@@ -0,0 +1,80 @@
+import type { APIRequestContext } from "../request/api-request-context.js";
+import EventEmitter from "node:events";
+import { ContextTree } from "./context-tree.js";
+import type { BrowserContext } from "./browser-context.js";
+import type { Evidence } from "./evidence.js";
+import { PageLogging } from "./page-logging.js";
+import { Lazy } from "./lazy.js";
+import { DialogHandling } from "./dialog-handling.js";
+import { DocumentWatcher } from "./document-watcher.js";
+import { PageNavigation } from "./page-navigation.js";
+import { PageNetwork } from "./page-network.js";
+import { PageTransfers } from "./page-transfers.js";
+import { InitScripts } from "./init-script.js";
+import { PageLocators } from "./page-locators.js";
+import Keyboard from "./keyboard.js";
+import Mouse from "./mouse.js";
+import { PageConfig, type PageSettings } from "./page-settings.js";
+import { PageViewport } from "./page-viewport.js";
+import { HelperRealm } from "../locator/helper-realm.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+/** @internal Page state and its wiring: the layers of `Page` build on it (see page.ts) */
+export declare abstract class PageCore {
+    protected biDiConnector: BiDiConnector;
+    protected id: BrowsingContext;
+    protected lazyTree: Lazy<ContextTree>;
+    protected helperRealm: HelperRealm;
+    protected initScripts: InitScripts;
+    protected pageConfig: PageConfig;
+    protected locators: PageLocators;
+    /** Real key input to whatever has focus: `press` (also chords such as `Control+a`), `down`, `up`, `type`, `insertText` */
+    readonly keyboard: Keyboard;
+    /** Real pointer input at viewport coordinates: `move`, `down`, `up`, `click`, `dblclick`, `wheel` */
+    readonly mouse: Mouse;
+    protected pageEvents: EventEmitter<any>;
+    protected documents: DocumentWatcher;
+    protected nav: PageNavigation;
+    protected net: PageNetwork;
+    protected dialogs: DialogHandling;
+    protected logging: PageLogging;
+    protected isClosed: boolean;
+    protected browserContext: BrowserContext | undefined;
+    protected transfers: PageTransfers;
+    protected evidence: Evidence | undefined;
+    protected viewport: PageViewport;
+    /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
+    constructor(biDiConnector: BiDiConnector, contextId: string, settings?: PageSettings);
+    /** The BiDi browsing context id of this page's top-level context */
+    get contextId(): BrowsingContext;
+    /** The context tree, created on first use and shared by everything that needs to attribute frame events to this page */
+    tree(): Promise<ContextTree>;
+    /** Removes everything the page registered in the browser: init scripts, framework helpers and event subscriptions */
+    dispose(): Promise<void>;
+    /** @internal The runner gives each test its own evidence folder */
+    setEvidence(evidence: Evidence | undefined): void;
+    /** The browser context (cookies, storage) this page belongs to */
+    context(): BrowserContext;
+    /** Makes HTTP requests from the test with this page's cookies; the same as `page.context().request` */
+    get request(): APIRequestContext;
+    /** @internal Called when the page is opened in a context */
+    setContext(context: BrowserContext): void;
+    /** @internal Marks the page closed after its tab is gone (its context was removed) and releases what it registered */
+    detach(): Promise<void>;
+    /** True once `close()` has run */
+    get closed(): boolean;
+    protected assertOpen(): void;
+    /**
+     * Closes the tab and releases everything the page registered. Later calls on the page throw "page closed".
+     * With `runBeforeUnload` the page's `beforeunload` handlers run first. Closing the browser's last tab may end the browser.
+     */
+    close(options?: {
+        runBeforeUnload?: boolean;
+    }): Promise<void>;
+    /**
+     * Resolves with the first `event` `matches` accepts. Listens before `trigger` runs, so what the trigger causes cannot
+     * be missed; a trigger that throws rejects the wait with its error. `onTimeout` builds the error for a wait that ran out.
+     */
+    private waitForPageEvent;
+    abstract url(): Promise<string>;
+}

package/dist/browser/page-core.js

@@ -0,0 +1,150 @@
+import EventEmitter from "node:events";
+import logger from "../logger/index.js";
+import { ContextTree } from "./context-tree.js";
+import { PageLogging } from "./page-logging.js";
+import { Lazy } from "./lazy.js";
+import { DialogHandling } from "./dialog-handling.js";
+import { DocumentWatcher } from "./document-watcher.js";
+import { PageNavigation } from "./page-navigation.js";
+import { PageNetwork } from "./page-network.js";
+import { PageTransfers } from "./page-transfers.js";
+import { InitScripts } from "./init-script.js";
+import { PageLocators } from "./page-locators.js";
+import Keyboard from "./keyboard.js";
+import Mouse from "./mouse.js";
+import { waitForPageEvent, } from "./page-events.js";
+import { PageConfig } from "./page-settings.js";
+import { PageViewport } from "./page-viewport.js";
+import { HelperRealm } from "../locator/helper-realm.js";
+import { BiDiError } from "../transport/bidi-error.js";
+/** @internal Page state and its wiring: the layers of `Page` build on it (see page.ts) */
+export class PageCore {
+    /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
+    constructor(biDiConnector, contextId, settings) {
+        this.lazyTree = new Lazy();
+        this.initScripts = new InitScripts();
+        this.pageEvents = new EventEmitter();
+        this.isClosed = false;
+        this.biDiConnector = biDiConnector;
+        this.id = contextId;
+        this.pageConfig = new PageConfig(settings);
+        this.helperRealm = new HelperRealm(biDiConnector, contextId);
+        this.locators = new PageLocators(biDiConnector, contextId, this.helperRealm, this.pageConfig, () => this.assertOpen());
+        this.keyboard = new Keyboard(biDiConnector, contextId, () => this.assertOpen());
+        this.mouse = new Mouse(biDiConnector, contextId, () => this.assertOpen());
+        this.documents = new DocumentWatcher(biDiConnector, contextId);
+        this.viewport = new PageViewport(biDiConnector, contextId, this.pageConfig);
+        this.logging = new PageLogging(biDiConnector, contextId, () => this.tree(), this.pageEvents);
+        this.net = new PageNetwork(biDiConnector, contextId, {
+            config: this.pageConfig,
+            tree: { ensure: () => this.tree(), peek: () => this.lazyTree.peek() },
+            emitter: this.pageEvents,
+            waitForEvent: (event, matches, options, onTimeout) => this.waitForPageEvent(event, matches, options, onTimeout),
+        });
+        this.nav = new PageNavigation(biDiConnector, contextId, {
+            config: this.pageConfig,
+            documents: this.documents,
+            assertOpen: () => this.assertOpen(),
+            url: () => this.url(),
+            waitForNetworkIdle: (options) => this.net.waitForIdle(options),
+        });
+        this.transfers = new PageTransfers(biDiConnector, contextId, {
+            config: this.pageConfig,
+            tree: { ensure: () => this.tree(), peek: () => this.lazyTree.peek() },
+            emitter: this.pageEvents,
+            waitForEvent: (event, matches, options, onTimeout) => this.waitForPageEvent(event, matches, options, onTimeout),
+        });
+        this.dialogs = new DialogHandling(biDiConnector, contextId, { ensure: () => this.tree(), peek: () => this.lazyTree.peek() }, this.pageEvents);
+    }
+    /** The BiDi browsing context id of this page's top-level context */
+    get contextId() {
+        return this.id;
+    }
+    /** The context tree, created on first use and shared by everything that needs to attribute frame events to this page */
+    tree() {
+        return this.lazyTree.get(() => ContextTree.create(this.biDiConnector));
+    }
+    /** Removes everything the page registered in the browser: init scripts, framework helpers and event subscriptions */
+    async dispose() {
+        const scripts = this.initScripts.all();
+        const results = await Promise.allSettled([
+            ...scripts.map((handle) => handle.dispose()),
+            this.helperRealm.dispose(),
+            // The tracker goes before the tree it reads
+            this.net.disposeTracker(),
+        ]);
+        const tree = this.lazyTree.take();
+        const pageLogs = this.logging.take();
+        results.push(...(await Promise.allSettled([
+            tree?.then((resolved) => resolved.dispose()),
+            this.documents.dispose(),
+            this.dialogs.dispose(),
+            pageLogs?.then((logs) => logs.dispose()),
+            ...this.net.disposeRest(),
+            ...this.transfers.dispose(),
+        ])));
+        const failed = results.find((result) => result.status === "rejected");
+        if (failed)
+            throw failed.reason;
+    }
+    /** @internal The runner gives each test its own evidence folder */
+    setEvidence(evidence) {
+        this.evidence = evidence;
+    }
+    /** The browser context (cookies, storage) this page belongs to */
+    context() {
+        if (!this.browserContext)
+            throw new Error("this page has no browser context: open it with browser.newPage() or context.newPage()");
+        return this.browserContext;
+    }
+    /** Makes HTTP requests from the test with this page's cookies; the same as `page.context().request` */
+    get request() {
+        return this.context().request;
+    }
+    /** @internal Called when the page is opened in a context */
+    setContext(context) {
+        this.browserContext = context;
+    }
+    /** @internal Marks the page closed after its tab is gone (its context was removed) and releases what it registered */
+    async detach() {
+        this.isClosed = true;
+        await this.dispose().catch((err) => logger.debug("Releasing a detached page failed", { err }));
+    }
+    /** True once `close()` has run */
+    get closed() {
+        return this.isClosed;
+    }
+    assertOpen() {
+        if (this.isClosed)
+            throw new Error("page closed");
+    }
+    /**
+     * Closes the tab and releases everything the page registered. Later calls on the page throw "page closed".
+     * With `runBeforeUnload` the page's `beforeunload` handlers run first. Closing the browser's last tab may end the browser.
+     */
+    async close(options = {}) {
+        if (this.isClosed)
+            return;
+        try {
+            await this.biDiConnector.send("browsingContext.close", {
+                context: this.id,
+                ...(options.runBeforeUnload && { promptUnload: true }),
+            });
+        }
+        catch (err) {
+            // Already gone (closed by the page, the browser or another call): the goal is met
+            if (!(err instanceof BiDiError && err.code === "no such frame"))
+                throw err;
+        }
+        this.isClosed = true;
+        await this.dispose().catch((err) => logger.debug("Releasing a closed page failed", { err }));
+    }
+    /**
+     * Resolves with the first `event` `matches` accepts. Listens before `trigger` runs, so what the trigger causes cannot
+     * be missed; a trigger that throws rejects the wait with its error. `onTimeout` builds the error for a wait that ran out.
+     */
+    async waitForPageEvent(event, matches, options, onTimeout) {
+        const timeout = await this.pageConfig.navigationTimeout(options.timeout);
+        return waitForPageEvent(this.pageEvents, event, matches, options, timeout, onTimeout);
+    }
+}

package/dist/browser/page-locating.d.ts

@@ -0,0 +1,37 @@
+import Locator from "../locator/locator.js";
+import type { FilterOptions } from "../locator/filter-step.js";
+import type { RoleOptions } from "../locator/role-locator.js";
+import type { ExactOption, TextOptions } from "../locator/selector.js";
+import { PageActions } from "./page-actions.js";
+/** @internal The ways to locate elements */
+export declare abstract class PageLocating extends PageActions {
+    /**
+     * Locates elements on the page. An xpath (`//x`, `/html/body`, `(//x)[2]`, `./x`, `xpath=…`, or an older
+     * relative one such as `a[@id='x']`) or a css selector (`input[name='x']`, `a, button`, `css=…`).
+     * `options` filter the matches, as `locator.filter()` does
+     */
+    locator(selector: string, options?: FilterOptions<Locator>): Locator;
+    /**
+     * Makes this page's locators strict (or not): an action or read on a locator matching several elements then
+     * throws `name(): strict mode violation, N elements match ...` instead of using the first. `undefined` goes back
+     * to config `use.strictSelectors` (off unless set). Applies to locators made afterwards and to earlier ones that have not
+     * run an action or read yet: a locator keeps the answer it got at its first one
+     */
+    setStrictSelectors(enabled: boolean | undefined): void;
+    /** Locates elements with a CSS selector */
+    getByCss(css: string): Locator;
+    /** Locates elements by their text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written (see `TextOptions`) */
+    getByText(text: string | RegExp, options?: TextOptions): Locator;
+    /** Locates form controls by their label text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written */
+    getByLabel(text: string | RegExp, options?: TextOptions): Locator;
+    /** Locates elements by their `placeholder` (see `TextOptions` for `exact` and RegExp) */
+    getByPlaceholder(text: string | RegExp, options?: ExactOption): Locator;
+    /** Locates elements by their `alt` text (images, areas, image inputs) */
+    getByAltText(text: string | RegExp, options?: ExactOption): Locator;
+    /** Locates elements by their `title` attribute */
+    getByTitle(text: string | RegExp, options?: ExactOption): Locator;
+    /** Locates elements by their `data-testid` attribute */
+    getByTestId(testId: string): Locator;
+    /** Locates elements by ARIA role and, optionally, accessible name and state (see `RoleOptions`) */
+    getByRole(role: string, options?: RoleOptions): Locator;
+}

package/dist/browser/page-locating.js

@@ -0,0 +1,58 @@
+import Locator from "../locator/locator.js";
+import { attributeSelector, cssSelector, labelSelector, roleSelector, testIdSelector, textSelector, } from "../locator/selector.js";
+import { PageActions } from "./page-actions.js";
+/** @internal The ways to locate elements */
+export class PageLocating extends PageActions {
+    /**
+     * Locates elements on the page. An xpath (`//x`, `/html/body`, `(//x)[2]`, `./x`, `xpath=…`, or an older
+     * relative one such as `a[@id='x']`) or a css selector (`input[name='x']`, `a, button`, `css=…`).
+     * `options` filter the matches, as `locator.filter()` does
+     */
+    locator(selector, options) {
+        const found = this.locators.locate(selector);
+        return options === undefined ? found : found.filter(options);
+    }
+    /**
+     * Makes this page's locators strict (or not): an action or read on a locator matching several elements then
+     * throws `name(): strict mode violation, N elements match ...` instead of using the first. `undefined` goes back
+     * to config `use.strictSelectors` (off unless set). Applies to locators made afterwards and to earlier ones that have not
+     * run an action or read yet: a locator keeps the answer it got at its first one
+     */
+    setStrictSelectors(enabled) {
+        this.locators.setStrictSelectors(enabled);
+    }
+    /** Locates elements with a CSS selector */
+    getByCss(css) {
+        return this.locators.locate([cssSelector(css)]);
+    }
+    /** Locates elements by their text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written (see `TextOptions`) */
+    getByText(text, options) {
+        return this.locators.locate([textSelector(text, options)]);
+    }
+    /** Locates form controls by their label text: an exact match unless `match: "partial"` or `exact: false`; a RegExp is tested as written */
+    getByLabel(text, options) {
+        return this.locators.locate([labelSelector(text, options)]);
+    }
+    /** Locates elements by their `placeholder` (see `TextOptions` for `exact` and RegExp) */
+    getByPlaceholder(text, options) {
+        return this.locators.locate([
+            attributeSelector("placeholder", text, options),
+        ]);
+    }
+    /** Locates elements by their `alt` text (images, areas, image inputs) */
+    getByAltText(text, options) {
+        return this.locators.locate([attributeSelector("alt", text, options)]);
+    }
+    /** Locates elements by their `title` attribute */
+    getByTitle(text, options) {
+        return this.locators.locate([attributeSelector("title", text, options)]);
+    }
+    /** Locates elements by their `data-testid` attribute */
+    getByTestId(testId) {
+        return this.locators.locate([testIdSelector(testId)]);
+    }
+    /** Locates elements by ARIA role and, optionally, accessible name and state (see `RoleOptions`) */
+    getByRole(role, options) {
+        return this.locators.locate([roleSelector(role, options)]);
+    }
+}

package/dist/browser/page-observing.d.ts

@@ -0,0 +1,120 @@
+import type { NetworkRequest } from "../network/network-tracker.js";
+import type { Download } from "./download.js";
+import type { FileChooser } from "./file-chooser.js";
+import type { LogRecord, PageError } from "./page-logs.js";
+import type { RouteHandler } from "../network/router.js";
+import { Response } from "../network/response.js";
+import type { NetworkMatch } from "../network/network-wait.js";
+import type { UrlPattern } from "../network/url-match.js";
+import { type PageEventName, type PageEvents, type WaitableEventName, type WaitForEventOptions, type WaitOptions } from "./page-events.js";
+import { PageLocating } from "./page-locating.js";
+/** @internal Events, network, routes, logs, dialogs and transfers */
+export declare abstract class PageObserving extends PageLocating {
+    /**
+     * Starts following this page's requests now. Tracking only sees requests made after it started, so the
+     * browser calls this when it opens a page; without it, tracking starts on first use. Does nothing when
+     * config `network.track` is false.
+     */
+    startNetworkTracking(): Promise<void>;
+    /**
+     * Waits until no request has been in flight for `idleTime` ms (default config `network.idleTime`, then 500).
+     * Long-lived requests (server-sent events, long polling) keep the page busy until `timeout`.
+     */
+    waitForNetworkIdle(options?: {
+        idleTime?: number;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Listens for page events: `request`, `response`, `requestfailed` (network), `dialog` (a JavaScript dialog or
+     * `beforeunload` prompt opened; answer it with `dialog.accept()` / `dialog.dismiss()`), `console` (a `console.*` call)
+     * and `pageerror` (an uncaught exception). Starts what the event needs.
+     * A dialog nobody answers is dismissed automatically (a `beforeunload` prompt is accepted), so it cannot hang a test.
+     * @example
+     *  page.on("dialog", (dialog) => dialog.accept());
+     */
+    on<E extends PageEventName>(event: E, listener: (...args: PageEvents[E]) => void): this;
+    once<E extends PageEventName>(event: E, listener: (...args: PageEvents[E]) => void): this;
+    off<E extends PageEventName>(event: E, listener: (...args: PageEvents[E]) => void): this;
+    private trackInBackground;
+    /** Starts following downloads; the browser does this when it opens a page, `page.on("download")` and `waitForDownload` when needed */
+    startDownloadTracking(): Promise<void>;
+    /** Starts following file pickers; the browser does this when it opens a page, `page.on("filechooser")` and `waitForFileChooser` when needed */
+    startFileChooserTracking(): Promise<void>;
+    /**
+     * Resolves with the next download this page starts (when it starts, not when it ends: use `download.path()` for that).
+     * Call it before the download is triggered, or pass `trigger`, which runs once the wait is set up.
+     * @example
+     *  const download = await page.waitForDownload({ trigger: () => link.click() });
+     *  const file = await download.path();
+     */
+    waitForDownload(options?: WaitOptions): Promise<Download>;
+    /**
+     * Resolves with the next file picker the page opens (a click on an `<input type=file>` or its label). Nothing shows
+     * on screen: answer it with `chooser.setFiles(...)`.
+     * @example
+     *  const chooser = await page.waitForFileChooser({ trigger: () => page.locator("label[@for='avatar']").click() });
+     *  await chooser.setFiles("./fixtures/avatar.png");
+     */
+    waitForFileChooser(options?: WaitOptions): Promise<FileChooser>;
+    /**
+     * Playwright-style wait for one page event: `download`, `filechooser`, `request` or `response`. Same as the named
+     * `waitFor…` method, with an optional predicate (a function, or `predicate` in the options). Call it before the event
+     * is caused, or pass `trigger`, which runs once the wait is set up.
+     * @example
+     *  const chooser = await page.waitForEvent("filechooser", { trigger: () => page.getByText("Upload file").click() });
+     *  await chooser.setFiles("./myfile.pdf");
+     */
+    waitForEvent<E extends WaitableEventName>(event: E, optionsOrPredicate?: ((item: PageEvents[E][0]) => boolean) | WaitForEventOptions<PageEvents[E][0]>): Promise<PageEvents[E][0]>;
+    /**
+     * Starts keeping response bodies, which is what makes `response.body()` possible: the browser only keeps a body
+     * when this ran before the request started. `page.on("response")` and `waitForResponse` call it; config
+     * `network.collectBodies` calls it when the browser opens the page.
+     */
+    startBodyCollection(): Promise<void>;
+    /**
+     * Resolves with the next response of this page whose URL matches (a pattern, see `route`) or that the function
+     * accepts. Call it before the request is made, or pass `trigger`, which runs once the wait is set up.
+     * @example
+     *  const response = await page.waitForResponse("**\/api/users", { trigger: () => button.click() });
+     *  const users = await response.json();
+     */
+    waitForResponse(match: NetworkMatch<Response>, options?: WaitOptions): Promise<Response>;
+    /** Like `waitForResponse`, for requests */
+    waitForRequest(match: NetworkMatch<NetworkRequest>, options?: WaitOptions): Promise<NetworkRequest>;
+    /** Turns the browser's HTTP cache off (`true`) or back on for this page: every request then goes to the server */
+    setCacheDisabled(disabled: boolean): Promise<void>;
+    /**
+     * Sends requests whose URL matches to `handler`, which must answer with `route.fulfill()`, `route.continue()`,
+     * `route.abort()` or `route.fallback()` (await the answer: a handler that returns first lets the request continue).
+     * A string without `*` is an exact URL, with `*` / `**` a glob (`*` stops at `/`), a RegExp is tested on the URL.
+     * Routes added later are asked first. Errors a handler throws fail the request and, in the runner, the test.
+     * @example
+     *  await page.route("**\/api/users", (route) => route.fulfill({ json: [{ id: 1 }] }));
+     *  await page.route(/\.(png|jpg)$/, (route) => route.abort());
+     */
+    route(url: UrlPattern, handler: RouteHandler): Promise<void>;
+    /** Removes the routes for `url` (only the one with `handler`, when given) */
+    unroute(url: UrlPattern, handler?: RouteHandler): Promise<void>;
+    unrouteAll(): Promise<void>;
+    /** Errors thrown by route handlers so far */
+    routeErrors(): readonly Error[];
+    /**
+     * Starts collecting the page's console output and uncaught exceptions. The browser does this when it opens a page so
+     * early output is kept; `page.on("console" | "pageerror")` starts it when needed.
+     */
+    startLogging(): Promise<void>;
+    /** The newest console and error entries of this page (empty until logging started), oldest first */
+    getLogs(): readonly LogRecord[];
+    /** Uncaught exceptions of the page since logging started or `clearLogs()` */
+    pageErrors(): readonly PageError[];
+    /** How many entries fell out of the page's log buffer */
+    get logsDropped(): number;
+    clearLogs(): void;
+    /** Resolves once everything the page logged before the call has arrived: events and replies share one ordered connection */
+    syncLogs(): Promise<void>;
+    /** Tells the runner not to fail this test on uncaught page exceptions (config `logs.failOnPageError`) */
+    allowPageErrors(): void;
+    get pageErrorsAllowed(): boolean;
+    /** Starts watching for dialogs; the browser does this when it opens a page, `page.on("dialog")` when needed */
+    startDialogHandling(): Promise<void>;
+}