Locator Class

Finds elements of a page, as the locators of Playwright: a locator is a query, evaluated again each time it is used, so it finds the new elements when the page renders again. The actions wait until the locator finds exactly one element and the element is actionable; the assertions of Expectations.Expect wait until they pass. A locator that finds more than one element where one is needed throws a StrictModeViolationException.

public sealed class Locator : LocatorScope
Inheritance
LocatorScope Locator

Properties

NameDescription
CountGets the number of elements that the locator finds now.
FirstGets a locator of the first element of this locator.
InputValueGets the value of the field (input, textarea or select, or the control of a label).
IsCheckedGets whether the check box, the radio button, or the element with a checked state is checked.
IsEditableGets whether the field is editable: enabled and not read-only.
IsEnabledGets whether the element is enabled: not a disabled form control, and no aria-disabled="true".
IsVisibleGets whether the locator finds a visible element now: a non-empty box, and not visibility: hidden. False when it finds no element.
LastGets a locator of the last element of this locator.
PageGets the page of the locator.
TextContentGets the text content of the element.

Gets the number of elements that the locator finds now.

public int Count { get; }

Property value

int

Gets a locator of the first element of this locator.

public Locator First { get; }

Property value

Locator

InputValue

Locator.cs

Gets the value of the field (input, textarea or select, or the control of a label).

public string InputValue { get; }

Property value

string

Exceptions

ElementNotFoundException
The locator finds no element.
StrictModeViolationException
The locator finds more than one element.
InvalidOperationException
The element is not a field.

IsChecked

Locator.cs

Gets whether the check box, the radio button, or the element with a checked state is checked.

public bool IsChecked { get; }

Property value

bool

Exceptions

ElementNotFoundException
The locator finds no element.
StrictModeViolationException
The locator finds more than one element.
InvalidOperationException
The element has no checked state.

IsEditable

Locator.cs

Gets whether the field is editable: enabled and not read-only.

public bool IsEditable { get; }

Property value

bool

Exceptions

ElementNotFoundException
The locator finds no element.
StrictModeViolationException
The locator finds more than one element.
InvalidOperationException
The element is not a field.

IsEnabled

Locator.cs

Gets whether the element is enabled: not a disabled form control, and no aria-disabled="true".

public bool IsEnabled { get; }

Property value

bool

Exceptions

ElementNotFoundException
The locator finds no element.
StrictModeViolationException
The locator finds more than one element.

IsVisible

Locator.cs

Gets whether the locator finds a visible element now: a non-empty box, and not visibility: hidden. False when it finds no element.

public bool IsVisible { get; }

Property value

bool

Exceptions

StrictModeViolationException
The locator finds more than one element.

Gets a locator of the last element of this locator.

public Locator Last { get; }

Property value

Locator

Gets the page of the locator.

public TestPage Page { get; }

Property value

TestPage

TextContent

Locator.cs

Gets the text content of the element.

public string TextContent { get; }

Property value

string

Exceptions

ElementNotFoundException
The locator finds no element.
StrictModeViolationException
The locator finds more than one element.

Methods

