Playwright Locator | BCTRL

All Locator methods available when using the Playwright driver.

Access via runtime.page.locator(...) after launching a Playwright runtime.

How these methods work over HTTP

Every method below is a remote call. The SDK translates it into a structured step sent to a single endpoint:

POST /v1/workspaces/{workspaceId}/execute

1 {
2   "runtime": "my-browser",
3   "steps": [
4     {
5       "call": "locator.goto",
6       "args": ["https://example.com"]
7     }
8   ]
9 }

The call field maps directly to the method name. args is a JSON array of the method’s arguments. You can batch multiple steps in one request.

Actions

click(options?)

Clicks on the element.

Waits for actionability checks, scrolls element into view, and uses Page.mouse to click in the center of the element.

1 await locator.click();

Parameter	Type	Required	Description
`options`	`PlaywrightClickOptions`	No	—

Upstream docs

dblclick(options?)

Double-clicks on the element.

Performs two clicks with a short delay, simulating a native double-click. Waits for actionability checks before performing the action.

1 await runtime.page.locator(...).dblclick();

Parameter	Type	Required	Description
`options`	`PlaywrightDblclickOptions`	No	—

Upstream docs

fill(value, options?)

Fills an input or textarea element with the specified value.

This method waits for actionability checks, focuses the element, fills it, and triggers an input event. It clears the existing value before filling. Works with <input>, <textarea>, and [contenteditable] elements.

1 await page.getByLabel('Password').fill('secret');

Parameter	Type	Required	Description
`value`	`string`	Yes	Value to fill in
`options`	`PlaywrightFillOptions`	No	—

Upstream docs

clear(options?)

Clears the input field.

Waits for actionability checks, focuses the element, clears it, and triggers an input event.

1 await runtime.page.locator(...).clear();

Parameter	Type	Required	Description
`options`	`PlaywrightClearOptions`	No	—

Upstream docs

press(key, options?)

Presses a single key or key combination.

Focuses the element, then uses keyboard.down() and keyboard.up(). Supports modifier keys like Control, Shift, Alt, Meta.

1 await locator.press('Enter');

Parameter	Type	Required	Description
`key`	`string`	Yes	Key to press (e.g., “Enter”, “Control+A”)
`options`	`PlaywrightPressOptions`	No	—

Upstream docs

pressSequentially(text, options?)

Types text character by character with keydown, keypress, and keyup events.

Use this for special keyboard handling. In most cases, fill() is preferred. The delay option can simulate realistic typing speed.

1 await locator.pressSequentially('Hello');

Parameter	Type	Required	Description
`text`	`string`	Yes	Characters to type
`options`	`PlaywrightPressSequentiallyOptions`	No	—

Upstream docs

type(text, options?)

Types text into the element (DEPRECATED - use fill() or pressSequentially()).

This method is deprecated. Use fill() for most cases, or pressSequentially() when special keyboard handling is required.

1 await runtime.page.locator(...).type('...');

Parameter	Type	Required	Description
`text`	`string`	Yes	—
`options`	`{ delay?: number; noWaitAfter?: boolean; timeout?: number }`	No	—

Upstream docs

hover(options?)

Hovers over the element.

Waits for actionability checks, scrolls element into view, and moves mouse to the center of the element.

1 await runtime.page.locator(...).hover();

Parameter	Type	Required	Description
`options`	`PlaywrightHoverOptions`	No	—

Upstream docs

tap(options?)

Performs a tap gesture on the element.

Requires hasTouch option to be enabled in browser context. Waits for actionability checks before performing the tap.

1 await runtime.page.locator(...).tap();

Parameter	Type	Required	Description
`options`	`PlaywrightTapOptions`	No	—

Upstream docs

focus(options?)

Focuses the element.

1 await runtime.page.locator(...).focus();

Parameter	Type	Required	Description
`options`	`PlaywrightFocusOptions`	No	—

Upstream docs

blur(options?)

Removes focus from the element.

1 await runtime.page.locator(...).blur();

Parameter	Type	Required	Description
`options`	`PlaywrightBlurOptions`	No	—

Upstream docs

check(options?)

Checks a checkbox or radio button.

If already checked, this method does nothing.

1 await runtime.page.locator(...).check();

Parameter	Type	Required	Description
`options`	`PlaywrightCheckOptions`	No	—

