Playwright · API reference · all subjects

locator/methods

23 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Locator.or() method with alternative locator

The or() method takes a locator parameter of type Locator and returns a new locator that matches when either the original locator or the alternative locator matches. It was introduced in v1.33. The signature accepts one Locator parameter named 'locator' which represents an alternative locator to match.

Locator.page property returns Page

The page property of a Locator returns the Page object that the locator belongs to. It has been available since v1.19 and returns type Page.

Locator.press() async method signature and parameters

Locator.press() is an async method since v1.14 that focuses the matching element and presses a combination of keys. The method takes a required parameter 'key' of type string representing the name of the key to press or a character to generate, such as ArrowLeft or 'a'. The method also accepts optional parameters: delay (float, defaults to 0) representing time in milliseconds to wait between keydown and keyup, noWaitAfter, timeout (varies by language), and signal.

Locator.pressSequentially() async method parameters

Locator.pressSequentially() is an async method since v1.38 that focuses an element and sends keydown, keypress/input, and keyup events for each character in text. It takes a required parameter 'text' of type string representing the string of characters to sequentially press into a focused element. Optional parameters include: delay (float, defaults to 0) representing time to wait between key presses in milliseconds, noWaitAfter, timeout (varies by language), and signal.

Locator.screenshot() async method returns Buffer

Locator.screenshot() is an async method since v1.14 that takes a screenshot of the element matching the locator. It returns type Buffer containing the captured screenshot. The method accepts options: animations and path (common screenshot options v1.8+), timeout (varies by language), signal, maskColor (v1.34), and style (v1.41).

Locator.screenshot() with CSS selector example

To take a screenshot of an element with a specific CSS selector: await page.getByRole('link').screenshot(); or with animations disabled: await page.getByRole('link').screenshot({ animations: 'disabled', path: 'link.png' });

Locator.scrollIntoViewIfNeeded() async method

Locator.scrollIntoViewIfNeeded() is an async method since v1.14 that waits for actionability checks, then tries to scroll the element into view unless it is completely visible as defined by IntersectionObserver's ratio. It accepts optional parameters: timeout (varies by language) and signal.

Locator.selectOption() async method returns Array<string>

Locator.selectOption() is an async method since v1.14 that selects option or options in a <select> element. It returns type Array<string> containing the array of option values that have been successfully selected. The method accepts parameter 'values' (select options values), and optional parameters: force, noWaitAfter, timeout (varies by language), signal, and language-specific parameters element, index, value, and label.

Locator.selectOption() usage examples

Single selection matching value or label: element.selectOption('blue'); Single selection by label: element.selectOption({ label: 'Blue' }); Multiple selection: element.selectOption(['red', 'green', 'blue']);

Locator.selectText() async method

Locator.selectText() is an async method since v1.14 that waits for actionability checks, then focuses the element and selects all its text content. It accepts optional parameters: force, timeout (varies by language), and signal.

Locator.setChecked() async method parameters

Locator.setChecked() is an async method since v1.15 that sets the state of a checkbox or radio element. It takes a required parameter 'checked' of type boolean. Optional parameters include: force, scroll (v1.62), noWaitAfter, position, timeout (varies by language), signal, and trial.

Locator.setInputFiles() async method for file upload

Locator.setInputFiles() is an async method since v1.14 that uploads file or multiple files into <input type=file>. For inputs with [webkitdirectory] attribute, only a single directory path is supported. The method accepts parameter 'files' and optional parameters: noWaitAfter, timeout (varies by language), and signal. It supports uploading single files, multiple files, directories, or clearing files with an empty array.

Locator.setInputFiles() usage examples

Select one file: await page.getByLabel('Upload file').setInputFiles(path.join(__dirname, 'myfile.pdf')); Select multiple files: await page.getByLabel('Upload files').setInputFiles([path.join(__dirname, 'file1.txt'), path.join(__dirname, 'file2.txt')]); Upload buffer from memory: await page.getByLabel('Upload file').setInputFiles({ name: 'file.txt', mimeType: 'text/plain', buffer: Buffer.from('this is test') });

Locator.tap() async method for touch

Locator.tap() is an async method since v1.14 that performs a tap gesture on the element matching the locator. Optional parameters include: position, modifiers, force, scroll (v1.62), noWaitAfter, timeout (varies by language), signal, and trial. Note that tap() requires the hasTouch option of the browser context to be set to true.

Locator.textContent() async method returns null or string

Locator.textContent() is an async method since v1.14 that returns the node.textContent. It returns type null|string. Optional parameters include: timeout (varies by language) and signal.

Locator.toString() method returns string

Locator.toString() is a method since v1.57 (JavaScript only) that returns a human-readable representation of the locator, using the description if one exists; otherwise generates a string based on the locator's selector. It returns type string.

Locator.type() async method deprecated

Locator.type() is an async method since v1.14 that is deprecated. It focuses the element and sends keydown, keypress/input, and keyup events for each character in text. In most cases, use Locator.fill() instead. For special keyboard handling, use Locator.pressSequentially(). Parameters include: required text (string), and optional delay (float, defaults to 0), noWaitAfter, timeout (varies by language), and signal.

Locator.uncheck() async method

Locator.uncheck() is an async method since v1.14 that ensures a checkbox or radio element is unchecked. Optional parameters include: position, force, scroll (v1.62), noWaitAfter, timeout (varies by language), signal, and trial.

Locator.visible property returns filtered Locator

Locator.visible is a method since v1.63 that returns a locator matching only visible elements, ignoring invisible ones. It returns type Locator. Visibility is checked every time the locator is used, not at the moment of the visible() call. Example: await page.locator('button').visible().click();

Locator.waitFor() async method

Locator.waitFor() is an async method since v1.16 that returns when the element specified by the locator satisfies the state option. Optional parameters include: state (wait-for-selector-state), timeout (varies by language), and signal.

Locator.waitForFunction() async method

Locator.waitForFunction() is an async method since v1.62 that returns when the expression returns a truthy value, called with the matching element as the first argument and arg as the second argument. The locator is re-resolved on each retry. Parameters include: required expression (evaluated function), optional arg (EvaluationArgument), and optional timeout (varies by language) and signal.

Locator.waitForFunction() usage examples

Wait for an attribute to appear: const toggle = page.getByRole('button', { name: 'Menu' }); await toggle.click(); await toggle.waitForFunction(element => element.hasAttribute('aria-expanded')); Passing argument to expression: await page.getByTestId('status').waitForFunction((element, value) => { return element.textContent === value; }, 'Ready');

Locator.or() with chaining and filter methods example

Example of using or() with first() and isVisibleAsync(): var newEmail = page.GetByRole(AriaRole.Button, new() { Name = "New" }); var dialog = page.GetByText("Confirm security settings"); await Expect(newEmail.Or(dialog).First).ToBeVisibleAsync(); if (await dialog.IsVisibleAsync()) await page.GetByRole(AriaRole.Button, new() { Name = "Dismiss" }).ClickAsync(); await newEmail.ClickAsync();

Give your agent this brain