@itmetsam/samurai-framework 0.22.10 → 0.22.11

package/dist/browser/page.d.ts

@@ -1,374 +1,23 @@
-import type { APIRequestContext } from "../request/api-request-context.js";
-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 type { NetworkRequest } from "../network/network-tracker.js";
 import type { Recorder, RecorderOptions } from "../recorder/recorder.js";
-import { ContextTree } from "./context-tree.js";
-import type { BrowserContext } from "./browser-context.js";
-import { type PdfOptions } from "./pdf.js";
-import type { RuntimeUseOptions } from "../types/use.js";
-import type { Download } from "./download.js";
-import type { FileChooser } from "./file-chooser.js";
-import { type ScreenshotOptions } from "./screenshot.js";
-import type { Evidence } from "./evidence.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 { PageObserving } from "./page-observing.js";
+import type { PageEventName, WaitableEventName, WaitForEventOptions, WaitOptions } from "./page-events.js";
+import type { PageSettings, ReadinessState } from "./page-settings.js";
 import type { LoadState, NavigateOptions, NavigationResult } from "./page-navigation.js";
-import Keyboard from "./keyboard.js";
-import Mouse from "./mouse.js";
-import { type PageEventName, type PageEvents, type WaitableEventName, type WaitForEventOptions, type WaitOptions } from "./page-events.js";
+/** @public */
 export type { PageEventName, WaitableEventName, WaitForEventOptions, WaitOptions, };
-import { type PageSettings, type ReadinessState } from "./page-settings.js";
+/** @public */
 export type { PageSettings, ReadinessState };
-import type { Viewport } from "./viewport.js";
-import type { PreloadHandle } from "../script/preload.js";
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-import type { PageFunction } from "../script/call-function.js";
-import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+/** @public */
 export type { LoadState, NavigateOptions, NavigationResult };
-export default class Page {
-    private biDiConnector;
-    private id;
-    private lazyTree;
-    private helperRealm;
-    private initScripts;
-    private pageConfig;
-    private locators;
-    /** 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;
-    private pageEvents;
-    private documents;
-    private nav;
-    private net;
-    private dialogs;
-    private logging;
-    private isClosed;
-    private browserContext;
-    private transfers;
-    private evidence;
-    private viewport;
-    /** `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>;
-    /**
-     * 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;
-    /**
-     * 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>;
+export default class Page extends PageObserving {
     /**
      * Starts recording what a person does in the page as steps (see `Recorder`). The page must be driven by
      * a person; stop with `recorder.stop()`.
      */
     record(options: RecorderOptions): Promise<Recorder>;
-    /** Removes everything the page registered in the browser: init scripts, framework helpers and event subscriptions */
-    dispose(): Promise<void>;
-    /** 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>;
     /**
      * What the browser sets up on every page it opens: the default size, then everything that has to be listening
      * before the page does anything (requests, dialogs, logs, downloads, file pickers). Safe to call again.
      */
     startTracking(): 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>;
-    /** @internal The runner gives each test its own evidence folder */
-    setEvidence(evidence: Evidence | undefined): void;
-    /** 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>;
-    /** 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>;
-    /**
-     * 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>;
-    /** True once `close()` has run */
-    get closed(): boolean;
-    private assertOpen;
-    /**
-     * 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>;
-    /**
-     * 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>;
-    /**
-     * 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>;
-    /**
-     * 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;
-    /** 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>;
 }