Locator

Namespace: E2E

public sealed class Locator

A query that resolves against a fresh observation every time it is used.

Inheritance: object

View source

Methods

AllAsync(CancellationToken)

public Task<IReadOnlyList<Locator>> AllAsync(CancellationToken cancellationToken = default)

One Nth(int) locator per current match, without waiting. Empty when nothing matches.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<IReadOnlyList<Locator>>

View source

AllTextContentsAsync(CancellationToken)

public Task<IReadOnlyList<string>> AllTextContentsAsync(CancellationToken cancellationToken = default)

Reads the whitespace-normalized rendered text of every current match, without waiting. Empty when nothing matches. Fails with POLICY_DENIED when any match is a secure field.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<IReadOnlyList<string>>

View source

BoundingBoxAsync(CancellationToken)

public Task<BoundingBox?> BoundingBoxAsync(CancellationToken cancellationToken = default)

Waits up to the action timeout for one match, then reads its viewport-relative box once, or null when the node lays out no box (display: none on it or an ancestor, or any display: contents element) or the engine does not report one.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<BoundingBox>

View source

CheckAsync(ActionOptions?, CancellationToken)

public Task CheckAsync(ActionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

ClearAsync(ActionOptions?, CancellationToken)

public Task ClearAsync(ActionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

ClickAsync(ActionOptions?, CancellationToken)

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

Alias of CancellationToken).

Parameters

Name	Type	Description
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

CountAsync(CancellationToken)

public Task<int> CountAsync(CancellationToken cancellationToken = default)

Counts current matches without waiting.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<int>

View source

DblClickAsync(ActionOptions?, CancellationToken)

public Task DblClickAsync(ActionOptions? options = null, CancellationToken cancellationToken = default)

Alias of CancellationToken).

Parameters

Name	Type	Description
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

DoubleTapAsync(ActionOptions?, CancellationToken)

