@types/k6 1.1.1 → 1.3.0

k6/browser/index.d.ts

@@ -1377,6 +1377,19 @@ export interface ElementHandle extends JSHandle {
 
     /**
      * Select one or more options of a `<select>` element which match the values.
+     *
+     * @example
+     * ```js
+     * // Single selection matching the value or label
+     * handle.selectOption('blue');
+     *
+     * // single selection matching the label
+     * handle.selectOption({ label: 'Blue' });
+     *
+     * // multiple selection
+     * handle.selectOption(['red', 'green', 'blue']);
+     * ```
+     *
      * @param values Values of options to select.
      * @param options Element handle options.
      * @returns List of selected options.
@@ -1567,6 +1580,19 @@ export interface Frame {
     /**
      * Select the given options and return the array of option values of the first element
      * found that matches the selector.
+     *
+     * @example
+     * ```js
+     * // Single selection matching the value or label
+     * frame.selectOption('blue');
+     *
+     * // single selection matching the label
+     * frame.selectOption({ label: 'Blue' });
+     *
+     * // multiple selection
+     * frame.selectOption(['red', 'green', 'blue']);
+     * ```
+     *
      * @param selector The selector to use.
      * @param values The values to select.
      * @returns The array of option values of the first element found.
@@ -1693,10 +1719,18 @@ export interface Frame {
 
     /**
      * Сreates and returns a new locator for this frame.
+     *
+     * @example
+     * ```js
+     * const frame = page.frames()[1];
+     * const submitButton = frame.locator('button', { hasText: 'Pizza, Please!' });
+     * ```
+     *
      * @param selector The selector to use.
+     * @param options Options to use for filtering.
      * @returns The new locator.
      */
-    locator(selector: string): Locator;
+    locator(selector: string, options?: LocatorOptions): Locator;
 
     /**
      * Get the `innerHTML` attribute of the first element found that matches the selector.
@@ -1841,7 +1875,83 @@ export interface Frame {
      * @param options The options to use.
      * @returns A promise that resolves to the response of the navigation when it happens.
      */
-    waitForNavigation(options?: ContentLoadOptions): Promise<Response | null>;
+    waitForNavigation(options?: {
+        /**
+         * Maximum operation time in milliseconds. Defaults to `30` seconds. The
+         * default value can be changed via the
+         * browserContext.setDefaultNavigationTimeout(timeout),
+         * browserContext.setDefaultTimeout(timeout),
+         * page.setDefaultNavigationTimeout(timeout) or
+         * page.setDefaultTimeout(timeout) methods.
+         *
+         * Setting the value to `0` will disable the timeout.
+         */
+        timeout?: number;
+
+        /**
+         * An exact string or regex pattern to match while waiting for the
+         * navigation. Note that if the parameter is a string, the method will
+         * wait for navigation to URL that is exactly equal to the string.
+         */
+        url?: string | RegExp;
+
+        /**
+         * When to consider operation succeeded, defaults to `load`. Events can be
+         * either:
+         * - `'domcontentloaded'` - consider operation to be finished when the
+         * `DOMContentLoaded` event is fired.
+         * - `'load'` - consider operation to be finished when the `load` event is
+         * fired.
+         * - `'networkidle'` - **DISCOURAGED** consider operation to be finished
+         * when there are no network connections for at least `500` ms. Don't use
+         * this method for testing especially with chatty websites where the event
+         * may never fire, rely on web assertions to assess readiness instead.
+         */
+        waitUntil?: "load" | "domcontentloaded" | "networkidle";
+    }): Promise<Response | null>;
+
+    /**
+     * Waits for the page to navigate to the specified URL.
+     *
+     * @example
+     * ```js
+     * await page.locator('a[href="/login"]').click();
+     * await page.waitForURL(/.*\/login$/);
+     * ```
+     *
+     * @param url An exact match or regular expression to match the URL.
+     * @param options Options to use.
+     */
+    waitForURL(
+        url: string | RegExp,
+        options?: {
+            /**
+             * Maximum operation time in milliseconds. Defaults to `30` seconds.
+             * The default value can be changed via the
+             * browserContext.setDefaultNavigationTimeout(timeout),
+             * browserContext.setDefaultTimeout(timeout),
+             * page.setDefaultNavigationTimeout(timeout) or
+             * page.setDefaultTimeout(timeout) methods.
+             *
+             * Setting the value to `0` will disable the timeout.
+             */
+            timeout?: number;
+
+            /**
+             * When to consider operation succeeded, defaults to `load`. Events can be
+             * either:
+             * - `'domcontentloaded'` - consider operation to be finished when the
+             * `DOMContentLoaded` event is fired.
+             * - `'load'` - consider operation to be finished when the `load` event is
+             * fired.
+             * - `'networkidle'` - **DISCOURAGED** consider operation to be finished
+             * when there are no network connections for at least `500` ms. Don't use
+             * this method for testing especially with chatty websites where the event
+             * may never fire, rely on web assertions to assess readiness instead.
+             */
+            waitUntil?: "load" | "domcontentloaded" | "networkidle";
+        },
+    ): Promise<void>;
 
     /**
      * Wait for the given selector to match the waiting criteria.
@@ -1859,145 +1969,894 @@ export interface Frame {
      * @param timeout The timeout to wait for.
      */
     waitForTimeout(timeout: number): Promise<void>;
-}
-
-/**
- * JSHandle represents an in-page JavaScript object.
- */
-export interface JSHandle<T = any> {
-    /**
-     * Returns either `null` or the object handle itself, if the object handle is
-     * an instance of `ElementHandle`.
-     * @returns The ElementHandle if available.
-     */
-    asElement(): Promise<ElementHandle | null>;
 
     /**
-     * Stops referencing the element handle.
-     */
-    dispose(): Promise<void>;
-
-    /**
-     * Evaluates the page function and returns its return value.
-     * This method passes this handle as the first argument to the page function.
-     * @param pageFunction The function to be evaluated.
-     * @param args The arguments to pass to the page function.
-     * @returns The return value of `pageFunction`.
-     */
-    evaluate<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg): Promise<R>;
+     * Returns {@link Locator} to the element with the corresponding role.
+     *
+     * @example
+     * ```js
+     * const locator = frame.getByRole('button', { name: 'Pizza, Please!' });
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param role The role of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding role.
+     */
+    getByRole(
+        role:
+            | "alert"
+            | "alertdialog"
+            | "application"
+            | "article"
+            | "banner"
+            | "blockquote"
+            | "button"
+            | "caption"
+            | "cell"
+            | "checkbox"
+            | "code"
+            | "columnheader"
+            | "combobox"
+            | "complementary"
+            | "contentinfo"
+            | "definition"
+            | "dialog"
+            | "directory"
+            | "document"
+            | "emphasis"
+            | "feed"
+            | "figure"
+            | "form"
+            | "generic"
+            | "grid"
+            | "gridcell"
+            | "group"
+            | "heading"
+            | "img"
+            | "insertion"
+            | "link"
+            | "list"
+            | "listbox"
+            | "listitem"
+            | "log"
+            | "main"
+            | "marquee"
+            | "math"
+            | "menu"
+            | "menubar"
+            | "menuitem"
+            | "menuitemcheckbox"
+            | "menuitemradio"
+            | "meter"
+            | "navigation"
+            | "none"
+            | "note"
+            | "option"
+            | "presentation"
+            | "progressbar"
+            | "radio"
+            | "radiogroup"
+            | "region"
+            | "row"
+            | "rowgroup"
+            | "rowheader"
+            | "scrollbar"
+            | "search"
+            | "searchbox"
+            | "separator"
+            | "slider"
+            | "spinbutton"
+            | "status"
+            | "strong"
+            | "subscript"
+            | "superscript"
+            | "switch"
+            | "tab"
+            | "table"
+            | "tablist"
+            | "tabpanel"
+            | "term"
+            | "textbox"
+            | "time"
+            | "timer"
+            | "toolbar"
+            | "tooltip"
+            | "tree"
+            | "treegrid"
+            | "treeitem",
+        options?: {
+            /**
+             * Whether the accessible `options.name` should be checked exactly for equality.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
 
-    /**
-     * Evaluates the page function and returns a `JSHandle`.
-     * This method passes this handle as the first argument to the page function.
-     * Unlike `evaluate`, `evaluateHandle` returns the value as a `JSHandle`
-     * @param pageFunction The function to be evaluated.
-     * @param args The arguments to pass to the page function.
-     * @returns A JSHandle of the return value of `pageFunction`.
-     */
-    evaluateHandle<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg): Promise<JSHandle<R>>;
+            /**
+             * Whether to include elements that are normally excluded from the accessibility tree.
+             *
+             * @defaultValue false
+             */
+            includeHidden?: boolean;
 
-    /**
-     * Fetches a map with own property names of of the `JSHandle` with their values as
-     * `JSHandle` instances.
-     * @returns A map with property names as keys and `JSHandle` instances for the property values.
-     */
-    getProperties(): Promise<Map<string, JSHandle>>;
+            /**
+             * A number attribute that is traditionally used for headings h1-h6.
+             */
+            level?: number;
 
-    /**
-     * Fetches a JSON representation of the object.
-     * @returns A JSON representation of the object.
-     */
-    jsonValue(): Promise<any>;
-}
+            /**
+             * An accessible name for the element, such as a text in a button or a label for an input.
+             */
+            name?: string | RegExp;
 
-/**
- * Keyboard provides an API for managing a virtual keyboard.
- */
-export interface Keyboard {
-    /**
-     * Sends a key down message to a session target.
-     * A superset of the key values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values).
-     * @param key Name of key to press, such as `ArrowLeft`.
-     */
-    down(key: string): Promise<void>;
+            /**
+             * A boolean attribute that can be used to indicate if a checkbox is checked or not.
+             */
+            checked?: boolean;
 
-    /**
-     * Dispatches an `input` event with the given `text`.
-     * This method does not emit `keyDown`, `keyUp` or `keyPress` events.
-     * @param text Event text.
-     */
-    insertText(text: string): Promise<void>;
+            /**
+             * A boolean attribute that can be used to indicate if an element is disabled or not.
+             */
+            disabled?: boolean;
 
-    /**
-     * Sends a key press message to a session target.
-     * A press message consists of successive key down and up messages.
-     * @param key Sequence of keys to press.
-     * @param options Specifies the typing options.
-     */
-    press(key: string, options?: { delay?: number }): Promise<void>;
+            /**
+             * A boolean attribute that can be used to indicate if an element is expanded or not.
+             */
+            expanded?: boolean;
 
-    /**
-     * Type sends a `press` message to a session target for each character in text.
-     * It sends an insertText message if a character is not among
-     * valid characters in the keyboard's layout.
-     * Modifier keys `Shift`, `Control`, `Alt`, `Meta` are _not_ respected.
-     * @param text A text to type into a focused element.
-     * @param options Specifies the typing options.
-     */
-    type(text: string, options?: { delay?: number }): Promise<void>;
+            /**
+             * A boolean attribute that can be used to indicate if an element is pressed or not.
+             */
+            pressed?: boolean;
 
-    /**
-     * Sends a key up message to a session target.
-     * A superset of the key values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values).
-     * @param key Name of key to release, such as `ArrowLeft`.
-     */
-    up(key: string): Promise<void>;
-}
+            /**
+             * A boolean attribute that can be used to indicate if an element is selected or not.
+             */
+            selected?: boolean;
+        },
+    ): Locator;
 
-/**
- * The Locator API makes it easier to work with dynamically changing elements.
- * Some of the benefits of using it over existing ways to locate an element
- * (e.g. Page.$()) include:
- *
- * - Helps with writing robust tests by finding an element even if the
- * underlying frame navigates.
- * - Makes it easier to work with dynamic web pages and SPAs built with Svelte,
- * React, Vue, etc.
- */
-export interface Locator {
     /**
-     * Clears text boxes and input fields of any existing values.
-     *
-     * **Usage**
+     * Returns {@link Locator} to the element with the corresponding alt text.
      *
+     * @example
      * ```js
