@types/k6 1.2.0 → 1.3.0

k6/browser/index.d.ts

@@ -1719,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.
@@ -1961,132 +1969,859 @@ 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`.
+     * 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.
      */
-    evaluate<R, Arg>(pageFunction: PageFunction<Arg, R>, arg?: Arg): Promise<R>;
+    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 {
     /**
-     * Returns an array of locators matching the selector.
-     *
-     * **Usage**
+     * Returns {@link Locator} to the element with the corresponding alt text.
      *
+     * @example
      * ```js
-     * // Select all options
-     * for (const option of await page.locator('option').all())
-     *   await option.click();
+     * const locator = frame.getByAltText('pizza');
+     *
+     * await locator.click();
      * ```
      *
-     * @returns Array of locators
+     * @param altText The alt text of the element.
+     * @param options Options to use.
+     * @returns The locator to the element with the corresponding alt text.
      */
-    all(): Promise<Locator[]>;
-
-    /**
-     * Clears text boxes and input fields of any existing values.
-     *
-     * **Usage**
-     *
+    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 = frame.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>
+     * 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);
+     * ```
+     *
+     * 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 = 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();
@@ -2094,248 +2829,628 @@ export interface Locator {
      *
      * @param options Options to use.
      */
-    clear(options?: ElementHandleOptions): Promise<void>;
+    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.
+     * @param options Options to use.
+     */
+    dblclick(options?: MouseMoveOptions & MouseMultiClickOptions): Promise<void>;
+
+    /**
+     * Use this method to select an `input type="checkbox"`.
+     * @param options Options to use.
+     */
+    check(options?: ElementClickOptions): Promise<void>;
+
+    /**
+     * Use this method to unselect an `input type="checkbox"`.
+     * @param options Options to use.
+     */
+    uncheck(options?: ElementClickOptions): Promise<void>;
+
+    /**
+     * Checks to see if the `input type="checkbox"` is selected or not.
+     * @param options Options to use.
+     * @returns `true` if the element is checked, `false` otherwise.
+     */
+    isChecked(options?: TimeoutOptions): Promise<boolean>;
+
+    /**
+     * Checks if the element is editable.
+     * @param options Options to use.
+     * @returns `true` if the element is editable, `false` otherwise.
+     */
+    isEditable(options?: TimeoutOptions): Promise<boolean>;
+
+    /**
+     * Checks if the element is `enabled`.
+     * @param options Options to use.
+     * @returns `true` if the element is enabled, `false` otherwise.
+     */
+    isEnabled(options?: TimeoutOptions): Promise<boolean>;
+
+    /**
+     * Checks if the element is `disabled`.
+     * @param options Options to use.
+     * @returns `true` if the element is disabled, `false` otherwise.
+     */
+    isDisabled(options?: TimeoutOptions): Promise<boolean>;
+
+    /**
+     * Checks if the element is `visible`.
+     * @returns `true` if the element is visible, `false` otherwise.
+     */
+    isVisible(): Promise<boolean>;
+
+    /**
+     * Checks if the element is `hidden`.
+     * @returns `true` if the element is hidden, `false` otherwise.
+     */
+    isHidden(): Promise<boolean>;
+
+    /**
+     * Fill an `input`, `textarea` or `contenteditable` element with the provided value.
+     * @param value Value to fill for the `input` or `textarea` element.
+     * @param options Options to use.
+     */
+    fill(value: string, options?: ElementHandleOptions): Promise<void>;
+
+    /**
+     * Returns locator to the first matching element.
+     *
+     * **Usage**
+     *
+     * ```js
+     * const firstRow = await page.locator('tr').first();
+     * ```
+     *
+     * @returns Locator.
+     */
+    first(): Locator;
+
+    /**
+     * Focuses the element using locator's selector.
+     * @param options Options to use.
+     */
+    focus(options?: TimeoutOptions): Promise<void>;
+
+    /**
+     * Returns the element attribute value for the given attribute name.
+     * @param name Attribute name to retrieve value for.
+     * @param options Options to use.
+     * @returns Attribute value.
+     */
+    getAttribute(name: string, options?: TimeoutOptions): Promise<string | null>;
+
+    /**
+     * Returns the `element.innerHTML`.
+     * @param options Options to use.
+     * @returns Element's innerHTML.
+     */
+    innerHTML(options?: TimeoutOptions): Promise<string>;
+
+    /**
+     * Returns the `element.innerText`.
+     * @param options Options to use.
+     * @returns Element's innerText.
+     */
+    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 `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;
 
     /**
-     * Mouse click on the chosen element.
-     * @param options Options to use.
-     * @returns Promise which resolves when the element is successfully clicked.
+     * 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.
      */
-    click(options?: MouseMoveOptions & MouseMultiClickOptions): Promise<void>;
+    locator(selector: string, options?: LocatorOptions): Locator;
 
     /**
-     * Returns the number of elements matching the selector.
+     * Returns locator to the n-th matching element. It's zero based, `nth(0)` selects the first element.
      *
      * **Usage**
      *
      * ```js
-     * const count = await page.locator('input').count();
+     * const secondRow = await page.locator('tr').nth(1);
      * ```
      *
-     * @returns Promise which resolves with the number of elements matching the selector.
+     * @param index
+     * @returns Locator
      */
-    count(): Promise<number>;
+    nth(index: number): Locator;
 
     /**
-     * Mouse double click on the chosen element.
+     * 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.
      */
-    dblclick(options?: MouseMoveOptions & MouseMultiClickOptions): Promise<void>;
+    selectOption(
+        values: string | string[] | { value?: string; label?: string; index?: number },
+        options?: ElementHandleOptions,
+    ): Promise<string[]>;
 
     /**
-     * Use this method to select an `input type="checkbox"`.
-     * @param options Options to use.
+     * 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.
      */
-    check(options?: ElementClickOptions): Promise<void>;
+    setChecked(checked: boolean, options?: FrameCheckOptions): Promise<void>;
 
     /**
-     * Use this method to unselect an `input type="checkbox"`.
-     * @param options Options to use.
+     * 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.
      */
-    uncheck(options?: ElementClickOptions): Promise<void>;
+    press(key: string, options?: KeyboardPressOptions): Promise<void>;
 
     /**
-     * Checks to see if the `input type="checkbox"` is selected or not.
-     * @param options Options to use.
-     * @returns `true` if the element is checked, `false` otherwise.
+     * Type a text into the input field.
+     * @param text Text to type into the input field.
+     * @param options Typing options.
      */
-    isChecked(options?: TimeoutOptions): Promise<boolean>;
+    type(text: string, options?: KeyboardPressOptions): Promise<void>;
 
     /**
-     * Checks if the element is editable.
+     * Hover over the element.
      * @param options Options to use.
-     * @returns `true` if the element is editable, `false` otherwise.
      */
-    isEditable(options?: TimeoutOptions): Promise<boolean>;
+    hover(options?: MouseMoveOptions): Promise<void>;
 
     /**
-     * Checks if the element is `enabled`.
+     * Tap on the chosen element.
      * @param options Options to use.
-     * @returns `true` if the element is enabled, `false` otherwise.
      */
-    isEnabled(options?: TimeoutOptions): Promise<boolean>;
+    tap(options?: MouseMoveOptions): Promise<void>;
 
     /**
-     * Checks if the element is `disabled`.
+     * Dispatches HTML DOM event types e.g. `click`.
+     * @param type DOM event type.
+     * @param eventInit Event-specific properties.
      * @param options Options to use.
-     * @returns `true` if the element is disabled, `false` otherwise.
-     */
-    isDisabled(options?: TimeoutOptions): Promise<boolean>;
-
-    /**
-     * Checks if the element is `visible`.
-     * @returns `true` if the element is visible, `false` otherwise.
-     */
-    isVisible(): Promise<boolean>;
-
-    /**
-     * Checks if the element is `hidden`.
-     * @returns `true` if the element is hidden, `false` otherwise.
      */
-    isHidden(): Promise<boolean>;
+    dispatchEvent(type: string, eventInit?: EvaluationArgument, options?: TimeoutOptions): Promise<void>;
 
     /**
-     * Fill an `input`, `textarea` or `contenteditable` element with the provided value.
-     * @param value Value to fill for the `input` or `textarea` element.
-     * @param options Options to use.
+     * Wait for the element to be in a particular state e.g. `visible`.
+     * @param options Wait options.
      */
-    fill(value: string, options?: ElementHandleOptions): Promise<void>;
+    waitFor(options?: { state?: ElementState } & TimeoutOptions): Promise<void>;
 
     /**
-     * Returns locator to the first matching element.
-     *
-     * **Usage**
+     * Returns a new Locator that matches only elements with the given options.
      *
+     * @example
      * ```js
-     * const firstRow = await page.locator('tr').first();
+     * // 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();
      * ```
      *
-     * @returns Locator.
+     * @param options Filter options.
+     * @returns A new filtered Locator that can be chained with other methods.
      */
-    first(): Locator;
+    filter(options: LocatorFilterOptions): Locator;
 
     /**
-     * Focuses the element using locator's selector.
+     * 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.
      */
-    focus(options?: TimeoutOptions): Promise<void>;
+    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;
 
-    /**
-     * Returns the element attribute value for the given attribute name.
-     * @param name Attribute name to retrieve value for.
-     * @param options Options to use.
-     * @returns Attribute value.
-     */
-    getAttribute(name: string, options?: TimeoutOptions): Promise<string | null>;
+            /**
+             * Whether to include elements that are normally excluded from the accessibility tree.
+             *
+             * @defaultValue false
+             */
+            includeHidden?: boolean;
 
-    /**
-     * Returns the `element.innerHTML`.
-     * @param options Options to use.
-     * @returns Element's innerHTML.
-     */
-    innerHTML(options?: TimeoutOptions): Promise<string>;
+            /**
+             * 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;
 
-    /**
-     * Returns the `element.innerText`.
-     * @param options Options to use.
-     * @returns Element's innerText.
-     */
-    innerText(options?: TimeoutOptions): Promise<string>;
+            /**
+             * A boolean attribute that can be used to indicate if an element is pressed or not.
+             */
+            pressed?: boolean;
 
-    /**
-     * Returns the `element.textContent`.
-     * @param options Options to use.
-     * @returns Element's textContent.
-     */
-    textContent(options?: TimeoutOptions): Promise<string | null>;
+            /**
+             * 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:
      *
-     * ```js
-     * const secondRow = await page.locator('tr').nth(1);
+     * ```html
+     * <div>Hello <span>world</span></div>
+     * <div>Hello</div>
      * ```
      *
-     * @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.
+     * You can locate by text substring, exact string, or a regular expression:
      *
      * @example
      * ```js
-     * // Single selection matching the value or label
-     * locator.selectOption('blue');
+     * // Matches <span>
+     * locator.getByText('world');
      *
-     * // single selection matching the label
-     * locator.selectOption({ label: 'Blue' });
+     * // Matches first <div>
+     * locator.getByText('Hello world');
      *
-     * // multiple selection
-     * locator.selectOption(['red', 'green', 'blue']);
+     * // Matches second <div>
+     * locator.getByText('Hello', { exact: true });
+     *
+     * // Matches both <div>s
+     * locator.getByText(/Hello/);
+     *
+     * // Matches second <div>
+     * locator.getByText(/^hello$/i);
      * ```
      *
-     * @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;
 }
 
 /**
@@ -3487,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
@@ -4334,6 +5458,36 @@ export interface Page {
         },
     ): 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.