public Task DoubleTapAsync(ActionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

FillAsync(Secret, ActionOptions?, CancellationToken)

public Task FillAsync(Secret value, ActionOptions? options = null, CancellationToken cancellationToken = default)

Fills a secret. The engine marks the value sensitive and never reports it.

Parameters

Name	Type	Description
`value`	Secret
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

FillAsync(string, ActionOptions?, CancellationToken)

public Task FillAsync(string value, ActionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`value`	string
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

Filter(Locator)

public Locator Filter(Locator has)

Keeps the matches with a descendant that <code class=“paramref”>has</code> matches. <code class=“paramref”>has</code> resolves inside each match.

Parameters

Name	Type	Description
`has`	Locator

Returns: Locator

View source

Filter(TextMatch)

public Locator Filter(TextMatch hasText)

Keeps the matches whose own or descendants’ name, text, or value contains <code class=“paramref”>hasText</code>, ignoring case.

Parameters

Name	Type	Description
`hasText`	TextMatch

Returns: Locator

View source

First()

public Locator First()

Returns: Locator

View source

FocusAsync(ActionOptions?, CancellationToken)

public Task FocusAsync(ActionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

GetAttributeAsync(string, CancellationToken)

public Task<string?> GetAttributeAsync(string name, CancellationToken cancellationToken = default)

Waits up to the action timeout for one match, then reads one platform attribute once, or null when the node does not have it. Fails with POLICY_DENIED on a secure field.

Parameters

Name	Type	Description
`name`	string
`cancellationToken`	CancellationToken

Returns: Task<string>

View source

GetByDisplayValue(TextMatch, TextMatchOptions)

public Locator GetByDisplayValue(TextMatch value, TextMatchOptions options)

Creates a displayed-value query among this locator’s descendants.

Parameters

Name	Type	Description
`value`	TextMatch
`options`	TextMatchOptions

Returns: Locator

View source

GetByDisplayValue(TextMatch, bool)

public Locator GetByDisplayValue(TextMatch value, bool exact = true)

Creates a displayed-value query among this locator’s descendants.

Parameters

Name	Type	Description
`value`	TextMatch
`exact`	bool

Returns: Locator

View source

GetByLabel(TextMatch, TextMatchOptions)

public Locator GetByLabel(TextMatch label, TextMatchOptions options)

Creates a label query among this locator’s descendants.

Parameters

Name	Type	Description
`label`	TextMatch
`options`	TextMatchOptions

Returns: Locator

View source

GetByLabel(TextMatch, bool)

public Locator GetByLabel(TextMatch label, bool exact = true)

Creates a label query among this locator’s descendants.

Parameters

Name	Type	Description
`label`	TextMatch
`exact`	bool

Returns: Locator

View source

GetByPlaceholder(TextMatch, TextMatchOptions)

public Locator GetByPlaceholder(TextMatch placeholder, TextMatchOptions options)

Creates a placeholder query among this locator’s descendants.

Parameters

Name	Type	Description
`placeholder`	TextMatch
`options`	TextMatchOptions

Returns: Locator

View source

GetByPlaceholder(TextMatch, bool)

public Locator GetByPlaceholder(TextMatch placeholder, bool exact = true)

Creates a placeholder query among this locator’s descendants.

Parameters

Name	Type	Description
`placeholder`	TextMatch
`exact`	bool

Returns: Locator

View source

GetByRole(string, RoleOptions)

public Locator GetByRole(string role, RoleOptions options)

Creates a role query among this locator’s descendants.

Parameters

Name	Type	Description
`role`	string
`options`	RoleOptions

Returns: Locator

View source

GetByRole(string, TextMatch, RoleOptions)

public Locator GetByRole(string role, TextMatch name, RoleOptions options)

Creates a role query among this locator’s descendants.

Parameters

Name	Type	Description
`role`	string
`name`	TextMatch
`options`	RoleOptions

Returns: Locator

View source

GetByRole(string, TextMatch?, bool)

public Locator GetByRole(string role, TextMatch? name = null, bool exact = true)

Creates a role query among this locator’s descendants.

Parameters

Name	Type	Description
`role`	string
`name`	TextMatch
`exact`	bool

Returns: Locator

View source

GetByTestId(TextMatch)

public Locator GetByTestId(TextMatch testId)

Creates a test-id query among this locator’s descendants.

Parameters

Name	Type	Description
`testId`	TextMatch

Returns: Locator

View source

GetByTestId(TextMatch, TextMatchOptions)

public Locator GetByTestId(TextMatch testId, TextMatchOptions options)

Creates a test-id query among this locator’s descendants.

Parameters

Name	Type	Description
`testId`	TextMatch
`options`	TextMatchOptions

Returns: Locator

View source

GetByText(TextMatch, TextMatchOptions)

public Locator GetByText(TextMatch text, TextMatchOptions options)

Creates a visible-text query among this locator’s descendants.

Parameters

Name	Type	Description
`text`	TextMatch
`options`	TextMatchOptions

Returns: Locator

View source

GetByText(TextMatch, bool)

public Locator GetByText(TextMatch text, bool exact = true)

Creates a visible-text query among this locator’s descendants.

Parameters

Name	Type	Description
`text`	TextMatch
`exact`	bool

Returns: Locator

View source

InputValueAsync(CancellationToken)

public Task<string> InputValueAsync(CancellationToken cancellationToken = default)

Waits up to the action timeout for one match, then reads an input value once, the empty string when the node has none. Does not retry for a value and does not verify an earlier act. A checkbox or radio reads its value attribute, on when it has none, whatever its checked state. Fails with POLICY_DENIED on a secure field.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<string>

View source

IsCheckedAsync(CancellationToken)

public Task<bool> IsCheckedAsync(CancellationToken cancellationToken = default)

Waits up to the action timeout for one match, then reads its checked state once.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<bool>

View source

IsDisabledAsync(CancellationToken)

public Task<bool> IsDisabledAsync(CancellationToken cancellationToken = default)

Waits up to the action timeout for one match, then reads its disabled state once, the negation of IsEnabledAsync(CancellationToken).

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<bool>

View source

IsEnabledAsync(CancellationToken)

public Task<bool> IsEnabledAsync(CancellationToken cancellationToken = default)

Waits up to the action timeout for one match, then reads its enabled state once.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<bool>

View source

IsHiddenAsync(CancellationToken)

public Task<bool> IsHiddenAsync(CancellationToken cancellationToken = default)

Reads current hidden or absent state, the negation of IsVisibleAsync(CancellationToken).

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<bool>

View source

IsVisibleAsync(CancellationToken)

public Task<bool> IsVisibleAsync(CancellationToken cancellationToken = default)

Reads current visibility: true when exactly one visible node matches. More than one match fails.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<bool>

View source

Last()

public Locator Last()

Returns: Locator

View source

Nth(int)

public Locator Nth(int index)

Parameters

Name	Type	Description
`index`	int

Returns: Locator

View source

Or(Locator)

public Locator Or(Locator other)

Matches either locator, preserving document order without duplicate nodes. a.Or(b) stays strict: when both match different nodes, an action fails with STRICT_MODE, so add First() if either will do. Both locators must come from the same screen and attempt. Upstream’s locator.or.

Parameters

Name	Type	Description
`other`	Locator

Returns: Locator

Exceptions

Type	Condition
TestException	`INVALID_LOCATOR`: <code class=“paramref”>other</code> belongs to another screen or attempt.

View source

PressAsync(string, ActionOptions?, CancellationToken)

public Task PressAsync(string key, ActionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`key`	string
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

PressSequentiallyAsync(string, PressSequentiallyOptions?, CancellationToken)

public Task PressSequentiallyAsync(string text, PressSequentiallyOptions? options = null, CancellationToken cancellationToken = default)

Focuses the input and types <code class=“paramref”>text</code> one character at a time, so the app receives key events. Delay waits between characters.

Parameters

Name	Type	Description
`text`	string
`options`	PressSequentiallyOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

ScrollIntoViewAsync(ActionOptions?, CancellationToken)

public Task ScrollIntoViewAsync(ActionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

ScrollUntilVisibleAsync(Locator, ScrollUntilVisibleOptions?, CancellationToken)

public Task ScrollUntilVisibleAsync(Locator target, ScrollUntilVisibleOptions? options = null, CancellationToken cancellationToken = default)

Scrolls this locator’s node until <code class=“paramref”>target</code> is visible: the node itself swipes, so a scroll container pages without the pointer having to hover it first. Both locators must come from the same screen. Upstream’s locator.scrollUntilVisible.

Parameters

Name	Type	Description
`target`	Locator
`options`	ScrollUntilVisibleOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

SelectOptionAsync(string, ActionOptions?, CancellationToken)

public Task SelectOptionAsync(string value, ActionOptions? options = null, CancellationToken cancellationToken = default)

Selects the option whose value or label is <code class=“paramref”>value</code>.

Parameters

Name	Type	Description
`value`	string
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

TapAsync(ActionOptions?, CancellationToken)

public Task TapAsync(ActionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

TextContentAsync(CancellationToken)

public Task<string?> TextContentAsync(CancellationToken cancellationToken = default)

Waits up to the action timeout for one match, then reads whitespace-normalized text once: the node’s rendered text (innerText on the web), not its label. Null when the node has no text. Does not retry for a value and does not verify an earlier act. Fails with POLICY_DENIED on a secure field.

Parameters

Name	Type	Description
`cancellationToken`	CancellationToken

Returns: Task<string>

View source

UncheckAsync(ActionOptions?, CancellationToken)

public Task UncheckAsync(ActionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Name	Type	Description
`options`	ActionOptions
`cancellationToken`	CancellationToken

Returns: Task

View source

WaitForAsync(LocatorWaitForOptions?, CancellationToken)

public Task WaitForAsync(LocatorWaitForOptions? options = null, CancellationToken cancellationToken = default)

Waits for State, Visible by default: Attached for one match, visible or not; Detached for none; Hidden for none or a hidden one. The timeout defaults to the action timeout. More than one match fails at once. Does not verify an earlier act.

Parameters

Name	Type	Description
`options`	LocatorWaitForOptions
`cancellationToken`	CancellationToken

Returns: Task

View source