Locator

Locator represents a view to elements that match a selector. Locators are strict by default and automatically wait for elements to be actionable.

Constructor

new Locator(frame: Frame, selector: string, options?: LocatorOptions)

Frame

required

Parent frame

string

required

Selector to locate elements

LocatorOptions

Locator options

hasText (string | RegExp): Matches elements containing text
hasNotText (string | RegExp): Matches elements not containing text
has (Locator): Matches elements containing another locator
hasNot (Locator): Matches elements not containing another locator
visible (boolean): Matches only visible elements

Filtering Methods

filter

Creates a filtered locator.

filter(options?: LocatorOptions): Locator

LocatorOptions

Filter options

Returns: Locator - Filtered locator

first

Returns first matching element.

first(): Locator

Returns: Locator - Locator for first element

last

Returns last matching element.

last(): Locator

Returns: Locator - Locator for last element

nth

Returns nth matching element.

nth(index: number): Locator

number

required

Element index (0-based, negative for reverse)

Returns: Locator - Locator for nth element

and

Combines with another locator (AND).

and(locator: Locator): Locator

Locator

required

Locator to combine with

Returns: Locator - Combined locator

or

Combines with another locator (OR).

or(locator: Locator): Locator

Locator

required

Locator to combine with

Returns: Locator - Combined locator

Chaining Methods

Creates a descendant locator.

locator(selectorOrLocator: string | Locator, options?: LocatorOptions): Locator

string | Locator

required

Descendant selector or locator

LocatorOptions

Locator options

Returns: Locator - Descendant locator

getByRole

Finds by ARIA role.

getByRole(role: string, options?: ByRoleOptions): Locator

getByText

Finds by text content.

getByText(text: string | RegExp, options?: { exact?: boolean }): Locator

getByLabel

Finds by label text.

getByLabel(text: string | RegExp, options?: { exact?: boolean }): Locator

getByPlaceholder

Finds by placeholder text.

getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): Locator

getByAltText

Finds by alt text.

getByAltText(text: string | RegExp, options?: { exact?: boolean }): Locator

getByTitle

Finds by title attribute.

getByTitle(text: string | RegExp, options?: { exact?: boolean }): Locator

getByTestId

Finds by test ID.

getByTestId(testId: string | RegExp): Locator

frameLocator

Creates a frame locator.

frameLocator(selector: string): FrameLocator

contentFrame

Gets frame content locator.

contentFrame(): FrameLocator

Returns: FrameLocator - Frame locator

Action Methods

click

Clicks the element.

click(options?: ClickOptions): Promise<void>

ClickOptions

Click options

button (‘left’ | ‘right’ | ‘middle’): Mouse button
clickCount (number): Number of clicks
delay (number): Delay between mousedown and mouseup
position (object): Click position
modifiers (string[]): Modifier keys
force (boolean): Force click
noWaitAfter (boolean): Don’t wait after click
timeout (number): Maximum time

Returns: Promise<void>

dblclick

Double clicks the element.

dblclick(options?: DblClickOptions): Promise<void>

fill

Fills an input element.

fill(value: string, options?: FillOptions): Promise<void>

string

required

Value to fill

FillOptions

Fill options

force (boolean): Force fill
noWaitAfter (boolean): Don’t wait after fill
timeout (number): Maximum time

Returns: Promise<void>

clear

Clears an input element.

clear(options?: FillOptions): Promise<void>

FillOptions

Clear options

Returns: Promise<void>

type

Types text into element.

type(text: string, options?: TypeOptions): Promise<void>

string

required

Text to type

TypeOptions

Type options

delay (number): Delay between key presses
timeout (number): Maximum time

Returns: Promise<void>

pressSequentially

Presses keys sequentially.

pressSequentially(text: string, options?: TypeOptions): Promise<void>

press

Presses a key.

press(key: string, options?: PressOptions): Promise<void>

string

required

Key to press (e.g., ‘Enter’, ‘ArrowDown’)

PressOptions

Press options

Returns: Promise<void>

check

Checks a checkbox.

check(options?: CheckOptions): Promise<void>

uncheck

Unchecks a checkbox.

uncheck(options?: CheckOptions): Promise<void>

setChecked

Sets checkbox state.

setChecked(checked: boolean, options?: CheckOptions): Promise<void>

boolean

required

Whether to check or uncheck

CheckOptions

Check options

Returns: Promise<void>

selectOption

Selects options.

selectOption(values: string | string[] | SelectOption | SelectOption[], options?: SelectOptionOptions): Promise<string[]>

string | string[] | SelectOption | SelectOption[]

required

Values to select

SelectOptionOptions

Select options

Returns: Promise<string[]> - Selected values

hover

Hovers over element.

hover(options?: HoverOptions): Promise<void>

tap

Taps the element.

tap(options?: TapOptions): Promise<void>

focus

Focuses the element.

focus(options?: TimeoutOptions): Promise<void>

blur

Blurs the element.