-     * // Clears the input field matching the selector.
-     * page.locator('input[name="login"]').clear();
+     * const locator = frame.getByAltText('pizza');
+     *
+     * await locator.click();
      * ```
      *
+     * @param altText The alt text of the element.
      * @param options Options to use.
+     * @returns The locator to the element with the corresponding alt text.
      */
-    clear(options?: ElementHandleOptions): Promise<void>;
+    getByAltText(
+        altText: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
 
     /**
-     * Mouse click on the chosen element.
+     * Returns {@link Locator} to the element with the corresponding label text.
+     *
+     * @example
+     * ```js
+     * const locator = frame.getByLabel('Password');
+     *
+     * await locator.fill('my-password');
+     * ```
+     *
+     * @param label The label text of the element.
      * @param options Options to use.
-     * @returns Promise which resolves when the element is successfully clicked.
+     * @returns The locator to the element with the corresponding label text.
      */
-    click(options?: MouseMoveOptions & MouseMultiClickOptions): Promise<void>;
+    getByLabel(
+        label: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
 
     /**
-     * Returns the number of elements matching the selector.
+     * Allows locating elements by their text content. Returns {@link Locator}.
      *
-     * **Usage**
+     * Consider the following DOM structure:
+     *
+     * ```html
+     * <div>Hello <span>world</span></div>
+     * <div>Hello</div>
+     * ```
+     *
+     * You can locate by text substring, exact string, or a regular expression:
      *
+     * @example
      * ```js
