Struct Locator 

pub struct Locator<'a> { /* private fields */ }

A locator for finding elements on a page.

Locators are lightweight handles that store selection criteria. They don’t query the DOM until an action is performed, enabling auto-waiting.

Implementations

impl Locator<'_>

pub async fn click(&self) -> Result<(), LocatorError>

Click the element.

Waits for the element to be visible and enabled, then clicks its center.

Errors

Returns an error if:

• The element is not found within the timeout
• The element is not visible
• The CDP command fails

Panics

Panics if a visible element lacks bounding box coordinates. This should never occur as wait_for_actionable ensures visibility before returning.

pub async fn dblclick(&self) -> Result<(), LocatorError>

Double-click the element.

Errors

Returns an error if the element cannot be clicked.

Panics

Panics if a visible element lacks bounding box coordinates. This should never occur as wait_for_actionable ensures visibility before returning.

pub async fn fill(&self, text: &str) -> Result<(), LocatorError>

Fill the element with text (clears existing content first).

This is for input and textarea elements.

Errors

Returns an error if the element cannot be focused or text cannot be inserted.

pub async fn type_text(&self, text: &str) -> Result<(), LocatorError>

Type text character by character.

Unlike fill, this types each character with keydown/keyup events.

Errors

Returns an error if the element cannot be focused or keys cannot be dispatched.

pub async fn press(&self, key: &str) -> Result<(), LocatorError>

Press a key or key combination.

Examples: “Enter”, “Backspace”, “Control+a”, “Shift+Tab”

Errors

Returns an error if the element cannot be focused or the key cannot be pressed.

pub async fn hover(&self) -> Result<(), LocatorError>

Hover over the element.

Errors

Returns an error if the element cannot be found or the mouse event fails.

Panics

Panics if a visible element lacks bounding box coordinates. This should never occur as wait_for_actionable ensures visibility before returning.

pub async fn focus(&self) -> Result<(), LocatorError>

Focus the element.

Errors

Returns an error if the element cannot be found or focused.

pub async fn clear(&self) -> Result<(), LocatorError>

Clear the element’s content.

Errors

Returns an error if the element cannot be cleared.

pub async fn check(&self) -> Result<(), LocatorError>

Check a checkbox or radio button.

Errors

Returns an error if the element cannot be checked.

pub async fn uncheck(&self) -> Result<(), LocatorError>

Uncheck a checkbox.

Errors

Returns an error if the element cannot be unchecked.

pub async fn select_option(&self, option: &str) -> Result<(), LocatorError>

Select an option in a <select> element by value, label, or index.

Arguments

• option - The option to select. Can be:
  • A string value matching the option’s value attribute
  • A string matching the option’s visible text

Errors

Returns an error if the element is not a select or the option is not found.

Example

// Select by value
page.locator("select#size").select_option("medium").await?;

// Select by visible text
page.locator("select#size").select_option("Medium Size").await?;

pub async fn select_options(&self, options: &[&str]) -> Result<(), LocatorError>

Select multiple options in a <select multiple> element.

Arguments

• options - A slice of option values or labels to select.

Errors

Returns an error if the element is not a multi-select or options are not found.

pub async fn text_content(&self) -> Result<Option<String>, LocatorError>

Get the text content of the element.

Errors

Returns an error if the element cannot be queried.

pub async fn is_visible(&self) -> Result<bool, LocatorError>

Check if the element is visible.

Errors

Returns an error if the element cannot be queried.

pub async fn is_checked(&self) -> Result<bool, LocatorError>

Check if the element is checked (for checkboxes/radios).

Errors

Returns an error if the element cannot be queried.

pub async fn count(&self) -> Result<usize, LocatorError>

Count matching elements.

Errors

Returns an error if the elements cannot be queried.

impl<'a> Locator<'a>

pub fn page(&self) -> &'a Page

Get the page this locator belongs to.

pub fn selector(&self) -> &Selector

Get the selector.

pub fn options(&self) -> &LocatorOptions

Get the options.

pub fn timeout(self, timeout: Duration) -> Self

Set a custom timeout for this locator.

pub fn locator(&self, selector: impl Into<String>) -> Locator<'a>

Create a child locator that further filters elements.

Example

let items = page.locator(".list").locator(".item");

pub fn first(&self) -> Locator<'a>

Select the first matching element.

pub fn last(&self) -> Locator<'a>

Select the last matching element.

pub fn nth(&self, index: i32) -> Locator<'a>

Select the nth matching element (0-indexed).

Trait Implementations

impl<'a> Clone for Locator<'a>

fn clone(&self) -> Locator<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Locator<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<RoleLocatorBuilder<'a>> for Locator<'a>

fn from(builder: RoleLocatorBuilder<'a>) -> Self

Converts to this type from the input type.