blur(options?: TimeoutOptions): Promise<void>

dragTo

Drags to another locator.

dragTo(target: Locator, options?: DragAndDropOptions): Promise<void>

Locator

required

Target locator

DragAndDropOptions

Drag options

Returns: Promise<void>

setInputFiles

Sets input files.

setInputFiles(files: string | string[] | FilePayload | FilePayload[], options?: SetInputFilesOptions): Promise<void>

string | string[] | FilePayload | FilePayload[]

required

Files to upload

SetInputFilesOptions

Upload options

Returns: Promise<void>

dispatchEvent

Dispatches a DOM event.

dispatchEvent(type: string, eventInit?: any, options?: TimeoutOptions): Promise<void>

string

required

Event type

any

Event initialization object

TimeoutOptions

Timeout options

Returns: Promise<void>

Content Methods

textContent

Returns text content.

textContent(options?: TimeoutOptions): Promise<string | null>

Returns: Promise<string | null> - Text content or null

innerText

Returns inner text.

innerText(options?: TimeoutOptions): Promise<string>

Returns: Promise<string> - Inner text

innerHTML

Returns inner HTML.

innerHTML(options?: TimeoutOptions): Promise<string>

Returns: Promise<string> - Inner HTML

inputValue

Returns input value.

inputValue(options?: TimeoutOptions): Promise<string>

Returns: Promise<string> - Input value

getAttribute

Returns attribute value.

getAttribute(name: string, options?: TimeoutOptions): Promise<string | null>

string

required

Attribute name

TimeoutOptions

Timeout options

Returns: Promise<string | null> - Attribute value or null

allTextContents

Returns all text contents.

allTextContents(): Promise<string[]>

Returns: Promise<string[]> - Array of text contents

allInnerTexts

Returns all inner texts.

allInnerTexts(): Promise<string[]>

Returns: Promise<string[]> - Array of inner texts

State Methods

isVisible

Checks if visible.

isVisible(options?: TimeoutOptions): Promise<boolean>

Returns: Promise<boolean> - True if visible

isHidden

Checks if hidden.

isHidden(options?: TimeoutOptions): Promise<boolean>

Returns: Promise<boolean> - True if hidden

isEnabled

Checks if enabled.

isEnabled(options?: TimeoutOptions): Promise<boolean>

Returns: Promise<boolean> - True if enabled

isDisabled

Checks if disabled.

isDisabled(options?: TimeoutOptions): Promise<boolean>

Returns: Promise<boolean> - True if disabled

isChecked

Checks if checked.

isChecked(options?: TimeoutOptions): Promise<boolean>

Returns: Promise<boolean> - True if checked

isEditable

Checks if editable.

isEditable(options?: TimeoutOptions): Promise<boolean>

Returns: Promise<boolean> - True if editable

Evaluation Methods

evaluate

Evaluates JavaScript on element.

evaluate<R, Arg>(pageFunction: Function, arg?: Arg, options?: TimeoutOptions): Promise<R>

Function

required

Function to evaluate

any

Argument to pass

TimeoutOptions

Timeout options

Returns: Promise<R> - Evaluation result

evaluateAll

Evaluates on all matching elements.

evaluateAll<R, Arg>(pageFunction: Function, arg?: Arg): Promise<R>

evaluateHandle

Evaluates and returns JSHandle.

evaluateHandle<R, Arg>(pageFunction: Function, arg?: Arg, options?: TimeoutOptions): Promise<JSHandle<R>>

Utility Methods

count

Returns number of matching elements.

count(): Promise<number>

Returns: Promise<number> - Count of elements

all

Returns all matching locators.

all(): Promise<Locator[]>

Returns: Promise<Locator[]> - Array of locators

boundingBox

Returns bounding box.

boundingBox(options?: TimeoutOptions): Promise<Rect | null>

Returns: Promise<Rect | null> - Bounding box or null

screenshot

Takes a screenshot.

screenshot(options?: ScreenshotOptions): Promise<Buffer>

ScreenshotOptions

Screenshot options

path (string): File path to save to
type (‘png’ | ‘jpeg’): Image type
quality (number): JPEG quality
omitBackground (boolean): Transparent background
timeout (number): Maximum time
mask (Locator[]): Elements to mask

Returns: Promise<Buffer> - Screenshot buffer

scrollIntoViewIfNeeded

Scrolls element into view.

scrollIntoViewIfNeeded(options?: TimeoutOptions): Promise<void>

Returns: Promise<void>

selectText

Selects text.

selectText(options?: TimeoutOptions): Promise<void>

Returns: Promise<void>

waitFor

Waits for element state.

waitFor(options?: WaitForOptions): Promise<void>

WaitForOptions

Wait options

state (‘attached’ | ‘visible’ | ‘hidden’ | ‘detached’): Element state
timeout (number): Maximum time

Returns: Promise<void>

elementHandle

Returns element handle.

elementHandle(options?: TimeoutOptions): Promise<ElementHandle>