Upstream docs

uncheck(options?)

Unchecks a checkbox.

If already unchecked, this method does nothing.

1 await runtime.page.locator(...).uncheck();

Parameter	Type	Required	Description
`options`	`PlaywrightUncheckOptions`	No	—

Upstream docs

setChecked(checked, options?)

Sets the checked state of a checkbox or radio button.

1 await runtime.page.locator(...).setChecked(true);

Parameter	Type	Required	Description
`checked`	`boolean`	Yes	Whether to check or uncheck
`options`	`PlaywrightSetCheckedOptions`	No	—

Upstream docs

selectOption(values, options?)

Selects option(s) in a <select> element.

Waits for actionability checks, waits until all options are present, and triggers change and input events. Returns array of selected option values.

1 await locator.selectOption('blue');

Parameter	Type	Required	Description
`values`	`string \| string[] \| PlaywrightSelectOptionValue \| PlaywrightSelectOptionValue[]`	Yes	Options to select by value, label, or index
`options`	`PlaywrightSelectOptionOptions`	No	—

Returns string[]

Upstream docs

selectText(options?)

Selects all text content of the element.

This method waits for actionability checks, then focuses the element and selects all text content.

1 await runtime.page.locator(...).selectText();

Parameter	Type	Required	Description
`options`	`{ force?: boolean; timeout?: number }`	No	—

Upstream docs

setInputFiles(files, options?)

Sets files for a file input element.

Pass empty array to clear selected files. Supports paths, objects with name/mimeType/buffer, or directories.

1 await locator.setInputFiles('file.pdf');

Parameter	Type	Required	Description
`files`	`string \| string[] \| PlaywrightFilePayload \| PlaywrightFilePayload[]`	Yes	File paths or file objects to upload
`options`	`PlaywrightSetInputFilesOptions`	No	—

Upstream docs

dragTo(target, options?)

Drags this element to the target element.

Performs mousedown on source, moves to target, and releases with mouseup. Supports sourcePosition and targetPosition options for precise control.

1 await source.dragTo(target);

Parameter	Type	Required	Description
`target`	`RemotePlaywrightLocator`	Yes	Target locator to drag to
`options`	`PlaywrightDragToOptions`	No	—

Upstream docs

scrollIntoViewIfNeeded(options?)

Scrolls the element into view if not already visible.

Uses IntersectionObserver to determine if element is already visible.

1 await runtime.page.locator(...).scrollIntoViewIfNeeded();

Parameter	Type	Required	Description
`options`	`PlaywrightScrollIntoViewIfNeededOptions`	No	—

Upstream docs

dispatchEvent(type, eventInit?, options?)

Programmatically dispatches a DOM event on the element.

The event is created as composed, cancelable, and bubbles by default. Works regardless of element visibility state.

1 await locator.dispatchEvent('click');

Parameter	Type	Required	Description
`type`	`string`	Yes	DOM event type (e.g., “click”, “dragstart”)
`eventInit`	`Record<string, unknown>`	No	Event initialization properties
`options`	`PlaywrightDispatchEventOptions`	No	—

Upstream docs

highlight()

Highlights the element on screen (for debugging).

Useful for debugging during test development. Not recommended for production tests.

1 await runtime.page.locator(...).highlight();

Upstream docs

Queries

count()

Returns the number of elements matching this locator.

For assertions, prefer expect(locator).toHaveCount() to avoid flakiness.

1 const count = await page.getByRole('listitem').count();

Returns number

Upstream docs

first()

Returns locator to the first matching element.

1 runtime.page.locator(...).first();

Returns RemotePlaywrightLocator

Upstream docs

last()

Returns locator to the last matching element.

1 runtime.page.locator(...).last();

Returns RemotePlaywrightLocator

Upstream docs

nth(index)

Returns locator to the nth matching element.

Index is zero-based. Negative indices count from the end (-1 is last).

1 runtime.page.locator(...).nth(0);

Parameter	Type	Required	Description
`index`	`number`	Yes	Zero-based index

Returns RemotePlaywrightLocator

Upstream docs

locator(selectorOrLocator, options?)

Creates a locator matching descendants of this element.

Accepts CSS, XPath, or text selectors. Can also accept another locator.

1 const button = row.locator('button.submit');

