@itmetsam/samurai-framework 0.22.10 → 0.22.11

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

package/dist/browser/page-observing.js

@@ -0,0 +1,194 @@
+import logger from "../logger/index.js";
+import { Response } from "../network/response.js";
+import { startSources, waitForEventOn, } from "./page-events.js";
+import { PageLocating } from "./page-locating.js";
+/** @internal Events, network, routes, logs, dialogs and transfers */
+export 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() {
+        return this.net.startTracking();
+    }
+    /**
+     * 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 = {}) {
+        return this.net.waitForIdle(options);
+    }
+    /**
+     * 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(event, listener) {
+        this.pageEvents.on(event, listener);
+        this.trackInBackground(event);
+        return this;
+    }
+    once(event, listener) {
+        this.pageEvents.once(event, listener);
+        this.trackInBackground(event);
+        return this;
+    }
+    off(event, listener) {
+        this.pageEvents.off(event, listener);
+        return this;
+    }
+    trackInBackground(event) {
+        const start = {
+            dialogs: () => this.startDialogHandling(),
+            downloads: () => this.startDownloadTracking(),
+            filechoosers: () => this.startFileChooserTracking(),
+            logs: () => this.startLogging(),
+            network: () => this.startNetworkTracking(),
+            bodies: () => this.startBodyCollection(),
+        };
+        startSources(event, start, (err) => logger.error("Could not start listening for %s", event, { err }));
+    }
+    /** Starts following downloads; the browser does this when it opens a page, `page.on("download")` and `waitForDownload` when needed */
+    startDownloadTracking() {
+        return this.transfers.startDownloadTracking();
+    }
+    /** Starts following file pickers; the browser does this when it opens a page, `page.on("filechooser")` and `waitForFileChooser` when needed */
+    startFileChooserTracking() {
+        return this.transfers.startFileChooserTracking();
+    }
+    /**
+     * 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();
+     */
+    async waitForDownload(options = {}) {
+        this.assertOpen();
+        return this.transfers.waitForDownload(options);
+    }
+    /**
+     * 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");
+     */
+    async waitForFileChooser(options = {}) {
+        this.assertOpen();
+        return this.transfers.waitForFileChooser(options);
+    }
+    /**
+     * 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");
+     */
+    async waitForEvent(event, optionsOrPredicate = {}) {
+        return waitForEventOn({
+            request: (accepts, options) => this.waitForRequest(accepts, options),
+            response: (accepts, options) => this.waitForResponse(accepts, options),
+            download: (options, accepts) => {
+                this.assertOpen();
+                return this.transfers.waitForDownload(options, accepts);
+            },
+            filechooser: (options, accepts) => {
+                this.assertOpen();
+                return this.transfers.waitForFileChooser(options, accepts);
+            },
+        }, event, optionsOrPredicate);
+    }
+    /**
+     * 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() {
+        return this.net.startBodyCollection();
+    }
+    /**
+     * 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, options = {}) {
+        return this.net.waitForResponse(match, options);
+    }
+    /** Like `waitForResponse`, for requests */
+    waitForRequest(match, options = {}) {
+        return this.net.waitForRequest(match, options);
+    }
+    /** Turns the browser's HTTP cache off (`true`) or back on for this page: every request then goes to the server */
+    setCacheDisabled(disabled) {
+        return this.net.setCacheDisabled(disabled);
+    }
+    /**
+     * 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());
+     */
+    async route(url, handler) {
+        this.assertOpen();
+        await this.net.route(url, handler);
+    }
+    /** Removes the routes for `url` (only the one with `handler`, when given) */
+    unroute(url, handler) {
+        return this.net.unroute(url, handler);
+    }
+    unrouteAll() {
+        return this.net.unrouteAll();
+    }
+    /** Errors thrown by route handlers so far */
+    routeErrors() {
+        return this.net.routeErrors();
+    }
+    /**
+     * 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.
+     */
+    async startLogging() {
+        await this.logging.start();
+    }
+    /** The newest console and error entries of this page (empty until logging started), oldest first */
+    getLogs() {
+        return this.logging.entries();
+    }
+    /** Uncaught exceptions of the page since logging started or `clearLogs()` */
+    pageErrors() {
+        return this.logging.errors();
+    }
+    /** How many entries fell out of the page's log buffer */
+    get logsDropped() {
+        return this.logging.dropped;
+    }
+    clearLogs() {
+        this.logging.clear();
+    }
+    /** Resolves once everything the page logged before the call has arrived: events and replies share one ordered connection */
+    async syncLogs() {
+        await this.biDiConnector.send("session.status", {});
+    }
+    /** Tells the runner not to fail this test on uncaught page exceptions (config `logs.failOnPageError`) */
+    allowPageErrors() {
+        this.logging.allowErrors();
+    }
+    get pageErrorsAllowed() {
+        return this.logging.errorsAreAllowed;
+    }
+    /** Starts watching for dialogs; the browser does this when it opens a page, `page.on("dialog")` when needed */
+    startDialogHandling() {
+        return this.dialogs.start();
+    }
+}