NameDescription
And(Locator)Gets a locator of the elements that this locator and another locator both find (page.GetByRole("button").And(page.GetByTitle("Subscribe"))).
CheckAsync(CancellationToken)Checks the check box or the radio button with a click, when it is not checked. An element of a label checks the control of the label.
ClearAsync(CancellationToken)Clears the value of the text field, then leaves the field.
ClickAsync(ClickOptions?, CancellationToken)Clicks the element at its center (or at ClickOptions.Position), once the locator finds it and it is visible, stable, enabled and not covered by another element.
DoubleClickAsync(CancellationToken)Double-clicks the element.
DragToAsync(Locator, CancellationToken)Drags the element with the mouse, and drops it on the element of another locator (the HTML drag and drop events).
FillAsync(string, CancellationToken)Replaces the value of the text field with a text typed with the keyboard, then leaves the field (the change event, so @bind updates the value). Waits until the field is visible, enabled and editable. An element of a label fills the control of the label.
Filter(LocatorFilterOptions)Gets a locator of the elements of this locator that satisfy conditions.
FocusAsync(CancellationToken)Focuses the element.
GetAccessibilitySnapshot()Gets the accessibility tree of the element, as a YAML snapshot (the format of the ARIA snapshots of Playwright).
GetAll()Gets a locator for each element that the locator finds now (Nth(0), Nth(1)...).
GetAttribute(string)Gets the value of an attribute of the element, or null when it has no such attribute.
GetElement()Gets the element that the locator finds now.
GetElementOrDefault()Gets the element that the locator finds now, or null.
GetElements()Gets the elements that the locator finds now, in document order.
GetMarkup(MarkupOptions?)Gets the HTML of the element, formatted for snapshots.
HoverAsync(CancellationToken)Moves the mouse over the element, once it is visible, stable and not covered by another element.
Nth(int)Gets a locator of the element at an index of the elements of this locator.
Or(Locator)Gets a locator of the elements that this locator or another locator finds, in document order (page.GetByRole("button", "New").Or(page.GetByText("Confirm"))).
PressAsync(string, string[])Focuses the element, and presses a key (a character or a key name such as Enter, Tab, ArrowDown) while modifier keys are held.
SelectOptionAsync(string[])Selects options of the select element by value or by label, and fires the input and change events. Waits until the element is visible and enabled, and until it has all the options.
SetCheckedAsync(bool, CancellationToken)Checks or unchecks the check box with a click, when its state is not isChecked.
TakeScreenshotAsPng()Takes a screenshot of the element, encoded as PNG.
TapAsync(CancellationToken)Taps the element with a finger.
ToString()Gets the description of the locator, as C# code (GetByRole("listitem").Filter(HasText = "Ada").First).
TypeAsync(string, CancellationToken)Focuses the element, and types a text with the keyboard, key by key (the text is appended to the value of a field).
UncheckAsync(CancellationToken)Unchecks the check box with a click, when it is checked.
WaitForAsync(LocatorState, TimeSpan?, CancellationToken)Runs the event loop of the page until the locator reaches a state.

And(Locator)

Locator.cs

Gets a locator of the elements that this locator and another locator both find (page.GetByRole("button").And(page.GetByTitle("Subscribe"))).

public Locator And(Locator locator)

Parameters

locator Locator
The other locator, evaluated from the same scope as this locator.

Returns

Locator The locator.

CheckAsync(CancellationToken)

Locator.cs

Checks the check box or the radio button with a click, when it is not checked. An element of a label checks the control of the label.

public Task CheckAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

Exceptions

ElementNotInteractableException
The element is not a check box or a radio button, or the click does not check it.

ClearAsync(CancellationToken)

Locator.cs

Clears the value of the text field, then leaves the field.

public Task ClearAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

ClickAsync(ClickOptions?, CancellationToken)

Locator.cs

Clicks the element at its center (or at ClickOptions.Position), once the locator finds it and it is visible, stable, enabled and not covered by another element.

public Task ClickAsync(ClickOptions? options = null, CancellationToken cancellationToken = default)

Parameters

options ClickOptions?
The options, or null for the default options.
cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

DoubleClickAsync(CancellationToken)

Locator.cs

Double-clicks the element.

public Task DoubleClickAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

DragToAsync(Locator, CancellationToken)

Locator.cs

Drags the element with the mouse, and drops it on the element of another locator (the HTML drag and drop events).

public Task DragToAsync(Locator target, CancellationToken cancellationToken = default)

Parameters

target Locator
The locator of the element where the element is dropped.
cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

FillAsync(string, CancellationToken)

Locator.cs

Replaces the value of the text field with a text typed with the keyboard, then leaves the field (the change event, so @bind updates the value). Waits until the field is visible, enabled and editable. An element of a label fills the control of the label.

public Task FillAsync(string text, CancellationToken cancellationToken = default)

Parameters

text string
The text.
cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

Exceptions

ElementNotInteractableException
The element is not a text field.

Filter(LocatorFilterOptions)

Locator.cs

Gets a locator of the elements of this locator that satisfy conditions.

public Locator Filter(LocatorFilterOptions options)

Parameters

options LocatorFilterOptions
The conditions.

Returns

Locator The locator.

FocusAsync(CancellationToken)

Locator.cs

Focuses the element.

public Task FocusAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

GetAccessibilitySnapshot()

Locator.cs

Gets the accessibility tree of the element, as a YAML snapshot (the format of the ARIA snapshots of Playwright).

public string GetAccessibilitySnapshot()

Returns

string The snapshot.

GetAll()

Locator.cs

Gets a locator for each element that the locator finds now (Nth(0), Nth(1)...).

public IReadOnlyList<Locator> GetAll()

Returns

IReadOnlyList<Locator> The locators.

GetAttribute(string)

Locator.cs

Gets the value of an attribute of the element, or null when it has no such attribute.

public string? GetAttribute(string name)

Parameters

name string
The name of the attribute.

