@itmetsam/samurai-framework 0.22.10 → 0.22.11

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

@@ -0,0 +1,151 @@
+import { type PdfOptions } from "./pdf.js";
+import type { RuntimeUseOptions } from "../types/use.js";
+import { type ScreenshotOptions } from "./screenshot.js";
+import type { UrlPattern } from "../network/url-match.js";
+import type { LoadState, NavigateOptions, NavigationResult } from "./page-navigation.js";
+import { type ReadinessState } from "./page-settings.js";
+import type { Viewport } from "./viewport.js";
+import type { PreloadHandle } from "../script/preload.js";
+import type { PageFunction } from "../script/call-function.js";
+import { PageCore } from "./page-core.js";
+/** @internal Navigation, content, viewport and the other things a page does */
+export declare abstract 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 });
+     */
+    addInitScript(script: string | ((arg?: any) => void), arg?: unknown): Promise<PreloadHandle>;
+    /** Sets the base that relative `goto` URLs resolve against; `undefined` falls back to the run's baseURL */
+    setBaseURL(url: string | undefined): void;
+    /** @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: string, method?: string): string;
+    /**
+     * 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: string, options?: NavigateOptions): Promise<NavigationResult>;
+    /**
+     * 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: string, options?: NavigateOptions | ReadinessState, protocol?: "http" | "https"): Promise<NavigationResult>;
+    /**
+     * Reloads the page and resolves when it reached `wait` (default like `navigateTo`). Firefox does not support
+     * `ignoreCache`; asking for it throws UnsupportedOperationError.
+     */
+    reload(options?: {
+        wait?: ReadinessState;
+        timeout?: number;
+        ignoreCache?: boolean;
+    }): Promise<NavigationResult>;
+    /** Goes back one entry in the history. False when there is none to go back to */
+    goBack(): Promise<boolean>;
+    /** Goes forward one entry in the history. False when there is none */
+    goForward(): Promise<boolean>;
+    /** The URL of the page now */
+    url(): Promise<string>;
+    /**
+     * 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: UrlPattern | ((url: URL) => boolean), options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
+    /** The markup of the document now, doctype included */
+    content(): Promise<string>;
+    /**
+     * 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>");
+     */
+    setContent(html: string, options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
+    /** The title of the document now */
+    title(): Promise<string>;
+    /**
+     * 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);
+     */
+    evaluate<R = unknown, A = unknown>(fn: PageFunction<[A], R>, arg?: A): Promise<R>;
+    /**
+     * 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 });
+     */
+    setViewport(viewport: Viewport | null): Promise<void>;
+    /** @internal Chrome: lays this page out like a phone from now on (`use.isMobile`), including the size it has now */
+    setMobileLayout(): Promise<void>;
+    /** Playwright's name for `setViewport` */
+    setViewportSize(size: Viewport): Promise<void>;
+    /**
+     * 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(): {
+        width: number;
+        height: number;
+    } | null;
+    /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
+    applyDefaultViewport(): Promise<void>;
+    /**
+     * Takes a screenshot and returns the image (also written to `options.path`).
+     * @example
+     *  await page.screenshot({ path: "out/home.png", fullPage: true });
+     */
+    screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+    /** Waits `ms` milliseconds. Prefer waiting for something (an assertion, `waitForNetworkIdle`) when you can */
+    waitForTimeout(ms: number): Promise<void>;
+    /** Renders the page as a PDF and returns it (also written to `options.path`) */
+    pdf(options?: PdfOptions): Promise<Buffer>;
+    /**
+     * 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 });
+     */
+    use(options: RuntimeUseOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    grantPermission(name: string, options?: {
+        origin?: string;
+    }): Promise<void>;
+    /**
+     * 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?: LoadState, options?: {
+        timeout?: number;
+    }): Promise<void>;
+}

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;
+}