Parameter	Type	Required	Description
`selectorOrLocator`	`string \| RemotePlaywrightLocator`	Yes	Selector or locator to match descendants
`options`	`PlaywrightLocatorOptions`	No	—

Returns RemotePlaywrightLocator

Upstream docs

Narrows the locator with additional filters.

Supports has, hasNot, hasText, hasNotText, and visible options. Multiple filters can be chained.

1 const row = page.locator('tr').filter({ hasText: 'John' });

Parameter	Type	Required	Description
`options`	`PlaywrightLocatorFilterOptions`	No	—

Returns RemotePlaywrightLocator

Upstream docs

and(locator)

Creates a locator that matches both this locator AND the argument.

Both conditions must be satisfied for an element to match.

1 const button = page.getByRole('button').and(page.getByTitle('Subscribe'));

Parameter	Type	Required	Description
`locator`	`RemotePlaywrightLocator`	Yes	Additional locator to match

Returns RemotePlaywrightLocator

Upstream docs

or(locator)

Creates a locator that matches this locator OR the argument.

Either condition being satisfied will match. Be careful with strict mode - if both match, use .first() to select one.

1 const btnOrLink = page.getByRole('button').or(page.getByRole('link'));

Parameter	Type	Required	Description
`locator`	`RemotePlaywrightLocator`	Yes	Alternative locator to match

Returns RemotePlaywrightLocator

Upstream docs

all()

Returns array of locators pointing to all matching elements.

Does not wait for elements. Use with caution on dynamic lists. Wait for the list to stabilize before calling.

1 for (const li of await page.getByRole('listitem').all()) {
2   await li.click();
3 }

Returns RemotePlaywrightLocator[]

Upstream docs

getByRole(role, options?)

Locates elements by their ARIA role.

Matches by implicit ARIA role (e.g., <button>) or explicit role attribute. Options include name, checked, disabled, expanded, etc.

1 await locator.getByRole('button', { name: 'Submit' }).click();

Parameter	Type	Required	Description
`role`	`PlaywrightAriaRole`	Yes	ARIA role to match
`options`	`PlaywrightGetByRoleOptions`	No	—

Returns RemotePlaywrightLocator

Upstream docs

getByText(text, options?)

Locates elements containing the specified text.

Matches case-insensitively by default. Use exact: true for exact match.

1 await locator.getByText('Welcome').click();

Parameter	Type	Required	Description
`text`	`string \| RegExp`	Yes	Text or pattern to match
`options`	`PlaywrightGetByTextOptions`	No	—

Returns RemotePlaywrightLocator

Upstream docs

getByLabel(text, options?)

Locates form elements by their associated label text.

Matches <label> text, aria-label, or aria-labelledby.

1 await locator.getByLabel('Email').fill('[email protected]');

Parameter	Type	Required	Description
`text`	`string \| RegExp`	Yes	Label text or pattern
`options`	`PlaywrightGetByLabelOptions`	No	—

Returns RemotePlaywrightLocator

Upstream docs

getByPlaceholder(text, options?)

Locates input elements by their placeholder text.

1 await locator.getByPlaceholder('Search...').fill('query');

Parameter	Type	Required	Description
`text`	`string \| RegExp`	Yes	Placeholder text or pattern
`options`	`PlaywrightGetByPlaceholderOptions`	No	—

Returns RemotePlaywrightLocator

Upstream docs

getByAltText(text, options?)

Locates elements by their alt attribute (typically images).

1 await locator.getByAltText('Company Logo').click();

Parameter	Type	Required	Description
`text`	`string \| RegExp`	Yes	Alt text or pattern
`options`	`PlaywrightGetByAltTextOptions`	No	—

Returns RemotePlaywrightLocator

Upstream docs

getByTitle(text, options?)

Locates elements by their title attribute.

1 await locator.getByTitle('More information').click();

Parameter	Type	Required	Description
`text`	`string \| RegExp`	Yes	Title attribute text or pattern
`options`	`PlaywrightGetByTitleOptions`	No	—

Returns RemotePlaywrightLocator

Upstream docs

getByTestId(testId)

Locates elements by their test ID attribute.

Default attribute is data-testid. Can be configured via selectors.setTestIdAttribute().

1 await locator.getByTestId('submit-button').click();