Returns: Promise<ElementHandle> - Element handle

elementHandles

Returns all element handles.

elementHandles(): Promise<ElementHandle[]>

Returns: Promise<ElementHandle[]> - Array of element handles

page

Returns parent page.

page(): Page

Returns: Page - Parent page

highlight

Highlights the element.

highlight(): Promise<void>

Returns: Promise<void>

ariaSnapshot

Returns ARIA snapshot.

ariaSnapshot(options?: TimeoutOptions): Promise<string>

Returns: Promise<string> - ARIA snapshot

describe

Adds custom description.

describe(description: string): Locator

string

required

Custom description

Returns: Locator - Locator with description

description

Returns custom description.

description(): string | null

Returns: string | null - Custom description or null

Usage Examples

Basic Locator Usage

import { test, expect } from '@playwright/test';

test('locator basics', async ({ page }) => {
  await page.goto('https://example.com');
  
  const button = page.locator('button#submit');
  await button.click();
  
  await expect(button).toBeDisabled();
});

Filtering Locators

const products = page.locator('.product');

// Filter by text
const macbook = products.filter({ hasText: 'MacBook' });
await macbook.click();

// Filter by child element
const inStock = products.filter({
  has: page.locator('.in-stock'),
});

// Chain filters
const filtered = products
  .filter({ hasText: 'iPhone' })
  .filter({ visible: true })
  .first();

Using Get By Methods

// By role
const submitButton = page.getByRole('button', { name: 'Submit' });
await submitButton.click();

// By text
const heading = page.getByText('Welcome back');
await expect(heading).toBeVisible();

// By label
const emailInput = page.getByLabel('Email address');
await emailInput.fill('test@example.com');

// By placeholder
const searchInput = page.getByPlaceholder('Search...');
await searchInput.type('Playwright');

// By test ID
const menu = page.getByTestId('main-menu');
await menu.click();

Chaining Locators

const article = page.locator('article');
const title = article.locator('h1');
const author = article.getByText(/Author:/i);

await expect(title).toContainText('Introduction');
await expect(author).toBeVisible();

Working with Multiple Elements

const items = page.locator('.item');

// Count elements
const count = await items.count();
console.log(`Found ${count} items`);

// Iterate over elements
for (let i = 0; i < count; i++) {
  const item = items.nth(i);
  console.log(await item.textContent());
}

// Get all locators
const allItems = await items.all();
for (const item of allItems) {
  await item.click();
}

// Get all text contents
const texts = await items.allTextContents();
console.log(texts);

Page - Page containing locator
Frame - Frame containing locator
ElementHandle - Element handles
FrameLocator - Frame locators

​Constructor

​Filtering Methods

​filter

​first

​last

​nth

​and

​or

​Chaining Methods

​locator

​getByRole

​getByText

​getByLabel

​getByPlaceholder

​getByAltText

​getByTitle

​getByTestId

​frameLocator

​contentFrame

​Action Methods

​click

​dblclick

​fill

​clear

​type

​pressSequentially

​press

​check

​uncheck

​setChecked

​selectOption

​hover

​tap

​focus

​blur

​dragTo

​setInputFiles

​dispatchEvent

​Content Methods

​textContent

​innerText

​innerHTML

​inputValue

​getAttribute

​allTextContents

​allInnerTexts

​State Methods

​isVisible

​isHidden

​isEnabled

​isDisabled

​isChecked

​isEditable

​Evaluation Methods

​evaluate

​evaluateAll

​evaluateHandle

​Utility Methods

​count

​all

​boundingBox

​screenshot

​scrollIntoViewIfNeeded

​selectText

​waitFor

​elementHandle

​elementHandles

​page

​highlight

​ariaSnapshot

​describe

​description

​Usage Examples

​Basic Locator Usage

​Filtering Locators

​Using Get By Methods

​Chaining Locators

​Working with Multiple Elements

​Related Classes

Constructor

Filtering Methods

filter

first

last

nth

and

or

Chaining Methods

locator

getByRole

getByText

getByLabel

getByPlaceholder

getByAltText

getByTitle

getByTestId

frameLocator

contentFrame

Action Methods

click

dblclick

fill

clear

type

pressSequentially

press

check

uncheck

setChecked

selectOption

hover

tap

focus

blur

dragTo

setInputFiles

dispatchEvent

Content Methods

textContent

innerText

innerHTML

inputValue

getAttribute

allTextContents

allInnerTexts

State Methods

isVisible

isHidden

isEnabled

isDisabled

isChecked

isEditable

Evaluation Methods

evaluate

evaluateAll

evaluateHandle

Utility Methods

count

all

boundingBox

screenshot

scrollIntoViewIfNeeded

selectText

waitFor

elementHandle

elementHandles

page

highlight

ariaSnapshot

describe

description

Usage Examples

Basic Locator Usage

Filtering Locators

Using Get By Methods

Chaining Locators

Working with Multiple Elements

Related Classes