Locator

Namespace: PuppeteerSharp.Locators

public abstract class Locator

Locators describe a strategy of locating elements and performing an action on them. If the action fails because the element is not ready for the action, the whole operation is retried. Various preconditions for a successful action are checked automatically.

Inheritance: object

Properties

EnsureElementIsInTheViewport

protected bool EnsureElementIsInTheViewport { get; set; }

Gets or sets a value indicating whether to ensure the element is in the viewport.

Value: bool

Timeout

protected int Timeout { get; set; }

Gets or sets the timeout in milliseconds.

Value: int

Visibility

protected VisibilityOption? Visibility { get; set; }

Gets or sets the visibility option.

Value: VisibilityOption?

WaitForEnabled

protected bool WaitForEnabled { get; set; }

Gets or sets a value indicating whether to wait for the element to be enabled.

Value: bool

WaitForStableBoundingBox

protected bool WaitForStableBoundingBox { get; set; }

Gets or sets a value indicating whether to wait for a stable bounding box.

Value: bool

Methods

ClickAsync(LocatorClickOptions)

public Task ClickAsync(LocatorClickOptions options = null)

Clicks the located element.

Parameters

Name	Type	Description
`options`	LocatorClickOptions	Optional click options.

Returns: Task — A task that completes when the click is performed.

FillAsync(string, LocatorActionOptions)

public Task FillAsync(string value, LocatorActionOptions options = null)

Fills the located element with the provided value.

Parameters

Name	Type	Description
`value`	string	The value to fill.
`options`	LocatorActionOptions	Optional action options.

Returns: Task — A task that completes when the fill is performed.

Filter(string)

public Locator Filter(string predicate)

Creates a new locator that filters elements using the provided predicate. If the predicate does not match, the locator will retry.

Parameters

Name	Type	Description
`predicate`	string	A JavaScript function expression that takes an element and returns a boolean.

Returns: Locator — A new locator that filters based on the predicate.

`FilterHandle(Func<IJSHandle, Task<bool>>)`

public Locator FilterHandle(Func<IJSHandle, Task<bool>> predicate)

Creates a new locator that filters elements using a handle-based predicate. If the predicate does not match, the locator will retry.

Parameters

Name	Type	Description
`predicate`	Func<IJSHandle, Task<bool>>	A function that takes a handle and returns whether it matches.

Returns: Locator — A new locator that filters based on the predicate.

HoverAsync(LocatorActionOptions)

public Task HoverAsync(LocatorActionOptions options = null)

Hovers over the located element.

Parameters

Name	Type	Description
`options`	LocatorActionOptions	Optional action options.

Returns: Task — A task that completes when the hover is performed.

Map(string)

public Locator Map(string mapper)

Maps the locator using the provided mapper.

Parameters

Name	Type	Description
`mapper`	string	A JavaScript function expression that transforms the element.

Returns: Locator — A new locator that maps the element.

`MapHandle(Func<IJSHandle, Task<IJSHandle>>)`

public Locator MapHandle(Func<IJSHandle, Task<IJSHandle>> mapper)

Maps the locator using a handle-based mapper.

Parameters

Name	Type	Description
`mapper`	Func<IJSHandle, Task<IJSHandle>>	A function that takes a handle and returns a new handle.

Returns: Locator — A new locator that maps the element.

Race(params Locator[])

public static Locator Race(params Locator[] locators)

Creates a new locator that races multiple locators, returning the first one to resolve.

Parameters

Name	Type	Description
`locators`	`Locator\[\]`	The locators to race.

Returns: Locator — A new locator that resolves to the first matching locator’s result.

ScrollAsync(LocatorScrollOptions)

public Task ScrollAsync(LocatorScrollOptions options = null)

Scrolls the located element.

Parameters

Name	Type	Description
`options`	LocatorScrollOptions	Optional scroll options.

Returns: Task — A task that completes when the scroll is performed.

SetEnsureElementIsInTheViewport(bool)

public Locator SetEnsureElementIsInTheViewport(bool value)

Sets whether to ensure the element is scrolled into the viewport.

Parameters

Name	Type	Description
`value`	bool	Whether to ensure the element is in the viewport.

Returns: Locator — The locator instance for chaining.

SetTimeout(int)

public Locator SetTimeout(int timeout)

Sets the timeout for the locator.

Parameters

Name	Type	Description
`timeout`	int	Timeout in milliseconds.

Returns: Locator — The locator instance for chaining.

SetVisibility(VisibilityOption?)

public Locator SetVisibility(VisibilityOption? visibility)

Sets the visibility option for the locator.

Parameters

Name	Type	Description
`visibility`	`VisibilityOption?`	The visibility option.

Returns: Locator — The locator instance for chaining.

SetWaitForEnabled(bool)

public Locator SetWaitForEnabled(bool value)

Sets whether to wait for the element to be enabled before acting.

Parameters

Name	Type	Description
`value`	bool	Whether to wait for enabled.

Returns: Locator — The locator instance for chaining.

SetWaitForStableBoundingBox(bool)

public Locator SetWaitForStableBoundingBox(bool value)

Sets whether to wait for a stable bounding box before acting.

Parameters

Name	Type	Description
`value`	bool	Whether to wait for a stable bounding box.

Returns: Locator — The locator instance for chaining.

WaitAsync(LocatorActionOptions)

public Task WaitAsync(LocatorActionOptions options = null)

Waits for the locator to locate an element.

Parameters

Name	Type	Description
`options`	LocatorActionOptions	Optional action options.

Returns: Task — A task that completes when the element is located.

`WaitAsync<T>(LocatorActionOptions)`

public Task<T> WaitAsync<T>(LocatorActionOptions options = null)

Waits for the locator to get a value from the page. Note this requires the value to be JSON-serializable.

Type parameters

Name	Description
`T`	The type of the return value.

Parameters

Name	Type	Description
`options`	LocatorActionOptions	Optional action options.

Returns: Task<T> — A task that resolves to the serialized value.

WaitHandleAsync(LocatorActionOptions)

public Task<IJSHandle> WaitHandleAsync(LocatorActionOptions options = null)

Waits for the locator to get a handle from the page.

Parameters

Name	Type	Description
`options`	LocatorActionOptions	Optional action options.

Returns: Task<IJSHandle> — A task that resolves to a handle for the located element.

Made with love by Dario Kondratiuk