Parameter	Type	Required	Description
`testId`	`string \| RegExp`	Yes	Test ID value or pattern

Returns RemotePlaywrightLocator

Upstream docs

contentFrame()

Returns a FrameLocator pointing to the iframe this locator points to.

Useful when you have a Locator to an iframe and want to interact with its content.

1 const frameLocator = locator.contentFrame();
2 await frameLocator.getByRole('button').click();

Returns RemotePlaywrightFrameLocator

Upstream docs

frameLocator(selector)

Returns a FrameLocator for an iframe within this element.

Use to interact with content inside iframes.

1 const frame = locator.frameLocator('iframe.content');

Parameter	Type	Required	Description
`selector`	`string`	Yes	CSS selector for iframe

Returns RemotePlaywrightFrameLocator

Upstream docs

page()

Returns the Page that this locator belongs to.

1 runtime.page.locator(...).page();

Returns RemotePlaywrightPage

Upstream docs

Content

innerHTML(options?)

Returns the innerHTML of the element.

1 await runtime.page.locator(...).innerHTML();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns string

Upstream docs

innerText(options?)

Returns the innerText of the element.

For assertions, prefer expect(locator).toHaveText() with useInnerText option.

1 await runtime.page.locator(...).innerText();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns string

Upstream docs

textContent(options?)

Returns the textContent of the element.

For assertions, prefer expect(locator).toHaveText().

1 await runtime.page.locator(...).textContent();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns string \| null

Upstream docs

allInnerTexts()

Returns an array of innerText values for all matching elements.

For assertions, prefer expect(locator).toHaveText() with useInnerText option.

1 const texts = await page.getByRole('link').allInnerTexts();

Returns string[]

Upstream docs

allTextContents()

Returns an array of textContent values for all matching elements.

For assertions, prefer expect(locator).toHaveText().

1 const texts = await page.getByRole('link').allTextContents();

Returns string[]

Upstream docs

getAttribute(name, options?)

Returns the attribute value of the element.

1 await runtime.page.locator(...).getAttribute('...');

Parameter	Type	Required	Description
`name`	`string`	Yes	Attribute name
`options`	`{ timeout?: number }`	No	—

Returns string \| null

Upstream docs

inputValue(options?)

Returns the input value for <input>, <textarea>, or <select> elements.

1 await runtime.page.locator(...).inputValue();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns string

Upstream docs

boundingBox(options?)

Returns the bounding box of the element, or null if not visible.

Returns { x, y, width, height } in pixels relative to the main frame viewport. Scrolling affects the coordinates. Returns null if element is not visible.

1 const box = await locator.boundingBox();
2 await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);

Parameter	Type	Required	Description
`options`	`PlaywrightBoundingBoxOptions`	No	—

Returns PlaywrightBoundingBox \| null

Upstream docs

State Checks

isVisible(options?)

Returns whether the element is visible.

Does not wait for element to appear. For assertions, prefer expect(locator).toBeVisible().

1 await runtime.page.locator(...).isVisible();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns boolean

Upstream docs

isHidden(options?)

Returns whether the element is hidden.

Opposite of isVisible(). For assertions, prefer expect(locator).toBeHidden().

1 await runtime.page.locator(...).isHidden();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns boolean

Upstream docs

isEnabled(options?)

Returns whether the element is enabled.

For assertions, prefer expect(locator).toBeEnabled().

1 await runtime.page.locator(...).isEnabled();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns boolean

Upstream docs

isDisabled(options?)

Returns whether the element is disabled.

For assertions, prefer expect(locator).toBeDisabled().

1 await runtime.page.locator(...).isDisabled();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns boolean

Upstream docs

isChecked(options?)

Returns whether a checkbox or radio is checked.

For assertions, prefer expect(locator).toBeChecked().

1 await runtime.page.locator(...).isChecked();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns boolean

Upstream docs

isEditable(options?)

Returns whether the element is editable.

For assertions, prefer expect(locator).toBeEditable().

1 await runtime.page.locator(...).isEditable();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns boolean

Upstream docs

Waiting

waitFor(options?)

Waits for element to satisfy the given state.

State options: ‘attached’, ‘detached’, ‘visible’, ‘hidden’. Returns immediately if condition is already met. Default state is ‘visible’.