-     * const count = await page.locator('input').count();
+     * // Matches <span>
+     * frame.getByText('world');
+     *
+     * // Matches first <div>
+     * frame.getByText('Hello world');
+     *
+     * // Matches second <div>
+     * frame.getByText('Hello', { exact: true });
+     *
+     * // Matches both <div>s
+     * frame.getByText(/Hello/);
+     *
+     * // Matches second <div>
+     * frame.getByText(/^hello$/i);
      * ```
      *
-     * @returns Promise which resolves with the number of elements matching the selector.
+     * Matching by text always normalizes whitespace, even with exact match. For
+     * example, it turns multiple spaces into one, turns line breaks into spaces
+     * and ignores leading and trailing whitespace.
+     *
+     * Input elements of the type `button` and `submit` are matched by their
+     * `value` instead of the text content. For example, locating by text
+     * `"Log in"` matches `<input type=button value="Log in">`.
+     *
+     * @param text Text to locate the element by.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding text content.
      */
-    count(): Promise<number>;
+    getByText(
+        text: string | RegExp,
+        options?: {
+            /**
+             * Whether to find an exact match: case-sensitive and whole-string.
+             * Default to false. Ignored when locating by a regular expression.
+             * Note that exact match still trims whitespace.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding test ID.
+     * Note that this method only supports the `data-testid` attribute.
+     *
+     * @example
+     * HTML:
+     * ```html
+     * <button data-testid="submit-button">Submit</button>
+     * ```
+     *
+     * JavaScript:
+     * ```js
+     * const locator = frame.getByTestId('submit-button');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param testId The test ID of the element.
+     * @returns The locator to the element with the corresponding test ID.
+     */
+    getByTestId(testId: string | RegExp): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding placeholder text.
+     *
+     * @example
+     * ```js
+     * const locator = frame.getByPlaceholder('name@example.com');
+     *
+     * await locator.fill('my.name@example.com');
+     * ```
+     *
+     * @param placeholder The placeholder text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding placeholder text.
+     */
+    getByPlaceholder(
+        placeholder: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding title text.
+     *
+     * @example
+     * ```js
+     * const locator = frame.getByTitle('Information box');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param title The title text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding title text.
+     */
+    getByTitle(
+        title: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
+}
+
+/**
+ * FrameLocator makes it easier to locate elements within an `iframe` on the
+ * page. `FrameLocator` are created by calling `page.locator(selector).contentFrame()`.
+ * It works in the same way as `Locator` instances.
+ */
+export interface FrameLocator {
+    /**
+     * The method finds all elements matching the selector and creates a new
+     * locator that matches all of them. This method can be used to further
+     * refine the locator by chaining additional selectors.
+     *
+     * @example
+     * ```js
+     * const frame = page.frameLocator('iframe');
+     * const rows = frame.locator('table tr');
+     * const cell = rows.locator('.selected');
+     *
+     * // Use with options to filter by text
+     * const submitButton = frame.locator('button', { hasText: 'Submit' });
+     * ```
+     *
+     * @param selector A selector to use when resolving DOM element.
+     * @param options Options to use for filtering.
+     * @returns The new locator.
+     */
+    locator(selector: string, options?: LocatorOptions): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding role.
+     *
+     * @example
+     * ```js
+     * const locator = frameLocator.getByRole('button', { name: 'Pizza, Please!' });
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param role The role of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding role.
+     */
+    getByRole(
+        role:
+            | "alert"
+            | "alertdialog"
+            | "application"
+            | "article"
+            | "banner"
+            | "blockquote"
+            | "button"
+            | "caption"
+            | "cell"
+            | "checkbox"
+            | "code"
+            | "columnheader"
+            | "combobox"
+            | "complementary"
+            | "contentinfo"
+            | "definition"
+            | "dialog"
+            | "directory"
+            | "document"
+            | "emphasis"
+            | "feed"
+            | "figure"
+            | "form"
+            | "generic"
+            | "grid"
+            | "gridcell"
+            | "group"
+            | "heading"
+            | "img"
+            | "insertion"
+            | "link"
+            | "list"
+            | "listbox"
+            | "listitem"
+            | "log"
+            | "main"
+            | "marquee"
+            | "math"
+            | "menu"
+            | "menubar"
+            | "menuitem"
+            | "menuitemcheckbox"
+            | "menuitemradio"
+            | "meter"
+            | "navigation"
+            | "none"
+            | "note"
+            | "option"
+            | "presentation"
+            | "progressbar"
+            | "radio"
+            | "radiogroup"
+            | "region"
+            | "row"
+            | "rowgroup"
+            | "rowheader"
+            | "scrollbar"
+            | "search"
+            | "searchbox"
+            | "separator"
+            | "slider"
+            | "spinbutton"
+            | "status"
+            | "strong"
+            | "subscript"
+            | "superscript"
+            | "switch"
+            | "tab"
+            | "table"
+            | "tablist"
+            | "tabpanel"
+            | "term"
+            | "textbox"
+            | "time"
+            | "timer"
+            | "toolbar"
+            | "tooltip"
+            | "tree"
+            | "treegrid"
+            | "treeitem",
+        options?: {
+            /**
+             * Whether the accessible `options.name` should be checked exactly for equality.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+
+            /**
+             * Whether to include elements that are normally excluded from the accessibility tree.
+             *
+             * @defaultValue false
+             */
+            includeHidden?: boolean;
+
+            /**
+             * A number attribute that is traditionally used for headings h1-h6.
+             */
+            level?: number;
+
+            /**
+             * An accessible name for the element, such as a text in a button or a label for an input.
+             */
+            name?: string | RegExp;
+
+            /**
+             * A boolean attribute that can be used to indicate if a checkbox is checked or not.
+             */
+            checked?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is disabled or not.
+             */
+            disabled?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is expanded or not.
+             */
+            expanded?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is pressed or not.
+             */
+            pressed?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is selected or not.
+             */
+            selected?: boolean;
+        },
+    ): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding alt text.
+     *
+     * @example
+     * ```js
+     * const locator = frameLocator.getByAltText('pizza');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param altText The alt text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding alt text.
+     */
+    getByAltText(
+        altText: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding label text.
+     *
+     * @example
+     * ```js
+     * const locator = frameLocator.getByLabel('Password');
+     *
+     * await locator.fill('my-password');
+     * ```
+     *
+     * @param label The label text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding label text.
+     */
+    getByLabel(
+        label: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
+
+    /**
+     * Allows locating elements by their text content. Returns {@link Locator}.
+     *
+     * Consider the following DOM structure:
+     *
+     * ```html
+     * <div>Hello <span>world</span></div>
+     * <div>Hello</div>
+     * ```
+     *
+     * You can locate by text substring, exact string, or a regular expression:
+     *
+     * @example
+     * ```js
+     * // Matches <span>
+     * frameLocator.getByText('world');
+     *
+     * // Matches first <div>
+     * frameLocator.getByText('Hello world');
+     *
+     * // Matches second <div>
+     * frameLocator.getByText('Hello', { exact: true });
+     *
+     * // Matches both <div>s
+     * frameLocator.getByText(/Hello/);
+     *
+     * // Matches second <div>
+     * frameLocator.getByText(/^hello$/i);
+     * ```
+     *
+     * Matching by text always normalizes whitespace, even with exact match. For
+     * example, it turns multiple spaces into one, turns line breaks into spaces
+     * and ignores leading and trailing whitespace.
+     *
+     * Input elements of the type `button` and `submit` are matched by their
+     * `value` instead of the text content. For example, locating by text
+     * `"Log in"` matches `<input type=button value="Log in">`.
+     *
+     * @param text Text to locate the element by.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding text content.
+     */
+    getByText(
+        text: string | RegExp,
+        options?: {
+            /**
+             * Whether to find an exact match: case-sensitive and whole-string.
+             * Default to false. Ignored when locating by a regular expression.
+             * Note that exact match still trims whitespace.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding test ID.
+     * Note that this method only supports the `data-testid` attribute.
+     *
+     * @example
+     * HTML:
+     * ```html
+     * <button data-testid="submit-button">Submit</button>
+     * ```
+     *
+     * JavaScript:
+     * ```js
+     * const locator = frameLocator.getByTestId('submit-button');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param testId The test ID of the element.
+     * @returns The locator to the element with the corresponding test ID.
+     */
+    getByTestId(testId: string | RegExp): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding placeholder text.
+     *
+     * @example
+     * ```js
+     * const locator = frameLocator.getByPlaceholder('name@example.com');
+     *
+     * await locator.fill('my.name@example.com');
+     * ```
+     *
+     * @param placeholder The placeholder text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding placeholder text.
+     */
+    getByPlaceholder(
+        placeholder: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding title text.
+     *
+     * @example
+     * ```js
+     * const locator = frameLocator.getByTitle('Information box');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param title The title text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding title text.
+     */
+    getByTitle(
+        title: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
+}
+
+/**
+ * JSHandle represents an in-page JavaScript object.
+ */
+export interface JSHandle<T = any> {
+    /**
+     * Returns either `null` or the object handle itself, if the object handle is
+     * an instance of `ElementHandle`.
+     * @returns The ElementHandle if available.
+     */
+    asElement(): Promise<ElementHandle | null>;
+
+    /**
+     * Stops referencing the element handle.
+     */
+    dispose(): Promise<void>;
+
+    /**
+     * Evaluates the page function and returns its return value.
+     * This method passes this handle as the first argument to the page function.
+     * @param pageFunction The function to be evaluated.
+     * @param args The arguments to pass to the page function.
+     * @returns The return value of `pageFunction`.
+     */
+    evaluate<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg): Promise<R>;
+
+    /**
+     * Evaluates the page function and returns a `JSHandle`.
+     * This method passes this handle as the first argument to the page function.
+     * Unlike `evaluate`, `evaluateHandle` returns the value as a `JSHandle`
+     * @param pageFunction The function to be evaluated.
+     * @param args The arguments to pass to the page function.
+     * @returns A JSHandle of the return value of `pageFunction`.
+     */
+    evaluateHandle<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg): Promise<JSHandle<R>>;
+
+    /**
+     * Fetches a map with own property names of of the `JSHandle` with their values as
+     * `JSHandle` instances.
+     * @returns A map with property names as keys and `JSHandle` instances for the property values.
+     */
+    getProperties(): Promise<Map<string, JSHandle>>;
+
+    /**
+     * Fetches a JSON representation of the object.
+     * @returns A JSON representation of the object.
+     */
+    jsonValue(): Promise<any>;
+}
+
+/**
+ * Keyboard provides an API for managing a virtual keyboard.
+ */
+export interface Keyboard {
+    /**
+     * Sends a key down message to a session target.
+     * A superset of the key values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values).
+     * @param key Name of key to press, such as `ArrowLeft`.
+     */
+    down(key: string): Promise<void>;
+
+    /**
+     * Dispatches an `input` event with the given `text`.
+     * This method does not emit `keyDown`, `keyUp` or `keyPress` events.
+     * @param text Event text.
+     */
+    insertText(text: string): Promise<void>;
+
+    /**
+     * Sends a key press message to a session target.
+     * A press message consists of successive key down and up messages.
+     * @param key Sequence of keys to press.
+     * @param options Specifies the typing options.
+     */
+    press(key: string, options?: { delay?: number }): Promise<void>;
+
+    /**
+     * Type sends a `press` message to a session target for each character in text.
+     * It sends an insertText message if a character is not among
+     * valid characters in the keyboard's layout.
+     * Modifier keys `Shift`, `Control`, `Alt`, `Meta` are _not_ respected.
+     * @param text A text to type into a focused element.
+     * @param options Specifies the typing options.
+     */
+    type(text: string, options?: { delay?: number }): Promise<void>;
+
+    /**
+     * Sends a key up message to a session target.
+     * A superset of the key values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values).
+     * @param key Name of key to release, such as `ArrowLeft`.
+     */
+    up(key: string): Promise<void>;
+}
+
+export interface LocatorOptions {
+    /**
+     * Matches only elements that contain the specified text. String or regular expression.
+     */
+    hasText?: string | RegExp;
+
+    /**
+     * Matches only elements that do not contain the specified text. String or regular expression.
+     */
+    hasNotText?: string | RegExp;
+}
+
+export interface LocatorFilterOptions {
+    /**
+     * Matches only elements that contain the specified text. String or regular expression.
+     */
+    hasText?: string | RegExp;
+
+    /**
+     * Matches only elements that do not contain the specified text. String or regular expression.
+     */
+    hasNotText?: string | RegExp;
+}
+
+/**
+ * The Locator API makes it easier to work with dynamically changing elements.
+ * Some of the benefits of using it over existing ways to locate an element
+ * (e.g. Page.$()) include:
+ *
+ * - Helps with writing robust tests by finding an element even if the
+ * underlying frame navigates.
+ * - Makes it easier to work with dynamic web pages and SPAs built with Svelte,
+ * React, Vue, etc.
+ */
+export interface Locator {
+    /**
+     * Returns an array of locators matching the selector.
+     *
+     * **Usage**
+     *
+     * ```js
+     * // Select all options
+     * for (const option of await page.locator('option').all())
+     *   await option.click();
+     * ```
+     *
+     * @returns Array of locators
+     */
+    all(): Promise<Locator[]>;
+
+    /**
+     * Returns the bounding box of the element that this locator points to.
+     *
+     * **Usage**
+     *
+     * ```js
+     * const locator = page.locator('#my-element');
+     * const boundingBox = await locator.boundingBox();
+     * ```
+     *
+     * @param options Options to use.
+     * @returns The bounding box of the element, or null if the element is not visible.
+     */
+    boundingBox(options?: TimeoutOptions): Promise<Rect | null>;
+
+    /**
+     * Clears text boxes and input fields of any existing values.
+     *
+     * **Usage**
+     *
+     * ```js
+     * // Clears the input field matching the selector.
+     * page.locator('input[name="login"]').clear();
+     * ```
+     *
+     * @param options Options to use.
+     */
+    clear(options?: ElementHandleOptions): Promise<void>;
+
+    /**
+     * Mouse click on the chosen element.
+     * @param options Options to use.
+     * @returns Promise which resolves when the element is successfully clicked.
+     */
+    click(options?: MouseMoveOptions & MouseMultiClickOptions): Promise<void>;
+
+    /**
+     * Returns a `FrameLocator` that can be used to locate elements within an
+     * `iframe`.
+     * @returns A `FrameLocator`.
+     */
+    contentFrame(): FrameLocator;
+
+    /**
+     * Returns the number of elements matching the selector.
+     *
+     * **Usage**
+     *
+     * ```js
+     * const count = await page.locator('input').count();
+     * ```
+     *
+     * @returns Promise which resolves with the number of elements matching the selector.
+     */
+    count(): Promise<number>;
 
     /**
      * Mouse double click on the chosen element.
@@ -2105,107 +2964,493 @@ export interface Locator {
      */
     innerText(options?: TimeoutOptions): Promise<string>;
 
-    /**
-     * Returns the `element.textContent`.
-     * @param options Options to use.
-     * @returns Element's textContent.
-     */
-    textContent(options?: TimeoutOptions): Promise<string | null>;
+    /**
+     * Returns the `element.textContent`.
+     * @param options Options to use.
+     * @returns Element's textContent.
+     */
+    textContent(options?: TimeoutOptions): Promise<string | null>;
+
+    /**
+     * Returns `input.value` for the selected `input`, `textarea` or `select` element.
+     * @param options Options to use.
+     * @returns The input value of the element.
+     */
+    inputValue(options?: TimeoutOptions): Promise<string>;
+
+    /**
+     * Returns locator to the last matching element.
+     *
+     * **Usage**
+     *
+     * ```js
+     * const lastRow = await page.locator('tr').last();
+     * ```
+     *
+     * @returns Locator.
+     */
+    last(): Locator;
+
+    /**
+     * The method finds all elements matching the selector and creates a new
+     * locator that matches all of them. This method can be used to further
+     * refine the locator by chaining additional selectors.
+     *
+     * @example
+     * ```js
+     * const rows = page.locator('table tr');
+     * const cell = rows.locator('.selected');
+     *
+     * // Use with options to filter
+     * const orangeButton = fruitsSection.locator('button', { hasText: 'Add to Cart' });
+     * ```
+     *
+     * @param selector A selector to use when resolving DOM element.
+     * @param options Options to use for filtering.
+     * @returns The new locator.
+     */
+    locator(selector: string, options?: LocatorOptions): Locator;
+
+    /**
+     * Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.
+     *
+     * **Usage**
+     *
+     * ```js
+     * const secondRow = await page.locator('tr').nth(1);
+     * ```
+     *
+     * @param index
+     * @returns Locator
+     */
+    nth(index: number): Locator;
+
+    /**
+     * Select one or more options which match the values. If the select has the multiple attribute, all matching options are selected,
+     * otherwise only the first option matching one of the passed options is selected.
+     *
+     * @example
+     * ```js
+     * // Single selection matching the value or label
+     * locator.selectOption('blue');
+     *
+     * // single selection matching the label
+     * locator.selectOption({ label: 'Blue' });
+     *
+     * // multiple selection
+     * locator.selectOption(['red', 'green', 'blue']);
+     * ```
+     *
+     * @param values Values of options to select.
+     * @param options Options to use.
+     * @returns List of selected options.
+     */
+    selectOption(
+        values: string | string[] | { value?: string; label?: string; index?: number },
+        options?: ElementHandleOptions,
+    ): Promise<string[]>;
+
+    /**
+     * Checks or unchecks the input checkbox element.
+     * @param checked Whether to check or uncheck the element.
+     * @param options Options to customize the check action.
+     * @returns A promise that resolves when the element is checked or unchecked.
+     */
+    setChecked(checked: boolean, options?: FrameCheckOptions): Promise<void>;
+
+    /**
+     * Press a single key on the keyboard or a combination of keys.
+     * A superset of the key values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values).
+     * @param key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
+     * @param options Keyboard press options.
+     */
+    press(key: string, options?: KeyboardPressOptions): Promise<void>;
+
+    /**
+     * Type a text into the input field.
+     * @param text Text to type into the input field.
+     * @param options Typing options.
+     */
+    type(text: string, options?: KeyboardPressOptions): Promise<void>;
+
+    /**
+     * Hover over the element.
+     * @param options Options to use.
+     */
+    hover(options?: MouseMoveOptions): Promise<void>;
+
+    /**
+     * Tap on the chosen element.
+     * @param options Options to use.
+     */
+    tap(options?: MouseMoveOptions): Promise<void>;
+
+    /**
+     * Dispatches HTML DOM event types e.g. `click`.
+     * @param type DOM event type.
+     * @param eventInit Event-specific properties.
+     * @param options Options to use.
+     */
+    dispatchEvent(type: string, eventInit?: EvaluationArgument, options?: TimeoutOptions): Promise<void>;
+
+    /**
+     * Wait for the element to be in a particular state e.g. `visible`.
+     * @param options Wait options.
+     */
+    waitFor(options?: { state?: ElementState } & TimeoutOptions): Promise<void>;
+
+    /**
+     * Returns a new Locator that matches only elements with the given options.
+     *
+     * @example
+     * ```js
+     * // Filter list items that contain "Product 2" text
+     * const product2Item = page
+     *   .locator('li')
+     *   .filter({ hasText: 'Product 2' })
+     *   .first();
+     *
+     * // Filter list items that do NOT contain "Product 2" using regex
+     * const product1Item = page
+     *   .locator('li')
+     *   .filter({ hasNotText: /Product 2/ })
+     *   .first();
+     * ```
+     *
+     * @param options Filter options.
+     * @returns A new filtered Locator that can be chained with other methods.
+     */
+    filter(options: LocatorFilterOptions): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding role.
+     *
+     * @example
+     * ```js
+     * const locator = locator.getByRole('button', { name: 'Pizza, Please!' });
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param role The role of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding role.
+     */
+    getByRole(
+        role:
+            | "alert"
+            | "alertdialog"
+            | "application"
+            | "article"
+            | "banner"
+            | "blockquote"
+            | "button"
+            | "caption"
+            | "cell"
+            | "checkbox"
+            | "code"
+            | "columnheader"
+            | "combobox"
+            | "complementary"
+            | "contentinfo"
+            | "definition"
+            | "dialog"
+            | "directory"
+            | "document"
+            | "emphasis"
+            | "feed"
+            | "figure"
+            | "form"
+            | "generic"
+            | "grid"
+            | "gridcell"
+            | "group"
+            | "heading"
+            | "img"
+            | "insertion"
+            | "link"
+            | "list"
+            | "listbox"
+            | "listitem"
+            | "log"
+            | "main"
+            | "marquee"
+            | "math"
+            | "menu"
+            | "menubar"
+            | "menuitem"
+            | "menuitemcheckbox"
+            | "menuitemradio"
+            | "meter"
+            | "navigation"
+            | "none"
+            | "note"
+            | "option"
+            | "presentation"
+            | "progressbar"
+            | "radio"
+            | "radiogroup"
+            | "region"
+            | "row"
+            | "rowgroup"
+            | "rowheader"
+            | "scrollbar"
+            | "search"
+            | "searchbox"
+            | "separator"
+            | "slider"
+            | "spinbutton"
+            | "status"
+            | "strong"
+            | "subscript"
+            | "superscript"
+            | "switch"
+            | "tab"
+            | "table"
+            | "tablist"
+            | "tabpanel"
+            | "term"
+            | "textbox"
+            | "time"
+            | "timer"
+            | "toolbar"
+            | "tooltip"
+            | "tree"
+            | "treegrid"
+            | "treeitem",
+        options?: {
+            /**
+             * Whether the accessible `options.name` should be checked exactly for equality.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+
+            /**
+             * Whether to include elements that are normally excluded from the accessibility tree.
+             *
+             * @defaultValue false
+             */
+            includeHidden?: boolean;
+
+            /**
+             * A number attribute that is traditionally used for headings h1-h6.
+             */
+            level?: number;
+
+            /**
+             * An accessible name for the element, such as a text in a button or a label for an input.
+             */
+            name?: string | RegExp;
+
+            /**
+             * A boolean attribute that can be used to indicate if a checkbox is checked or not.
+             */
+            checked?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is disabled or not.
+             */
+            disabled?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is expanded or not.
+             */
+            expanded?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is pressed or not.
+             */
+            pressed?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is selected or not.
+             */
+            selected?: boolean;
+        },
+    ): Locator;
 
     /**
-     * Returns `input.value` for the selected `input`, `textarea` or `select` element.
+     * Returns {@link Locator} to the element with the corresponding alt text.
+     *
+     * @example
+     * ```js
+     * const locator = locator.getByAltText('pizza');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param altText The alt text of the element.
      * @param options Options to use.
-     * @returns The input value of the element.
+     * @returns The locator to the element with the corresponding alt text.
      */
-    inputValue(options?: TimeoutOptions): Promise<string>;
+    getByAltText(
+        altText: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
 
     /**
-     * Returns locator to the last matching element.
-     *
-     * **Usage**
+     * Returns {@link Locator} to the element with the corresponding label text.
      *
+     * @example
      * ```js
-     * const lastRow = await page.locator('tr').last();
+     * const locator = locator.getByLabel('Password');
+     *
+     * await locator.fill('my-password');
      * ```
      *
-     * @returns Locator.
+     * @param label The label text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding label text.
      */
-    last(): Locator;
+    getByLabel(
+        label: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
 
     /**
-     * Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.
+     * Allows locating elements by their text content. Returns {@link Locator}.
      *
-     * **Usage**
+     * Consider the following DOM structure:
+     *
+     * ```html
+     * <div>Hello <span>world</span></div>
+     * <div>Hello</div>
+     * ```
      *
+     * You can locate by text substring, exact string, or a regular expression:
+     *
+     * @example
      * ```js
-     * const secondRow = await page.locator('tr').nth(1);
+     * // Matches <span>
+     * locator.getByText('world');
+     *
+     * // Matches first <div>
+     * locator.getByText('Hello world');
+     *
+     * // Matches second <div>
+     * locator.getByText('Hello', { exact: true });
+     *
+     * // Matches both <div>s
+     * locator.getByText(/Hello/);
+     *
+     * // Matches second <div>
+     * locator.getByText(/^hello$/i);
      * ```
      *
-     * @param index
-     * @returns Locator
-     */
-    nth(index: number): Locator;
-
-    /**
-     * Select one or more options which match the values. If the select has the multiple attribute, all matching options are selected,
-     * otherwise only the first option matching one of the passed options is selected.
-     * @param values Values of options to select.
+     * Matching by text always normalizes whitespace, even with exact match. For
+     * example, it turns multiple spaces into one, turns line breaks into spaces
+     * and ignores leading and trailing whitespace.
+     *
+     * Input elements of the type `button` and `submit` are matched by their
+     * `value` instead of the text content. For example, locating by text
+     * `"Log in"` matches `<input type=button value="Log in">`.
+     *
+     * @param text Text to locate the element by.
      * @param options Options to use.
-     * @returns List of selected options.
-     */
-    selectOption(
-        values: string | string[] | { value?: string; label?: string; index?: number },
-        options?: ElementHandleOptions,
-    ): Promise<string[]>;
-
-    /**
-     * Checks or unchecks the input checkbox element.
-     * @param checked Whether to check or uncheck the element.
-     * @param options Options to customize the check action.
-     * @returns A promise that resolves when the element is checked or unchecked.
-     */
-    setChecked(checked: boolean, options?: FrameCheckOptions): Promise<void>;
-
-    /**
-     * Press a single key on the keyboard or a combination of keys.
-     * A superset of the key values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values).
-     * @param key Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
-     * @param options Keyboard press options.
-     */
-    press(key: string, options?: KeyboardPressOptions): Promise<void>;
-
-    /**
-     * Type a text into the input field.
-     * @param text Text to type into the input field.
-     * @param options Typing options.
+     * @returns The locator to the element with the corresponding text content.
      */
-    type(text: string, options?: KeyboardPressOptions): Promise<void>;
+    getByText(
+        text: string | RegExp,
+        options?: {
+            /**
+             * Whether to find an exact match: case-sensitive and whole-string.
+             * Default to false. Ignored when locating by a regular expression.
+             * Note that exact match still trims whitespace.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
 
     /**
-     * Hover over the element.
-     * @param options Options to use.
+     * Returns {@link Locator} to the element with the corresponding test ID.
+     * Note that this method only supports the `data-testid` attribute.
+     *
+     * @example
+     * HTML:
+     * ```html
+     * <button data-testid="submit-button">Submit</button>
+     * ```
+     *
+     * JavaScript:
+     * ```js
+     * const locator = locator.getByTestId('submit-button');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param testId The test ID of the element.
+     * @returns The locator to the element with the corresponding test ID.
      */
-    hover(options?: MouseMoveOptions): Promise<void>;
+    getByTestId(testId: string | RegExp): Locator;
 
     /**
-     * Tap on the chosen element.
+     * Returns {@link Locator} to the element with the corresponding placeholder text.
+     *
+     * @example
+     * ```js
+     * const locator = locator.getByPlaceholder('name@example.com');
+     *
+     * await locator.fill('my.name@example.com');
+     * ```
+     *
+     * @param placeholder The placeholder text of the element.
      * @param options Options to use.
+     * @returns The locator to the element with the corresponding placeholder text.
      */
-    tap(options?: MouseMoveOptions): Promise<void>;
+    getByPlaceholder(
+        placeholder: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
 
     /**
-     * Dispatches HTML DOM event types e.g. `click`.
-     * @param type DOM event type.
-     * @param eventInit Event-specific properties.
+     * Returns {@link Locator} to the element with the corresponding title text.
+     *
+     * @example
+     * ```js
+     * const locator = locator.getByTitle('Information box');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param title The title text of the element.
      * @param options Options to use.
+     * @returns The locator to the element with the corresponding title text.
      */
-    dispatchEvent(type: string, eventInit?: EvaluationArgument, options?: TimeoutOptions): Promise<void>;
-
-    /**
-     * Wait for the element to be in a particular state e.g. `visible`.
-     * @param options Wait options.
-     */
-    waitFor(options?: { state?: ElementState } & TimeoutOptions): Promise<void>;
+    getByTitle(
+        title: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+        },
+    ): Locator;
 }
 
 /**
@@ -2604,101 +3849,431 @@ export interface Page {
         value: string,
         options?: {
             /**
-             * Setting this to `true` will bypass the actionability checks (`visible`,
-             * `stable`, `enabled`). Defaults to `false`.
+             * Setting this to `true` will bypass the actionability checks (`visible`,
+             * `stable`, `enabled`). Defaults to `false`.
+             */
+            force?: boolean;
+
+            /**
+             * If set to `true` and a navigation occurs from performing this action, it
+             * will not wait for it to complete. Defaults to `false`.
+             */
+            noWaitAfter?: boolean;
+
+            /**
+             * When `true`, the call requires selector to resolve to a single element.
+             * If given selector resolves to more than one element, the call throws
+             * an exception. Defaults to `false`.
+             */
+            strict?: boolean;
+
+            /**
+             * Maximum time in milliseconds. Defaults to `30` seconds. Default is
+             * overridden by the `setDefaultTimeout` option on `BrowserContext` or
+             * `page` methods.
+             *
+             * Setting the value to `0` will disable the timeout.
+             */
+            timeout?: number;
+        },
+    ): Promise<void>;
+
+    /**
+     * **NOTE** Use locator-based `locator.focus([options])` instead.
+     *
+     * This method fetches an element with `selector` and focuses it.
+     *
+     * @param selector A selector to search for an element. If there are multiple
+     * elements satisfying the selector, the first will be used.
+     * @param options
+     */
+    focus(
+        selector: string,
+        options?: {
+            /**
+             * When `true`, the call requires selector to resolve to a single element.
+             * If given selector resolves to more than one element, the call throws
+             * an exception. Defaults to `false`.
+             */
+            strict?: boolean;
+
+            /**
+             * Maximum time in milliseconds. Defaults to `30` seconds. Default is
+             * overridden by the `setDefaultTimeout` option on `BrowserContext` or
+             * `page` methods.
+             *
+             * Setting the value to `0` will disable the timeout.
+             */
+            timeout?: number;
+        },
+    ): Promise<void>;
+
+    /**
+     * Frames returns an array of frames on the page.
+     */
+    frames(): Frame[];
+
+    /**
+     * **NOTE** Use locator-based locator.getAttribute(name[, options]) instead.
+     *
+     * Returns the element attribute value for the given attribute name.
+     *
+     * @param selector A selector to search for an element. If there are multiple
+     * elements satisfying the selector, the first will be used.
+     * @param name Attribute name to get the value for.
+     * @param options
+     */
+    getAttribute(
+        selector: string,
+        name: string,
+        options?: {
+            /**
+             * When `true`, the call requires selector to resolve to a single element.
+             * If given selector resolves to more than one element, the call throws
+             * an exception. Defaults to `false`.
+             */
+            strict?: boolean;
+
+            /**
+             * Maximum time in milliseconds. Defaults to `30` seconds. Default is
+             * overridden by the `setDefaultTimeout` option on `BrowserContext` or
+             * `page` methods.
+             *
+             * Setting the value to `0` will disable the timeout.
+             */
+            timeout?: number;
+        },
+    ): Promise<string | null>;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding role.
+     *
+     * @example
+     * ```js
+     * const locator = page.getByRole('button', { name: 'Pizza, Please!' });
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param role The role of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding role.
+     */
+    getByRole(
+        role:
+            | "alert"
+            | "alertdialog"
+            | "application"
+            | "article"
+            | "banner"
+            | "blockquote"
+            | "button"
+            | "caption"
+            | "cell"
+            | "checkbox"
+            | "code"
+            | "columnheader"
+            | "combobox"
+            | "complementary"
+            | "contentinfo"
+            | "definition"
+            | "dialog"
+            | "directory"
+            | "document"
+            | "emphasis"
+            | "feed"
+            | "figure"
+            | "form"
+            | "generic"
+            | "grid"
+            | "gridcell"
+            | "group"
+            | "heading"
+            | "img"
+            | "insertion"
+            | "link"
+            | "list"
+            | "listbox"
+            | "listitem"
+            | "log"
+            | "main"
+            | "marquee"
+            | "math"
+            | "menu"
+            | "menubar"
+            | "menuitem"
+            | "menuitemcheckbox"
+            | "menuitemradio"
+            | "meter"
+            | "navigation"
+            | "none"
+            | "note"
+            | "option"
+            | "presentation"
+            | "progressbar"
+            | "radio"
+            | "radiogroup"
+            | "region"
+            | "row"
+            | "rowgroup"
+            | "rowheader"
+            | "scrollbar"
+            | "search"
+            | "searchbox"
+            | "separator"
+            | "slider"
+            | "spinbutton"
+            | "status"
+            | "strong"
+            | "subscript"
+            | "superscript"
+            | "switch"
+            | "tab"
+            | "table"
+            | "tablist"
+            | "tabpanel"
+            | "term"
+            | "textbox"
+            | "time"
+            | "timer"
+            | "toolbar"
+            | "tooltip"
+            | "tree"
+            | "treegrid"
+            | "treeitem",
+        options?: {
+            /**
+             * Whether the accessible `options.name` should be checked exactly for equality.
+             *
+             * @defaultValue false
+             */
+            exact?: boolean;
+
+            /**
+             * Whether to include elements that are normally excluded from the accessibility tree.
+             *
+             * @defaultValue false
+             */
+            includeHidden?: boolean;
+
+            /**
+             * A number attribute that is traditionally used for headings h1-h6.
+             */
+            level?: number;
+
+            /**
+             * An accessible name for the element, such as a text in a button or a label for an input.
              */
-            force?: boolean;
+            name?: string | RegExp;
 
             /**
-             * If set to `true` and a navigation occurs from performing this action, it
-             * will not wait for it to complete. Defaults to `false`.
+             * A boolean attribute that can be used to indicate if a checkbox is checked or not.
              */
-            noWaitAfter?: boolean;
+            checked?: boolean;
 
             /**
-             * When `true`, the call requires selector to resolve to a single element.
-             * If given selector resolves to more than one element, the call throws
-             * an exception. Defaults to `false`.
+             * A boolean attribute that can be used to indicate if an element is disabled or not.
              */
-            strict?: boolean;
+            disabled?: boolean;
 
             /**
-             * Maximum time in milliseconds. Defaults to `30` seconds. Default is
-             * overridden by the `setDefaultTimeout` option on `BrowserContext` or
-             * `page` methods.
+             * A boolean attribute that can be used to indicate if an element is expanded or not.
+             */
+            expanded?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is pressed or not.
+             */
+            pressed?: boolean;
+
+            /**
+             * A boolean attribute that can be used to indicate if an element is selected or not.
+             */
+            selected?: boolean;
+        },
+    ): Locator;
+
+    /**
+     * Returns {@link Locator} to the element with the corresponding alt text.
+     *
+     * @example
+     * ```js
+     * const locator = page.getByAltText('pizza');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param altText The alt text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding alt text.
+     */
+    getByAltText(
+        altText: string | RegExp,
+        options?: {
+            /**
+             * Whether the locator should be exact.
              *
-             * Setting the value to `0` will disable the timeout.
+             * @defaultValue false
              */
-            timeout?: number;
+            exact?: boolean;
         },
-    ): Promise<void>;
+    ): Locator;
 
     /**
-     * **NOTE** Use locator-based `locator.focus([options])` instead.
+     * Returns {@link Locator} to the element with the corresponding label text.
      *
-     * This method fetches an element with `selector` and focuses it.
+     * @example
+     * ```js
+     * const locator = page.getByLabel('Password');
      *
-     * @param selector A selector to search for an element. If there are multiple
-     * elements satisfying the selector, the first will be used.
-     * @param options
+     * await locator.fill('my-password');
+     * ```
+     *
+     * @param label The label text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding label text.
      */
-    focus(
-        selector: string,
+    getByLabel(
+        label: string | RegExp,
         options?: {
             /**
-             * When `true`, the call requires selector to resolve to a single element.
-             * If given selector resolves to more than one element, the call throws
-             * an exception. Defaults to `false`.
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
              */
-            strict?: boolean;
+            exact?: boolean;
+        },
+    ): Locator;
 
+    /**
+     * Allows locating elements by their text content. Returns {@link Locator}.
+     *
+     * Consider the following DOM structure:
+     *
+     * ```html
+     * <div>Hello <span>world</span></div>
+     * <div>Hello</div>
+     * ```
+     *
+     * You can locate by text substring, exact string, or a regular expression:
+     *
+     * @example
+     * ```js
+     * // Matches <span>
+     * page.getByText('world');
+     *
+     * // Matches first <div>
+     * page.getByText('Hello world');
+     *
+     * // Matches second <div>
+     * page.getByText('Hello', { exact: true });
+     *
+     * // Matches both <div>s
+     * page.getByText(/Hello/);
+     *
+     * // Matches second <div>
+     * page.getByText(/^hello$/i);
+     * ```
+     *
+     * Matching by text always normalizes whitespace, even with exact match. For
+     * example, it turns multiple spaces into one, turns line breaks into spaces
+     * and ignores leading and trailing whitespace.
+     *
+     * Input elements of the type `button` and `submit` are matched by their
+     * `value` instead of the text content. For example, locating by text
+     * `"Log in"` matches `<input type=button value="Log in">`.
+     *
+     * @param text Text to locate the element by.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding text content.
+     */
+    getByText(
+        text: string | RegExp,
+        options?: {
             /**
-             * Maximum time in milliseconds. Defaults to `30` seconds. Default is
-             * overridden by the `setDefaultTimeout` option on `BrowserContext` or
-             * `page` methods.
+             * Whether to find an exact match: case-sensitive and whole-string.
+             * Default to false. Ignored when locating by a regular expression.
+             * Note that exact match still trims whitespace.
              *
-             * Setting the value to `0` will disable the timeout.
+             * @defaultValue false
              */
-            timeout?: number;
+            exact?: boolean;
         },
-    ): Promise<void>;
+    ): Locator;
 
     /**
-     * Frames returns an array of frames on the page.
+     * Returns {@link Locator} to the element with the corresponding test ID.
+     * Note that this method only supports the `data-testid` attribute.
+     *
+     * @example
+     * HTML:
+     * ```html
+     * <button data-testid="submit-button">Submit</button>
+     * ```
+     *
+     * JavaScript:
+     * ```js
+     * const locator = page.getByTestId('submit-button');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param testId The test ID of the element.
+     * @returns The locator to the element with the corresponding test ID.
      */
-    frames(): Frame[];
+    getByTestId(testId: string | RegExp): Locator;
 
     /**
-     * **NOTE** Use locator-based locator.getAttribute(name[, options]) instead.
+     * Returns {@link Locator} to the element with the corresponding placeholder text.
      *
-     * Returns the element attribute value for the given attribute name.
+     * @example
+     * ```js
+     * const locator = page.getByPlaceholder('name@example.com');
      *
-     * @param selector A selector to search for an element. If there are multiple
-     * elements satisfying the selector, the first will be used.
-     * @param name Attribute name to get the value for.
-     * @param options
+     * await locator.fill('my.name@example.com');
+     * ```
+     *
+     * @param placeholder The placeholder text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding placeholder text.
      */
-    getAttribute(
-        selector: string,
-        name: string,
+    getByPlaceholder(
+        placeholder: string | RegExp,
         options?: {
             /**
-             * When `true`, the call requires selector to resolve to a single element.
-             * If given selector resolves to more than one element, the call throws
-             * an exception. Defaults to `false`.
+             * Whether the locator should be exact.
+             *
+             * @defaultValue false
              */
-            strict?: boolean;
+            exact?: boolean;
+        },
+    ): Locator;
 
+    /**
+     * Returns {@link Locator} to the element with the corresponding title text.
+     *
+     * @example
+     * ```js
+     * const locator = page.getByTitle('Information box');
+     *
+     * await locator.click();
+     * ```
+     *
+     * @param title The title text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding title text.
+     */
+    getByTitle(
+        title: string | RegExp,
+        options?: {
             /**
-             * Maximum time in milliseconds. Defaults to `30` seconds. Default is
-             * overridden by the `setDefaultTimeout` option on `BrowserContext` or
-             * `page` methods.
+             * Whether the locator should be exact.
              *
-             * Setting the value to `0` will disable the timeout.
+             * @defaultValue false
              */
-            timeout?: number;
+            exact?: boolean;
         },
-    ): Promise<string | null>;
+    ): Locator;
 
     /**
      * Navigates to the specified url and returns the main resource response.
@@ -3027,9 +4602,18 @@ export interface Page {
      * when the action takes place, which means locators can span over navigations
      * where the underlying dom changes.
      *
+     * @example
+     * ```js
+     * const textbox = page.locator('#text1');
+     *
+     * // Create a locator with text filtering options
+     * const submitButton = page.locator('button', { hasText: 'Pizza, Please!' });
+     * ```
+     *
      * @param selector A selector to use when resolving DOM element.
+     * @param options Options to use for filtering.
      */
-    locator(selector: string): Locator;
+    locator(selector: string, options?: LocatorOptions): Locator;
 
     /**
      * The page's main frame. Page is made up of frames in a hierarchical. At the
@@ -3218,6 +4802,16 @@ export interface Page {
         waitUntil?: "load" | "domcontentloaded" | "networkidle";
     }): Promise<Response | null>;
 
+    /**
+     * Adds a route to the page to modify network requests made by that page.
+     *
+     * Once routing is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
+     */
+    route(
+        url: string | RegExp,
+        handler: (route: Route) => any,
+    ): Promise<void>;
+
     /**
      * Returns the buffer with the captured screenshot from the browser.
      *
@@ -3273,6 +4867,18 @@ export interface Page {
      * This select one or more options which match the values from a <select>
      * element.
      *
+     * @example
+     * ```js
+     * // Single selection matching the value or label
+     * page.selectOption('#colors-options', 'blue');
+     *
+     * // single selection matching the label
+     * page.selectOption('#colors-options', { label: 'Blue' });
+     *
+     * // multiple selection
+     * page.selectOption('#colors-options', ['red', 'green', 'blue']);
+     * ```
+     *
      * @param selector A selector to search for an element. If there are multiple
      * elements satisfying the selector, the first will be used.
      * @param values Options to select. If the select has multiple attribute, all
@@ -3787,6 +5393,13 @@ export interface Page {
          */
         timeout?: number;
 
+        /**
+         * An exact string or regex pattern to match while waiting for the
+         * navigation. Note that if the parameter is a string, the method will
+         * wait for navigation to URL that is exactly equal to the string.
+         */
+        url?: string | RegExp;
+
         /**
          * When to consider operation succeeded, defaults to `load`. Events can be
          * either:
@@ -3802,6 +5415,79 @@ export interface Page {
         waitUntil?: "load" | "domcontentloaded" | "networkidle";
     }): Promise<Response | null>;
 
+    /**
+     * Waits for the page to navigate to the specified URL.
+     *
+     * @example
+     * ```js
+     * await page.locator('a[href="/login"]').click();
+     * await page.waitForURL(/.*\/login$/);
+     * ```
+     *
+     * @param url An exact match or regular expression to match the URL.
+     * @param options Options to use.
+     */
+    waitForURL(
+        url: string | RegExp,
+        options?: {
+            /**
+             * Maximum operation time in milliseconds. Defaults to `30` seconds.
+             * The default value can be changed via the
+             * browserContext.setDefaultNavigationTimeout(timeout),
+             * browserContext.setDefaultTimeout(timeout),
+             * page.setDefaultNavigationTimeout(timeout) or
+             * page.setDefaultTimeout(timeout) methods.
+             *
+             * Setting the value to `0` will disable the timeout.
+             */
+            timeout?: number;
+
+            /**
+             * When to consider operation succeeded, defaults to `load`. Events can be
+             * either:
+             * - `'domcontentloaded'` - consider operation to be finished when the
+             * `DOMContentLoaded` event is fired.
+             * - `'load'` - consider operation to be finished when the `load` event is
+             * fired.
+             * - `'networkidle'` - **DISCOURAGED** consider operation to be finished
+             * when there are no network connections for at least `500` ms. Don't use
+             * this method for testing especially with chatty websites where the event
+             * may never fire, rely on web assertions to assess readiness instead.
+             */
+            waitUntil?: "load" | "domcontentloaded" | "networkidle";
+        },
+    ): Promise<void>;
+
+    /**
+     * Waits for the page to match against the URL for a Response object
+     *
+     * @example
+     * ```js
+     * const responsePromise = page.waitForResponse('https://example.com/resource');
+     * await page.goto('https://example.com/resource');
+     * const response = await responsePromise;
+     * ```
+     *
+     * @param response Request URL string or regex to match against Response object.
+     * @param options Options to use.
+     */
+    waitForResponse(
+        response: string | RegExp,
+        options?: {
+            /**
+             * Maximum operation time in milliseconds. Defaults to `30` seconds.
+             * The default value can be changed via the
+             * browserContext.setDefaultNavigationTimeout(timeout),
+             * browserContext.setDefaultTimeout(timeout),
+             * page.setDefaultNavigationTimeout(timeout) or
+             * page.setDefaultTimeout(timeout) methods.
+             *
+             * Setting the value to `0` will disable the timeout.
+             */
+            timeout?: number;
+        },
+    ): Promise<Response | null>;
+
     /**
      * **NOTE** Use web assertions that assert visibility or a locator-based
      * locator.waitFor([options]) instead.
@@ -4089,6 +5775,112 @@ export interface Response {
     url(): string;
 }
 
+/**
+ * Route represents a network request intercepted by page.route() function and allows to modify its behavior.
+ *
+ * Once routing is enabled, every request intercepted by a route will stall unless it's continued, fulfilled or aborted.
+ * When several routes match the given pattern, they run in the order opposite to their registration.
+ * That way the last registered route can always override all the previous ones.
+ */
+export interface Route {
+    /**
+     * Aborts the request with the given error code.
+     *
+     * **Usage**
+     *
+     * ```js
+     * // Abort all images requests
+     * await page.route(/(\.png$)|(\.jpg$)/, async (route) => {
+     *   await route.abort();
+     * });
+     * ```
+     *
+     * @param errorCode The error code to abort the request with, can be one of the following:
+     * 'aborted', 'accessdenied', 'addressunreachable', 'blockedbyclient', 'blockedbyresponse', 'connectionaborted','connectionclosed',
+     * 'connectionfailed', 'connectionrefused', 'connectionreset', 'internetdisconnected', 'namenotresolved', 'timedout', 'failed'.
+     */
+    abort(errorCode: string): Promise<void>;
+
+    /**
+     * Continues the request with optional overrides.
+     *
+     * **Usage**
+     *
+     * ```js
+     * await page.route('**\/*', async (route, request) => {
+     *   // Override headers
+     *   const headers = {
+     *     ...request.headers(),
+     *     foo: 'foo-value', // set "foo" header
+     *     bar: undefined, // remove "bar" header
+     *   };
+     *   await route.continue({ headers });
+     * });
+     * ```
+     *
+     * @param options Optional overrides for the request.
+     */
+    continue(options?: {
+        /**
+         * Optional HTTP headers to override.
+         */
+        headers?: { [key: string]: string };
+        /**
+         * Optional method to override the request method (e.g., 'GET', 'POST').
+         */
+        method?: string;
+        /**
+         * Optional post data to override the request body.
+         */
+        postData?: string | ArrayBuffer;
+        /**
+         * Optional URL to override the request URL.
+         */
+        url?: string;
+    }): Promise<void>;
+
+    /**
+     * Fulfills the request with the given response.
+     *
+     * **Usage**
+     * ```js
+     * // Respond with a custom JSON response
+     * await page.route('**\/*', async (route) => {
+     *   await route.fulfill({
+     *     status: 200,
+     *     contentType: 'application/json',
+     *     body: JSON.stringify({ message: 'Hello, world!' }),
+     *   });
+     * });
+     * ```
+     *
+     * @param options The response options to fulfill the request with.
+     */
+    fulfill(options: {
+        /**
+         * Optional body of the response, can be a string or an ArrayBuffer.
+         */
+        body?: string | ArrayBuffer;
+        /**
+         * Optional content type of the response.
+         */
+        contentType?: string;
+        /**
+         * Optional HTTP headers to return.
+         */
+        headers?: { [key: string]: string };
+        /**
+         * Optional HTTP status code to return. Defaults to `200`.
+         */
+        status?: number;
+    }): Promise<void>;
+
+    /**
+     * Returns the matching request that this route is handling.
+     */
+    request(): Request;
+}
+
 /**
  * Touchscreen provides an api for interacting with a virtual touchscreen. It
  * operates in main-frame CSS pixels relative to the top-left corner of the