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
LocatorScopeLocator
Properties
| Name | Description |
|---|---|
| Count | Gets the number of elements that the locator finds now. |
| First | Gets a locator of the first element of this locator. |
| InputValue | Gets the value of the field (input, textarea or select, or the control of a label). |
| IsChecked | Gets whether the check box, the radio button, or the element with a checked state is checked. |
| IsEditable | Gets whether the field is editable: enabled and not read-only. |
| IsEnabled | Gets whether the element is enabled: not a disabled form control, and no aria-disabled="true". |
| IsVisible | Gets whether the locator finds a visible element now: a non-empty box, and not visibility: hidden. False when it finds no element. |
| Last | Gets a locator of the last element of this locator. |
| Page | Gets the page of the locator. |
| TextContent | Gets the text content of the element. |
Count
Locator.csFirst
Locator.csInputValue
Locator.csGets the value of the field (input, textarea or select, or the control of a label).
public string InputValue { get; }Property value
Exceptions
ElementNotFoundException- The locator finds no element.
StrictModeViolationException- The locator finds more than one element.
InvalidOperationException- The element is not a field.
IsChecked
Locator.csGets whether the check box, the radio button, or the element with a checked state is checked.
public bool IsChecked { get; }Property value
Exceptions
ElementNotFoundException- The locator finds no element.
StrictModeViolationException- The locator finds more than one element.
InvalidOperationException- The element has no checked state.
IsEditable
Locator.csGets whether the field is editable: enabled and not read-only.
public bool IsEditable { get; }Property value
Exceptions
ElementNotFoundException- The locator finds no element.
StrictModeViolationException- The locator finds more than one element.
InvalidOperationException- The element is not a field.
IsEnabled
Locator.csGets whether the element is enabled: not a disabled form control, and no aria-disabled="true".
public bool IsEnabled { get; }Property value
Exceptions
ElementNotFoundException- The locator finds no element.
StrictModeViolationException- The locator finds more than one element.
IsVisible
Locator.csGets 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; }Last
Locator.csPage
Locator.csTextContent
Locator.csGets the text content of the element.
public string TextContent { get; }Property value
Exceptions
ElementNotFoundException- The locator finds no element.
StrictModeViolationException- The locator finds more than one element.
Methods
| Name | Description |
|---|---|
| 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.csCheckAsync(CancellationToken)
Locator.csChecks 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
cancellationTokenCancellationToken- 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.csClears the value of the text field, then leaves the field.
public Task ClearAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A token to cancel the wait.
Returns
Task A task completed once the page is idle.
ClickAsync(ClickOptions?, CancellationToken)
Locator.csClicks 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
optionsClickOptions?- The options, or null for the default options.
cancellationTokenCancellationToken- A token to cancel the wait.
Returns
Task A task completed once the page is idle.
DoubleClickAsync(CancellationToken)
Locator.csDouble-clicks the element.
public Task DoubleClickAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A token to cancel the wait.
Returns
Task A task completed once the page is idle.
DragToAsync(Locator, CancellationToken)
Locator.csDrags 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
targetLocator- The locator of the element where the element is dropped.
cancellationTokenCancellationToken- A token to cancel the wait.
Returns
Task A task completed once the page is idle.
FillAsync(string, CancellationToken)
Locator.csReplaces 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
textstring- The text.
cancellationTokenCancellationToken- 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.csGets a locator of the elements of this locator that satisfy conditions.
public Locator Filter(LocatorFilterOptions options)FocusAsync(CancellationToken)
Locator.csFocuses the element.
public Task FocusAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A token to cancel the wait.
Returns
Task A task completed once the page is idle.
GetAccessibilitySnapshot()
Locator.csGetAll()
Locator.csGets 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.csGets the value of an attribute of the element, or null when it has no such attribute.
Parameters
namestring- 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.csGets 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.csGets 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.csGets the elements that the locator finds now, in document order.
public IReadOnlyList<Element> GetElements()Returns
IReadOnlyList<Element> The elements.
GetMarkup(MarkupOptions?)
Locator.csGets the HTML of the element, formatted for snapshots.
public string GetMarkup(MarkupOptions? options = null)Parameters
optionsMarkupOptions?- The options, or null for the default options.
Returns
string The HTML.
HoverAsync(CancellationToken)
Locator.csMoves the mouse over the element, once it is visible, stable and not covered by another element.
public Task HoverAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A token to cancel the wait.
Returns
Task A task completed once the page is idle.
Nth(int)
Locator.csOr(Locator)
Locator.csGets 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[])
Locator.csFocuses the element, and presses a key (a character or a key name such as Enter, Tab, ArrowDown) while modifier keys are held.
SelectOptionAsync(string[])
Locator.csSelects 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.
Parameters
valuesstring[]- The values or the labels of the options to select.
Returns
Task A task completed once the page is idle.
SetCheckedAsync(bool, CancellationToken)
Locator.csChecks or unchecks the check box with a click, when its state is not isChecked.
public Task SetCheckedAsync(bool isChecked, CancellationToken cancellationToken = default)Parameters
isCheckedbool- The state.
cancellationTokenCancellationToken- 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.csTakes a screenshot of the element, encoded as PNG.
public byte[] TakeScreenshotAsPng()Returns
byte[] The PNG image.
TapAsync(CancellationToken)
Locator.csTaps the element with a finger.
public Task TapAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- A token to cancel the wait.
Returns
Task A task completed once the page is idle.
ToString()
Locator.csTypeAsync(string, CancellationToken)
Locator.csFocuses 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
textstring- The text.
cancellationTokenCancellationToken- A token to cancel the wait.
Returns
Task A task completed once the page is idle.
UncheckAsync(CancellationToken)
Locator.csUnchecks the check box with a click, when it is checked.
public Task UncheckAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken- 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.csRuns 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
stateLocatorState- The state. The default is
LocatorState.Visible. timeoutTimeSpan?- The maximum time to wait, or null for
TestPage.DefaultTimeout. cancellationTokenCancellationToken- 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.