1 await locator.waitFor();

Parameter	Type	Required	Description
`options`	`PlaywrightWaitForOptions`	No	—

Upstream docs

Screenshots & PDF

screenshot(options?)

Takes a screenshot of the element.

Waits for actionability checks and scrolls element into view. Returns screenshot clipped to element size and position.

1 await runtime.page.locator(...).screenshot();

Parameter	Type	Required	Description
`options`	`PlaywrightScreenshotOptions`	No	—

Returns Buffer

Upstream docs

Evaluation

evaluate(pageFunction, arg?, options?)

Evaluates a function in the browser context with the element as first argument.

Returns the value of the evaluated function. The function receives the DOM element as first argument.

1 const tagName = await locator.evaluate(el => el.tagName);

Parameter	Type	Required	Description
`pageFunction`	`string \| ((element: Element, arg: Arg) => R \| Promise<R>)`	Yes	Function to evaluate in browser context
`arg`	`Arg`	No	Argument to pass to function
`options`	`PlaywrightEvaluateOptions`	No	—

Returns R

Upstream docs

evaluateAll(pageFunction, arg?)

Evaluates a function with all matching elements as first argument.

Does not wait for elements - returns empty array if none match.

1 const count = await locator.evaluateAll(els => els.length);

Parameter	Type	Required	Description
`pageFunction`	`string \| ((elements: Element[], arg: Arg) => R \| Promise<R>)`	Yes	Function to evaluate in browser context
`arg`	`Arg`	No	Argument to pass to function

Returns R

Upstream docs

evaluateHandle(pageFunction, arg?)

Returns a JSHandle with the result of the evaluation.

Use when you need to retain a reference to a JavaScript object in the page. Note: JSHandle is not fully supported in the remote SDK.

1 await runtime.page.locator(...).evaluateHandle(/* pageFunction */);

Parameter	Type	Required	Description
`pageFunction`	`string \| ((element: Element, arg: Arg) => R \| Promise<R>)`	Yes	Function to evaluate in browser context
`arg`	`Arg`	No	Argument to pass to function

Returns unknown

Upstream docs

Other

elementHandle(options?)

Resolves to the ElementHandle of the element.

Returns the handle to the element that matches this locator. Throws if no elements or multiple elements match.

1 await runtime.page.locator(...).elementHandle();

Parameter	Type	Required	Description
`options`	`{ timeout?: number }`	No	—

Returns RemotePlaywrightElementHandle

Upstream docs

elementHandles()

Resolves to all ElementHandles matching this locator.

Returns an empty array if no elements match.

1 await runtime.page.locator(...).elementHandles();

Returns RemotePlaywrightElementHandle[]

Upstream docs

How these methods work over HTTP

Actions

click(options?)

dblclick(options?)

fill(value, options?)

clear(options?)

press(key, options?)

pressSequentially(text, options?)

type(text, options?)

hover(options?)

tap(options?)

focus(options?)

blur(options?)

check(options?)

uncheck(options?)

setChecked(checked, options?)

selectOption(values, options?)

selectText(options?)

setInputFiles(files, options?)

dragTo(target, options?)

scrollIntoViewIfNeeded(options?)

dispatchEvent(type, eventInit?, options?)

highlight()

Queries

count()

first()

last()

nth(index)

locator(selectorOrLocator, options?)

filter(options?)

and(locator)

or(locator)

all()

getByRole(role, options?)

getByText(text, options?)

getByLabel(text, options?)

getByPlaceholder(text, options?)

getByAltText(text, options?)

getByTitle(text, options?)

getByTestId(testId)

contentFrame()

frameLocator(selector)

page()

Content

innerHTML(options?)

innerText(options?)

textContent(options?)

allInnerTexts()

allTextContents()

getAttribute(name, options?)

inputValue(options?)

boundingBox(options?)

State Checks

isVisible(options?)

isHidden(options?)

isEnabled(options?)

isDisabled(options?)

isChecked(options?)

isEditable(options?)

Waiting

waitFor(options?)

Screenshots & PDF

screenshot(options?)

Evaluation

evaluate(pageFunction, arg?, options?)

evaluateAll(pageFunction, arg?)

evaluateHandle(pageFunction, arg?)

Other

elementHandle(options?)

elementHandles()