Returns

string? The value, or null.

Exceptions

ElementNotFoundException
The locator finds no element.
StrictModeViolationException
The locator finds more than one element.

GetElement()

Locator.cs

Gets the element that the locator finds now.

public Element GetElement()

Returns

Element The element.

Exceptions

ElementNotFoundException
The locator finds no element.
StrictModeViolationException
The locator finds more than one element.

GetElementOrDefault()

Locator.cs

Gets the element that the locator finds now, or null.

public Element? GetElementOrDefault()

Returns

Element? The element, or null.

Exceptions

StrictModeViolationException
The locator finds more than one element.

GetElements()

Locator.cs

Gets the elements that the locator finds now, in document order.

public IReadOnlyList<Element> GetElements()

Returns

IReadOnlyList<Element> The elements.

GetMarkup(MarkupOptions?)

Locator.cs

Gets the HTML of the element, formatted for snapshots.

public string GetMarkup(MarkupOptions? options = null)

Parameters

options MarkupOptions?
The options, or null for the default options.

Returns

string The HTML.

HoverAsync(CancellationToken)

Locator.cs

Moves the mouse over the element, once it is visible, stable and not covered by another element.

public Task HoverAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

Nth(int)

Locator.cs

Gets a locator of the element at an index of the elements of this locator.

public Locator Nth(int index)

Parameters

index int
The index, starting at 0. A negative index counts from the end (-1 is the last element).

Returns

Locator The locator.

Or(Locator)

Locator.cs

Gets a locator of the elements that this locator or another locator finds, in document order (page.GetByRole("button", "New").Or(page.GetByText("Confirm"))).

public Locator Or(Locator locator)

Parameters

locator Locator
The other locator, evaluated from the same scope as this locator.

Returns

Locator The locator.

PressAsync(string, string[])

Locator.cs

Focuses the element, and presses a key (a character or a key name such as Enter, Tab, ArrowDown) while modifier keys are held.

public Task PressAsync(string key, params string[] modifiers)

Parameters

key string
The key.
modifiers string[]
The modifier keys (Shift, Control, Alt, Meta).

Returns

Task A task completed once the page is idle.

SelectOptionAsync(string[])

Locator.cs

Selects options of the select element by value or by label, and fires the input and change events. Waits until the element is visible and enabled, and until it has all the options.

public Task SelectOptionAsync(params string[] values)

Parameters

values string[]
The values or the labels of the options to select.

Returns

Task A task completed once the page is idle.

SetCheckedAsync(bool, CancellationToken)

Locator.cs

Checks or unchecks the check box with a click, when its state is not isChecked.

public Task SetCheckedAsync(bool isChecked, CancellationToken cancellationToken = default)

Parameters

isChecked bool
The state.
cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

Exceptions

ElementNotInteractableException
The element is not a check box or a radio button, or the click does not change its state.

TakeScreenshotAsPng()

Locator.cs

Takes a screenshot of the element, encoded as PNG.

public byte[] TakeScreenshotAsPng()

Returns

byte[] The PNG image.

TapAsync(CancellationToken)

Locator.cs

Taps the element with a finger.

public Task TapAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

ToString()

Locator.cs

Gets the description of the locator, as C# code (GetByRole("listitem").Filter(HasText = "Ada").First).

public override string ToString()

Returns

string The description.

TypeAsync(string, CancellationToken)

Locator.cs

Focuses the element, and types a text with the keyboard, key by key (the text is appended to the value of a field).

public Task TypeAsync(string text, CancellationToken cancellationToken = default)

Parameters

text string
The text.
cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

UncheckAsync(CancellationToken)

Locator.cs

Unchecks the check box with a click, when it is checked.

public Task UncheckAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the page is idle.

Exceptions

ElementNotInteractableException
The element is not a check box, or the click does not uncheck it.

WaitForAsync(LocatorState, TimeSpan?, CancellationToken)

Locator.cs

Runs the event loop of the page until the locator reaches a state.

net10.0

public Task WaitForAsync(LocatorState state = LocatorState.Visible, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

net11.0

public Task WaitForAsync(LocatorState state = LocatorState.Visible, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

state LocatorState
The state. The default is LocatorState.Visible.
timeout TimeSpan?
The maximum time to wait, or null for TestPage.DefaultTimeout.
cancellationToken CancellationToken
A token to cancel the wait.

Returns

Task A task completed once the locator reaches the state.

Exceptions

TimeoutException
The locator does not reach the state after timeout.
StrictModeViolationException
The locator finds more than one element.