playwright_rs/protocol/

locator.rs

//! Locator — lazy element selector with auto-waiting.
//!
//! Locators are the central piece of Playwright's auto-waiting and retry
//! semantics. They represent *a way to find element(s)* at any given
//! moment — not an element handle. Each action re-queries.
//!
//! Key characteristics:
//! - Lazy: don't execute until an action is performed
//! - Retryable: auto-wait for elements to match actionability checks
//! - Chainable: can create sub-locators via `first()`, `last()`,
//!   `nth()`, `locator()`, `filter()`
//!
//! Architecture:
//! - Locator is **not** a ChannelOwner; it's a lightweight wrapper
//! - Stores a selector string + reference to its Frame + parent Page
//! - Delegates all operations to Frame with `strict=true`
//!
//! # Example
//!
//! ```no_run
//! use playwright_rs::Playwright;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let pw = Playwright::launch().await?;
//!     let browser = pw.chromium().launch().await?;
//!     let page = browser.new_page().await?;
//!
//!     page.set_content(
//!         r#"<button data-testid="submit" role="button">Submit</button>
//!            <ul><li class="item">A</li><li class="item">B</li></ul>"#,
//!         None,
//!     ).await?;
//!
//!     // Basic locator + action
//!     page.locator("button").click(None).await?;
//!
//!     // Robust locator from a fragile starting point: normalize() asks
//!     // Playwright for the canonical equivalent (test-id / role / text).
//!     let stable = page
//!         .locator("body button:nth-child(1)")
//!         .normalize()
//!         .await?;
//!     assert!(!stable.selector().is_empty());
//!
//!     // Chain primitives: filter, count, nth
//!     let items = page.locator(".item");
//!     assert_eq!(items.count().await?, 2);
//!     items.nth(0).click(None).await?;
//!
//!     browser.close().await?;
//!     Ok(())
//! }
//! ```
//!
//! See: <https://playwright.dev/docs/api/class-locator>

use crate::error::Result;
use crate::protocol::Frame;
use serde::Deserialize;

/// Trait for action option structs that have an optional timeout field.
/// Used by `Locator::with_timeout` to inject the page's default timeout.
pub(crate) trait HasTimeout {
    fn timeout_ref(&self) -> &Option<f64>;
    fn timeout_ref_mut(&mut self) -> &mut Option<f64>;
}

macro_rules! impl_has_timeout {
    ($($ty:ty),+ $(,)?) => {
        $(impl HasTimeout for $ty {
            fn timeout_ref(&self) -> &Option<f64> { &self.timeout }
            fn timeout_ref_mut(&mut self) -> &mut Option<f64> { &mut self.timeout }
        })+
    };
}

impl_has_timeout!(
    crate::protocol::WaitForFunctionOptions,
    crate::protocol::ClickOptions,
    crate::protocol::FillOptions,
    crate::protocol::PressOptions,
    crate::protocol::CheckOptions,
    crate::protocol::HoverOptions,
    crate::protocol::SelectOptions,
    crate::protocol::ScreenshotOptions,
    crate::protocol::TapOptions,
    crate::protocol::DragToOptions,
    crate::protocol::DropOptions,
    crate::protocol::WaitForOptions,
);
use std::sync::Arc;

/// The bounding box of an element in pixels.
///
/// All values are measured relative to the top-left corner of the page.
///
/// See: <https://playwright.dev/docs/api/class-locator#locator-bounding-box>
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[non_exhaustive]
pub struct BoundingBox {
    /// The x coordinate of the top-left corner of the element in pixels.
    pub x: f64,
    /// The y coordinate of the top-left corner of the element in pixels.
    pub y: f64,
    /// The width of the element in pixels.
    pub width: f64,
    /// The height of the element in pixels.
    pub height: f64,
}

/// Escapes text for use in Playwright's internal selector engine.
///
/// JSON-stringifies the text and appends `i` (case-insensitive) or `s` (strict/exact).
/// Matches the `escapeForTextSelector`/`escapeForAttributeSelector` in Playwright TypeScript.
/// `s` as a JSON string literal, the quoting the selector engines read.
fn json_quote(s: &str) -> String {
    // Serializing a `str` cannot fail: it has no map keys or non-finite
    // numbers to reject.
    serde_json::to_string(s).expect("a str always serializes")
}

fn escape_for_selector(text: &str, exact: bool) -> String {
    let suffix = if exact { "s" } else { "i" };
    let escaped = json_quote(text);
    format!("{}{}", escaped, suffix)
}

/// Builds the internal selector string for `get_by_text`.
///
/// - `exact=false` → `internal:text="text"i` (case-insensitive substring)
/// - `exact=true` → `internal:text="text"s` (case-sensitive exact)
pub(crate) fn get_by_text_selector(text: &str, exact: bool) -> String {
    format!("internal:text={}", escape_for_selector(text, exact))
}

/// Builds the internal selector string for `get_by_label`.
///
/// - `exact=false` → `internal:label="text"i`
/// - `exact=true` → `internal:label="text"s`
pub(crate) fn get_by_label_selector(text: &str, exact: bool) -> String {
    format!("internal:label={}", escape_for_selector(text, exact))
}

/// Builds the internal selector string for `get_by_placeholder`.
///
/// - `exact=false` → `internal:attr=[placeholder="text"i]`
/// - `exact=true` → `internal:attr=[placeholder="text"s]`
pub(crate) fn get_by_placeholder_selector(text: &str, exact: bool) -> String {
    format!(
        "internal:attr=[placeholder={}]",
        escape_for_selector(text, exact)
    )
}

/// Builds the internal selector string for `get_by_alt_text`.
///
/// - `exact=false` → `internal:attr=[alt="text"i]`
/// - `exact=true` → `internal:attr=[alt="text"s]`
pub(crate) fn get_by_alt_text_selector(text: &str, exact: bool) -> String {
    format!("internal:attr=[alt={}]", escape_for_selector(text, exact))
}

/// Builds the internal selector string for `get_by_title`.
///
/// - `exact=false` → `internal:attr=[title="text"i]`
/// - `exact=true` → `internal:attr=[title="text"s]`
pub(crate) fn get_by_title_selector(text: &str, exact: bool) -> String {
    format!("internal:attr=[title={}]", escape_for_selector(text, exact))
}

/// Builds the internal selector string for `get_by_test_id`.
///
/// Uses `data-testid` attribute by default (matching Playwright's default).
/// Always uses exact matching (`s` suffix).
pub(crate) fn get_by_test_id_selector(test_id: &str) -> String {
    get_by_test_id_selector_with_attr(test_id, "data-testid")
}

/// Builds the internal selector string for `get_by_test_id` with a custom attribute.
///
/// Used when `playwright.selectors().set_test_id_attribute()` has been called.
pub(crate) fn get_by_test_id_selector_with_attr(test_id: &str, attribute: &str) -> String {
    format!(
        "internal:testid=[{}={}]",
        attribute,
        escape_for_selector(test_id, true)
    )
}

/// Escapes text for use in Playwright's attribute role selector.
///
/// Unlike `escape_for_selector` (which uses JSON encoding), this only escapes
/// backslashes and double quotes, matching Playwright's `escapeForAttributeSelector`.
fn escape_for_attribute_selector(text: &str, exact: bool) -> String {
    let suffix = if exact { "s" } else { "i" };
    let escaped = text.replace('\\', "\\\\").replace('"', "\\\"");
    format!("\"{}\"{}", escaped, suffix)
}

/// Builds the internal selector string for `get_by_role`.
///
/// Format: `internal:role=<role>[prop1=val1][prop2=val2]...`
///
/// Properties are appended in Playwright's required order:
/// checked, disabled, selected, expanded, include-hidden, level, name, pressed.
pub(crate) fn get_by_role_selector(role: AriaRole, options: Option<GetByRoleOptions>) -> String {
    let mut selector = format!("internal:role={}", role.as_str());

    if let Some(opts) = options {
        if let Some(checked) = opts.checked {
            selector.push_str(&format!("[checked={}]", checked));
        }
        if let Some(disabled) = opts.disabled {
            selector.push_str(&format!("[disabled={}]", disabled));
        }
        if let Some(selected) = opts.selected {
            selector.push_str(&format!("[selected={}]", selected));
        }
        if let Some(expanded) = opts.expanded {
            selector.push_str(&format!("[expanded={}]", expanded));
        }
        if let Some(include_hidden) = opts.include_hidden {
            selector.push_str(&format!("[include-hidden={}]", include_hidden));
        }
        if let Some(level) = opts.level {
            selector.push_str(&format!("[level={}]", level));
        }
        if let Some(name) = &opts.name {
            let exact = opts.exact.unwrap_or(false);
            selector.push_str(&format!(
                "[name={}]",
                escape_for_attribute_selector(name, exact)
            ));
        }
        if let Some(description) = &opts.description {
            let exact = opts.exact.unwrap_or(false);
            selector.push_str(&format!(
                "[description={}]",
                escape_for_attribute_selector(description, exact)
            ));
        }
        if let Some(pressed) = opts.pressed {
            selector.push_str(&format!("[pressed={}]", pressed));
        }
    }

    selector
}

/// ARIA roles for `get_by_role()` locator.
///
/// Represents WAI-ARIA roles used to locate elements by their accessibility role.
/// Matches Playwright's `AriaRole` enum across all language bindings.
///
/// See: <https://playwright.dev/docs/api/class-page#page-get-by-role>
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum AriaRole {
    Alert,
    Alertdialog,
    Application,
    Article,
    Banner,
    Blockquote,
    Button,
    Caption,
    Cell,
    Checkbox,
    Code,
    Columnheader,
    Combobox,
    Complementary,
    Contentinfo,
    Definition,
    Deletion,
    Dialog,
    Directory,
    Document,
    Emphasis,
    Feed,
    Figure,
    Form,
    Generic,
    Grid,
    Gridcell,
    Group,
    Heading,
    Img,
    Insertion,
    Link,
    List,
    Listbox,
    Listitem,
    Log,
    Main,
    Marquee,
    Math,
    Meter,
    Menu,
    Menubar,
    Menuitem,
    Menuitemcheckbox,
    Menuitemradio,
    Navigation,
    None,
    Note,
    Option,
    Paragraph,
    Presentation,
    Progressbar,
    Radio,
    Radiogroup,
    Region,
    Row,
    Rowgroup,
    Rowheader,
    Scrollbar,
    Search,
    Searchbox,
    Separator,
    Slider,
    Spinbutton,
    Status,
    Strong,
    Subscript,
    Superscript,
    Switch,
    Tab,
    Table,
    Tablist,
    Tabpanel,
    Term,
    Textbox,
    Time,
    Timer,
    Toolbar,
    Tooltip,
    Tree,
    Treegrid,
    Treeitem,
}

impl AriaRole {
    /// Returns the lowercase string representation used in selectors.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Alert => "alert",
            Self::Alertdialog => "alertdialog",
            Self::Application => "application",
            Self::Article => "article",
            Self::Banner => "banner",
            Self::Blockquote => "blockquote",
            Self::Button => "button",
            Self::Caption => "caption",
            Self::Cell => "cell",
            Self::Checkbox => "checkbox",
            Self::Code => "code",
            Self::Columnheader => "columnheader",
            Self::Combobox => "combobox",
            Self::Complementary => "complementary",
            Self::Contentinfo => "contentinfo",
            Self::Definition => "definition",
            Self::Deletion => "deletion",
            Self::Dialog => "dialog",
            Self::Directory => "directory",
            Self::Document => "document",
            Self::Emphasis => "emphasis",
            Self::Feed => "feed",
            Self::Figure => "figure",
            Self::Form => "form",
            Self::Generic => "generic",
            Self::Grid => "grid",
            Self::Gridcell => "gridcell",
            Self::Group => "group",
            Self::Heading => "heading",
            Self::Img => "img",
            Self::Insertion => "insertion",
            Self::Link => "link",
            Self::List => "list",
            Self::Listbox => "listbox",
            Self::Listitem => "listitem",
            Self::Log => "log",
            Self::Main => "main",
            Self::Marquee => "marquee",
            Self::Math => "math",
            Self::Meter => "meter",
            Self::Menu => "menu",
            Self::Menubar => "menubar",
            Self::Menuitem => "menuitem",
            Self::Menuitemcheckbox => "menuitemcheckbox",
            Self::Menuitemradio => "menuitemradio",
            Self::Navigation => "navigation",
            Self::None => "none",
            Self::Note => "note",
            Self::Option => "option",
            Self::Paragraph => "paragraph",
            Self::Presentation => "presentation",
            Self::Progressbar => "progressbar",
            Self::Radio => "radio",
            Self::Radiogroup => "radiogroup",
            Self::Region => "region",
            Self::Row => "row",
            Self::Rowgroup => "rowgroup",
            Self::Rowheader => "rowheader",
            Self::Scrollbar => "scrollbar",
            Self::Search => "search",
            Self::Searchbox => "searchbox",
            Self::Separator => "separator",
            Self::Slider => "slider",
            Self::Spinbutton => "spinbutton",
            Self::Status => "status",
            Self::Strong => "strong",
            Self::Subscript => "subscript",
            Self::Superscript => "superscript",
            Self::Switch => "switch",
            Self::Tab => "tab",
            Self::Table => "table",
            Self::Tablist => "tablist",
            Self::Tabpanel => "tabpanel",
            Self::Term => "term",
            Self::Textbox => "textbox",
            Self::Time => "time",
            Self::Timer => "timer",
            Self::Toolbar => "toolbar",
            Self::Tooltip => "tooltip",
            Self::Tree => "tree",
            Self::Treegrid => "treegrid",
            Self::Treeitem => "treeitem",
        }
    }
}

/// Options for `get_by_role()` locator.
///
/// All fields are optional. When not specified, the property is not included
/// in the role selector, meaning it matches any value.
///
/// See: <https://playwright.dev/docs/api/class-page#page-get-by-role>
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct GetByRoleOptions {
    /// Whether the element is checked (for checkboxes, radio buttons).
    pub checked: Option<bool>,
    /// Whether the element is disabled.
    pub disabled: Option<bool>,
    /// Whether the element is selected (for options).
    pub selected: Option<bool>,
    /// Whether the element is expanded (for tree items, comboboxes).
    pub expanded: Option<bool>,
    /// Whether to include hidden elements.
    pub include_hidden: Option<bool>,
    /// The heading level (1-6, for heading role).
    pub level: Option<u32>,
    /// The accessible name of the element.
    pub name: Option<String>,
    /// The accessible description of the element (WAI-ARIA), matched in addition
    /// to role/name. Honors `exact` like `name`.
    pub description: Option<String>,
    /// Whether `name`/`description` matching is exact (case-sensitive,
    /// full-string). Default is false (case-insensitive substring).
    pub exact: Option<bool>,
    /// Whether the element is pressed (for toggle buttons).
    pub pressed: Option<bool>,
}

impl GetByRoleOptions {
    /// Match only checked / unchecked elements.
    pub fn checked(mut self, checked: bool) -> Self {
        self.checked = Some(checked);
        self
    }
    /// Match only enabled / disabled elements.
    pub fn disabled(mut self, disabled: bool) -> Self {
        self.disabled = Some(disabled);
        self
    }
    /// Match only selected / unselected elements.
    pub fn selected(mut self, selected: bool) -> Self {
        self.selected = Some(selected);
        self
    }
    /// Match only expanded / collapsed elements.
    pub fn expanded(mut self, expanded: bool) -> Self {
        self.expanded = Some(expanded);
        self
    }
    /// Include elements normally excluded from the accessibility tree.
    pub fn include_hidden(mut self, include_hidden: bool) -> Self {
        self.include_hidden = Some(include_hidden);
        self
    }
    /// Match the aria-level (e.g. heading level).
    pub fn level(mut self, level: u32) -> Self {
        self.level = Some(level);
        self
    }
    /// Match the accessible name.
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }
    /// Match the accessible description.
    pub fn description(mut self, description: impl Into<String>) -> Self {
        self.description = Some(description.into());
        self
    }
    /// Whether `name`/`description` match exactly (case-sensitive whole string).
    pub fn exact(mut self, exact: bool) -> Self {
        self.exact = Some(exact);
        self
    }
    /// Match only pressed / unpressed elements.
    pub fn pressed(mut self, pressed: bool) -> Self {
        self.pressed = Some(pressed);
        self
    }
}

/// Options for [`Locator::highlight()`].
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct HighlightOptions {
    /// Extra inline CSS applied to the debug highlight overlay.
    pub style: Option<String>,
}

impl HighlightOptions {
    /// Extra inline CSS applied to the debug highlight overlay.
    pub fn style(mut self, style: impl Into<String>) -> Self {
        self.style = Some(style.into());
        self
    }
}

/// Options for [`Locator::filter()`].
///
/// Narrows an existing locator according to the specified criteria.
/// All fields are optional; unset fields are ignored.
///
/// See: <https://playwright.dev/docs/api/class-locator#locator-filter>
#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct FilterOptions {
    /// Matches elements containing the specified text (case-insensitive substring by default).
    pub has_text: Option<String>,
    /// Matches elements that do **not** contain the specified text anywhere inside.
    pub has_not_text: Option<String>,
    /// Narrows to elements that contain a descendant matching this locator.
    ///
    /// The inner locator is queried relative to the outer locator's matched element,
    /// not the document root.
    pub has: Option<Locator>,
    /// Narrows to elements that do **not** contain a descendant matching this locator.
    pub has_not: Option<Locator>,
    /// Narrows to elements that are visible (`true`) or hidden (`false`).
    ///
    /// [`Locator::visible`] is the shorthand for the `true` case.
    pub visible: Option<bool>,
}

impl FilterOptions {
    /// Keep only elements containing the given text (case-insensitive substring).
    pub fn has_text(mut self, has_text: impl Into<String>) -> Self {
        self.has_text = Some(has_text.into());
        self
    }
    /// Keep only elements NOT containing the given text.
    pub fn has_not_text(mut self, has_not_text: impl Into<String>) -> Self {
        self.has_not_text = Some(has_not_text.into());
        self
    }
    /// Keep only elements containing a match for the inner locator.
    pub fn has(mut self, has: Locator) -> Self {
        self.has = Some(has);
        self
    }
    /// Keep only elements NOT containing a match for the inner locator.
    pub fn has_not(mut self, has_not: Locator) -> Self {
        self.has_not = Some(has_not);
        self
    }
    /// Keep only visible (`true`) or only hidden (`false`) elements.
    pub fn visible(mut self, visible: bool) -> Self {
        self.visible = Some(visible);
        self
    }
}

/// What is left of a `timeout_ms` budget after `elapsed`, for the second
/// step of a two-step action that shares one deadline. Playwright reads 0 as
/// no timeout, so it stays 0; otherwise at least a millisecond is left, since
/// a remainder of 0 would turn into no timeout at all.
fn remaining_ms(timeout_ms: f64, elapsed: std::time::Duration) -> f64 {
    if timeout_ms == 0.0 {
        return 0.0;
    }
    (timeout_ms - elapsed.as_secs_f64() * 1000.0).max(1.0)
}

/// The selector [`Locator::within`] builds: `child` chained under `parent`,
/// so relative parts of `child` such as `nth` resolve inside each element
/// `parent` matches.
fn within_selector(child: &str, parent: &str) -> String {
    let quoted = json_quote(child);
    format!("{parent} >> internal:chain={quoted}")
}

/// The selector `filter` builds: each narrowing appended in the order
/// upstream's client appends it, since the engine applies them in order.
///
/// The `has` / `has_not` selectors are passed separately because a
/// [`FilterOptions`] holds whole locators, and only their selectors matter
/// here.
fn filter_selector(
    base: &str,
    options: &FilterOptions,
    has: Option<&str>,
    has_not: Option<&str>,
) -> String {
    let mut selector = base.to_string();

    if let Some(text) = &options.has_text {
        let escaped = escape_for_selector(text, false);
        selector = format!("{selector} >> internal:has-text={escaped}");
    }

    if let Some(text) = &options.has_not_text {
        let escaped = escape_for_selector(text, false);
        selector = format!("{selector} >> internal:has-not-text={escaped}");
    }

    if let Some(inner) = has {
        let quoted = json_quote(inner);
        selector = format!("{selector} >> internal:has={quoted}");
    }

    if let Some(inner) = has_not {
        let quoted = json_quote(inner);
        selector = format!("{selector} >> internal:has-not={quoted}");
    }

    if let Some(visible) = options.visible {
        selector = format!("{selector} >> visible={visible}");
    }

    selector
}

/// Locator represents a way to find element(s) on the page at any given moment.
///
/// Locators are lazy - they don't execute queries until an action is performed.
/// This enables auto-waiting and retry-ability for robust test automation.
///
/// # Examples
///
/// ```no_run
/// use playwright_rs::protocol::{Playwright, SelectOption};
///
/// #[tokio::main]
/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
///     let playwright = Playwright::launch().await?;
///     let browser = playwright.chromium().launch().await?;
///     let page = browser.new_page().await?;
///
///     // Demonstrate set_checked() - checkbox interaction
///     let _ = page.goto(
///         "data:text/html,<input type='checkbox' id='cb'>",
///         None
///     ).await;
///     let checkbox = page.locator("#cb");
///     checkbox.set_checked(true, None).await?;
///     assert!(checkbox.is_checked().await?);
///     checkbox.set_checked(false, None).await?;
///     assert!(!checkbox.is_checked().await?);
///
///     // Demonstrate select_option() - select by value, label, and index
///     let _ = page.goto(
///         "data:text/html,<select id='fruits'>\
///             <option value='apple'>Apple</option>\
///             <option value='banana'>Banana</option>\
///             <option value='cherry'>Cherry</option>\
///         </select>",
///         None
///     ).await;
///     let select = page.locator("#fruits");
///     select.select_option("banana", None).await?;
///     assert_eq!(select.input_value(None).await?, "banana");
///     select.select_option(SelectOption::Label("Apple".to_string()), None).await?;
///     assert_eq!(select.input_value(None).await?, "apple");
///     select.select_option(SelectOption::Index(2), None).await?;
///     assert_eq!(select.input_value(None).await?, "cherry");
///
///     // Demonstrate select_option_multiple() - multi-select
///     let _ = page.goto(
///         "data:text/html,<select id='colors' multiple>\
///             <option value='red'>Red</option>\
///             <option value='green'>Green</option>\
///             <option value='blue'>Blue</option>\
///             <option value='yellow'>Yellow</option>\
///         </select>",
///         None
///     ).await;
///     let multi = page.locator("#colors");
///     let selected = multi.select_option_multiple(&["red", "blue"], None).await?;
///     assert_eq!(selected.len(), 2);
///     assert!(selected.contains(&"red".to_string()));
///     assert!(selected.contains(&"blue".to_string()));
///
///     // Demonstrate get_by_text() - find elements by text content
///     let _ = page.goto(
///         "data:text/html,<button>Submit</button><button>Submit Order</button>",
///         None
///     ).await;
///     let all_submits = page.get_by_text("Submit", false);
///     assert_eq!(all_submits.count().await?, 2); // case-insensitive substring
///     let exact_submit = page.get_by_text("Submit", true);
///     assert_eq!(exact_submit.count().await?, 1); // exact match only
///
///     // Demonstrate get_by_label, get_by_placeholder, get_by_test_id
///     let _ = page.goto(
///         "data:text/html,<label for='email'>Email</label>\
///             <input id='email' placeholder='you@example.com' data-testid='email-input' />",
///         None
///     ).await;
///     let by_label = page.get_by_label("Email", false);
///     assert_eq!(by_label.count().await?, 1);
///     let by_placeholder = page.get_by_placeholder("you@example.com", true);
///     assert_eq!(by_placeholder.count().await?, 1);
///     let by_test_id = page.get_by_test_id("email-input");
///     assert_eq!(by_test_id.count().await?, 1);
///
///     // Demonstrate screenshot() - element screenshot
///     let _ = page.goto(
///         "data:text/html,<h1 id='title'>Hello World</h1>",
///         None
///     ).await;
///     let heading = page.locator("#title");
///     let screenshot = heading.screenshot(None).await?;
///     assert!(!screenshot.is_empty());
///
///     browser.close().await?;
///     Ok(())
/// }
/// ```
///
/// See: <https://playwright.dev/docs/api/class-locator>
#[derive(Clone)]
pub struct Locator {
    frame: Arc<Frame>,
    selector: String,
    page: crate::protocol::Page,
}

impl Locator {
    /// Creates a new Locator (internal use only)
    ///
    /// Use `page.locator()` or `frame.locator()` to create locators in application code.
    pub(crate) fn new(frame: Arc<Frame>, selector: String, page: crate::protocol::Page) -> Self {
        Self {
            frame,
            selector,
            page,
        }
    }

    /// Returns the selector string for this locator
    pub fn selector(&self) -> &str {
        &self.selector
    }

    /// Returns the underlying frame for this locator (crate-internal use only).
    pub(crate) fn frame(&self) -> &Arc<Frame> {
        &self.frame
    }

    /// Waits until `expression` returns a truthy value, with the matched
    /// element passed as its first argument.
    ///
    /// The element is resolved with strict matching, so a selector matching
    /// more than one element is an error rather than a silent pick of the
    /// first. Returns `()` rather than a handle: the protocol omits the
    /// result when a selector is supplied, so there is nothing to hand back.
    ///
    /// `WaitForFunctionOptions::polling_interval` has no effect on this
    /// form: the driver polls element-scoped waits on its own backoff
    /// schedule (roughly 100ms growing toward 1s) and reads the interval
    /// only for the page-global form.
    ///
    /// # Errors
    ///
    /// Returns an error if the expression does not become truthy within the
    /// timeout (the page default unless set here), or if the selector
    /// matches nothing or more than one element. The timeout is enforced by
    /// the driver, so it surfaces as a protocol error carrying the driver's
    /// "Timeout ...ms exceeded" message, with the selector appended.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-wait-for-function>
    pub async fn wait_for_function(
        &self,
        expression: &str,
        options: impl Into<Option<crate::protocol::WaitForFunctionOptions>>,
    ) -> Result<()> {
        let options = self.with_timeout(options.into());
        self.frame
            .wait_for_function_internal(expression, Some(&self.selector), options)
            .await
            .map(|_| ())
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Serializes this locator as a screenshot `mask` entry — `{ frame, selector }`
    /// with the frame sent as a channel reference — matching the protocol shape
    /// the driver expects. Used by [`crate::protocol::ScreenshotOptions`].
    pub(crate) fn mask_json(&self) -> serde_json::Value {
        use crate::server::channel_owner::ChannelOwner as _;
        serde_json::json!({
            "frame": { "guid": self.frame.guid() },
            "selector": self.selector,
        })
    }

    /// Creates a [`FrameLocator`](crate::protocol::FrameLocator) scoped within this locator's subtree.
    ///
    /// The `selector` identifies an iframe element within the locator's scope.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-frame-locator>
    pub fn frame_locator(&self, selector: &str) -> crate::protocol::FrameLocator {
        crate::protocol::FrameLocator::new(
            Arc::clone(&self.frame),
            format!("{} >> {}", self.selector, selector),
            self.page.clone(),
        )
    }

    /// Returns the Page this locator belongs to.
    ///
    /// Each locator is bound to the page that created it. Chained locators (via
    /// `first()`, `last()`, `nth()`, `locator()`, `filter()`, etc.) all return
    /// the same owning page. This matches the behavior of `locator.page` in
    /// other Playwright language bindings.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use playwright_rs::Playwright;
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let playwright = Playwright::launch().await?;
    /// let browser = playwright.chromium().launch().await?;
    /// let page = browser.new_page().await?;
    /// page.goto("https://example.com", None).await?;
    ///
    /// let locator = page.locator("h1");
    /// let locator_page = locator.page()?;
    /// assert_eq!(locator_page.url(), page.url());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-page>
    pub fn page(&self) -> Result<crate::protocol::Page> {
        Ok(self.page.clone())
    }

    /// Evaluate a JavaScript expression in the frame context.
    ///
    /// Used internally for injecting CSS (e.g., disabling animations) before screenshot assertions.
    #[cfg(feature = "screenshot-diff")]
    pub(crate) async fn evaluate_js<T: serde::Serialize>(
        &self,
        expression: &str,
        _arg: Option<T>,
    ) -> Result<()> {
        self.frame
            .frame_evaluate_expression(expression)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Creates a locator for the first matching element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-first>
    pub fn first(&self) -> Locator {
        Locator::new(
            Arc::clone(&self.frame),
            format!("{} >> nth=0", self.selector),
            self.page.clone(),
        )
    }

    /// Creates a locator for the last matching element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-last>
    pub fn last(&self) -> Locator {
        Locator::new(
            Arc::clone(&self.frame),
            format!("{} >> nth=-1", self.selector),
            self.page.clone(),
        )
    }

    /// Creates a locator for the nth matching element (0-indexed).
    ///
    /// The index is `i32` on purpose: a negative value counts from the end,
    /// as in Playwright, so `nth(-1)` is [`Locator::last`].
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-nth>
    pub fn nth(&self, index: i32) -> Locator {
        Locator::new(
            Arc::clone(&self.frame),
            format!("{} >> nth={}", self.selector, index),
            self.page.clone(),
        )
    }

    /// Returns a locator that matches elements containing the given text.
    ///
    /// By default, matching is case-insensitive and searches for a substring.
    /// Set `exact` to `true` for case-sensitive exact matching.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-get-by-text>
    pub fn get_by_text(&self, text: &str, exact: bool) -> Locator {
        self.locator(get_by_text_selector(text, exact))
    }

    /// Returns a locator that matches elements by their associated label text.
    ///
    /// Targets form controls (`input`, `textarea`, `select`) linked via `<label>`,
    /// `aria-label`, or `aria-labelledby`.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-get-by-label>
    pub fn get_by_label(&self, text: &str, exact: bool) -> Locator {
        self.locator(get_by_label_selector(text, exact))
    }

    /// Returns a locator that matches elements by their placeholder text.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-get-by-placeholder>
    pub fn get_by_placeholder(&self, text: &str, exact: bool) -> Locator {
        self.locator(get_by_placeholder_selector(text, exact))
    }

    /// Returns a locator that matches elements by their alt text.
    ///
    /// Typically used for `<img>` elements.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-get-by-alt-text>
    pub fn get_by_alt_text(&self, text: &str, exact: bool) -> Locator {
        self.locator(get_by_alt_text_selector(text, exact))
    }

    /// Returns a locator that matches elements by their title attribute.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-get-by-title>
    pub fn get_by_title(&self, text: &str, exact: bool) -> Locator {
        self.locator(get_by_title_selector(text, exact))
    }

    /// Returns a locator that matches elements by their test ID attribute.
    ///
    /// By default, uses the `data-testid` attribute. Call
    /// `playwright.selectors().set_test_id_attribute()` to change the attribute name.
    ///
    /// Always uses exact matching (case-sensitive).
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-get-by-test-id>
    pub fn get_by_test_id(&self, test_id: &str) -> Locator {
        use crate::server::channel_owner::ChannelOwner as _;
        let attr = self.frame.connection().selectors().test_id_attribute();
        self.locator(get_by_test_id_selector_with_attr(test_id, &attr))
    }

    /// Returns a locator that matches elements by their ARIA role.
    ///
    /// This is the recommended way to locate elements, as it matches the way
    /// users and assistive technology perceive the page.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-get-by-role>
    pub fn get_by_role(&self, role: AriaRole, options: Option<GetByRoleOptions>) -> Locator {
        self.locator(get_by_role_selector(role, options))
    }

    /// Creates a sub-locator within this locator's subtree.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-locator>
    pub fn locator(&self, selector: impl Into<String>) -> Locator {
        Locator::new(
            Arc::clone(&self.frame),
            format!("{} >> {}", self.selector, selector.into()),
            self.page.clone(),
        )
    }

    /// Narrows this locator according to the filter options.
    ///
    /// Can be chained to apply multiple filters in sequence.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use playwright_rs::{Playwright, FilterOptions};
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let playwright = Playwright::launch().await?;
    /// let browser = playwright.chromium().launch().await?;
    /// let page = browser.new_page().await?;
    ///
    /// // Filter rows to those containing "Apple"
    /// let rows = page.locator("tr");
    /// let apple_row = rows.filter(FilterOptions::default().has_text("Apple"));
    /// # browser.close().await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-filter>
    pub fn filter(&self, options: FilterOptions) -> Locator {
        let selector = filter_selector(
            &self.selector,
            &options,
            options.has.as_ref().map(|l| l.selector.as_str()),
            options.has_not.as_ref().map(|l| l.selector.as_str()),
        );
        Locator::new(Arc::clone(&self.frame), selector, self.page.clone())
    }

    /// Returns a locator that matches only the visible elements of this one.
    ///
    /// This is the replacement Playwright recommends for the `:visible` CSS
    /// pseudo-class. `filter(FilterOptions::default().visible(false))` is the
    /// other half, matching only hidden elements.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use playwright_rs::Playwright;
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let playwright = Playwright::launch().await?;
    /// # let browser = playwright.chromium().launch().await?;
    /// # let page = browser.new_page().await?;
    /// page.locator("button").visible().click(None).await?;
    /// # browser.close().await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-visible>
    pub fn visible(&self) -> Locator {
        Locator::new(
            Arc::clone(&self.frame),
            format!("{} >> visible=true", self.selector),
            self.page.clone(),
        )
    }

    /// Creates a locator matching elements that satisfy **both** this locator and `locator`.
    ///
    /// Note: named `and_` because `and` is a Rust keyword.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use playwright_rs::Playwright;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let playwright = Playwright::launch().await?;
    /// let browser = playwright.chromium().launch().await?;
    /// let page = browser.new_page().await?;
    ///
    /// // Find a button that also has a specific title
    /// let button = page.locator("button");
    /// let titled = page.locator("[title='Subscribe']");
    /// let subscribe_btn = button.and_(&titled);
    /// # browser.close().await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-and>
    pub fn and_(&self, locator: &Locator) -> Locator {
        let inner = json_quote(&locator.selector);
        Locator::new(
            Arc::clone(&self.frame),
            format!("{} >> internal:and={}", self.selector, inner),
            self.page.clone(),
        )
    }

    /// Creates a locator matching the elements this locator finds inside each
    /// element `parent` matches, read in the natural order: "this button,
    /// within that dialog".
    ///
    /// Relative parts of this locator, such as [`nth`](Self::nth) or
    /// [`last`](Self::last), resolve inside each parent separately, so
    /// `cells.nth(2).within(&rows)` is the third cell of every row rather than
    /// the third cell of the table.
    ///
    /// Both locators should come from the same frame. That is not checked
    /// (as it is not for [`and_`](Self::and_) and [`or_`](Self::or_)): the
    /// result searches the frame `parent` belongs to, so a locator from
    /// another frame finds nothing there rather than raising an error.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-within>
    pub fn within(&self, parent: &Locator) -> Locator {
        Locator::new(
            Arc::clone(&parent.frame),
            within_selector(&self.selector, &parent.selector),
            parent.page.clone(),
        )
    }

    /// Creates a locator matching elements that satisfy **either** this locator or `locator`.
    ///
    /// Note: named `or_` because `or` is a Rust keyword.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use playwright_rs::Playwright;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let playwright = Playwright::launch().await?;
    /// let browser = playwright.chromium().launch().await?;
    /// let page = browser.new_page().await?;
    ///
    /// // Find any element that is either a button or a link
    /// let buttons = page.locator("button");
    /// let links = page.locator("a");
    /// let interactive = buttons.or_(&links);
    /// # browser.close().await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-or>
    pub fn or_(&self, locator: &Locator) -> Locator {
        let inner = json_quote(&locator.selector);
        Locator::new(
            Arc::clone(&self.frame),
            format!("{} >> internal:or={}", self.selector, inner),
            self.page.clone(),
        )
    }

    /// Returns the number of elements matching this locator.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-count>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector, count = tracing::field::Empty))]
    pub async fn count(&self) -> Result<usize> {
        let n = self
            .frame
            .locator_count(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))?;
        tracing::Span::current().record("count", n);
        Ok(n)
    }

    /// Returns an array of locators, one for each matching element.
    ///
    /// Note: `all()` does not wait for elements to match the locator,
    /// and instead immediately returns whatever is in the DOM.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-all>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn all(&self) -> Result<Vec<Locator>> {
        let count = self.count().await?;
        Ok((0..count).map(|i| self.nth(i as i32)).collect())
    }

    /// Returns the text content of the element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-text-content>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn text_content(&self) -> Result<Option<String>> {
        self.frame
            .locator_text_content(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns the inner text of the element (visible text).
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-inner-text>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn inner_text(&self) -> Result<String> {
        self.frame
            .locator_inner_text(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns the inner HTML of the element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-inner-html>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn inner_html(&self) -> Result<String> {
        self.frame
            .locator_inner_html(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns the value of the specified attribute.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-get-attribute>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector, name = %name))]
    pub async fn get_attribute(&self, name: &str) -> Result<Option<String>> {
        self.frame
            .locator_get_attribute(&self.selector, name)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns whether the element is visible.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-is-visible>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn is_visible(&self) -> Result<bool> {
        self.frame
            .locator_is_visible(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns whether the element is enabled.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-is-enabled>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn is_enabled(&self) -> Result<bool> {
        self.frame
            .locator_is_enabled(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns whether the checkbox or radio button is checked.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-is-checked>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn is_checked(&self) -> Result<bool> {
        self.frame
            .locator_is_checked(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns whether the element is editable.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-is-editable>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn is_editable(&self) -> Result<bool> {
        self.frame
            .locator_is_editable(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns whether the element is hidden.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-is-hidden>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn is_hidden(&self) -> Result<bool> {
        self.frame
            .locator_is_hidden(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns whether the element is disabled.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-is-disabled>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn is_disabled(&self) -> Result<bool> {
        self.frame
            .locator_is_disabled(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns whether the element is focused (currently has focus).
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-is-focused>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn is_focused(&self) -> Result<bool> {
        self.frame
            .locator_is_focused(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    // Action methods

    /// Clicks the element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-click>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn click(
        &self,
        options: impl Into<Option<crate::protocol::ClickOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_click(&self.selector, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Ensures an options struct has the page's default timeout when none is explicitly set.
    fn with_timeout<T: HasTimeout + Default>(&self, options: Option<T>) -> T {
        let mut opts = options.unwrap_or_default();
        if opts.timeout_ref().is_none() {
            *opts.timeout_ref_mut() = Some(self.page.default_timeout_ms());
        }
        opts
    }

    /// Wraps an error with selector context for better error messages.
    fn wrap_error_with_selector(&self, error: crate::error::Error) -> crate::error::Error {
        match &error {
            crate::error::Error::ProtocolError(msg) => {
                // Add selector context to protocol errors (timeouts, etc.)
                crate::error::Error::ProtocolError(format!("{} [selector: {}]", msg, self.selector))
            }
            crate::error::Error::Timeout(msg) => {
                crate::error::Error::Timeout(format!("{} [selector: {}]", msg, self.selector))
            }
            _ => error, // Other errors pass through unchanged
        }
    }

    /// Double clicks the element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-dblclick>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn dblclick(
        &self,
        options: impl Into<Option<crate::protocol::ClickOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_dblclick(&self.selector, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Fills the element with text.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-fill>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn fill(
        &self,
        text: &str,
        options: impl Into<Option<crate::protocol::FillOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_fill(&self.selector, text, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Clears the element's value.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-clear>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn clear(
        &self,
        options: impl Into<Option<crate::protocol::FillOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_clear(&self.selector, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Presses a key on the element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-press>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn press(
        &self,
        key: &str,
        options: impl Into<Option<crate::protocol::PressOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_press(&self.selector, key, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Sets focus on the element.
    ///
    /// Calls the element's `focus()` method. Used to move keyboard focus to a
    /// specific element for subsequent keyboard interactions.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-focus>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn focus(&self) -> Result<()> {
        self.frame
            .locator_focus(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Removes focus from the element.
    ///
    /// Calls the element's `blur()` method. Moves keyboard focus away from the element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-blur>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn blur(&self) -> Result<()> {
        self.frame
            .locator_blur(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Types `text` into the element character by character, as though it was typed
    /// on a real keyboard.
    ///
    /// Use this method when you need to simulate keystrokes with individual key events
    /// (e.g., for autocomplete widgets). For simply setting a field value, prefer
    /// [`Locator::fill()`].
    ///
    /// # Arguments
    ///
    /// * `text` - Text to type into the element
    /// * `options` - Optional [`PressSequentiallyOptions`](crate::protocol::PressSequentiallyOptions) (e.g., `delay` between key presses)
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-press-sequentially>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn press_sequentially(
        &self,
        text: &str,
        options: impl Into<Option<crate::protocol::PressSequentiallyOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_press_sequentially(&self.selector, text, options)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns the `innerText` values of all elements matching this locator.
    ///
    /// Unlike [`Locator::inner_text()`] (which uses strict mode and requires exactly one match),
    /// `all_inner_texts()` returns text from all matching elements.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-all-inner-texts>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn all_inner_texts(&self) -> Result<Vec<String>> {
        self.frame
            .locator_all_inner_texts(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns the `textContent` values of all elements matching this locator.
    ///
    /// Unlike [`Locator::text_content()`] (which uses strict mode and requires exactly one match),
    /// `all_text_contents()` returns text from all matching elements.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-all-text-contents>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn all_text_contents(&self) -> Result<Vec<String>> {
        self.frame
            .locator_all_text_contents(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Ensures the checkbox or radio button is checked.
    ///
    /// This method is idempotent - if already checked, does nothing.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-check>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn check(
        &self,
        options: impl Into<Option<crate::protocol::CheckOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_check(&self.selector, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Ensures the checkbox is unchecked.
    ///
    /// This method is idempotent - if already unchecked, does nothing.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-uncheck>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn uncheck(
        &self,
        options: impl Into<Option<crate::protocol::CheckOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_uncheck(&self.selector, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Sets the checkbox or radio button to the specified checked state.
    ///
    /// This is a convenience method that calls `check()` if `checked` is true,
    /// or `uncheck()` if `checked` is false.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-set-checked>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn set_checked(
        &self,
        checked: bool,
        options: impl Into<Option<crate::protocol::CheckOptions>>,
    ) -> Result<()> {
        let options = options.into();
        if checked {
            self.check(options).await
        } else {
            self.uncheck(options).await
        }
    }

    /// Hovers the mouse over the element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-hover>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn hover(
        &self,
        options: impl Into<Option<crate::protocol::HoverOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_hover(&self.selector, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns the value of the input, textarea, or select element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-input-value>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn input_value(&self, _options: impl Into<Option<()>>) -> Result<String> {
        self.frame
            .locator_input_value(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Selects one or more options in a select element.
    ///
    /// Returns an array of option values that have been successfully selected.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-select-option>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn select_option(
        &self,
        value: impl Into<crate::protocol::SelectOption>,
        options: impl Into<Option<crate::protocol::SelectOptions>>,
    ) -> Result<Vec<String>> {
        let options = options.into();
        self.frame
            .locator_select_option(
                &self.selector,
                value.into(),
                Some(self.with_timeout(options)),
            )
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Selects multiple options in a select element.
    ///
    /// Returns an array of option values that have been successfully selected.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-select-option>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn select_option_multiple(
        &self,
        values: &[impl Into<crate::protocol::SelectOption> + Clone],
        options: impl Into<Option<crate::protocol::SelectOptions>>,
    ) -> Result<Vec<String>> {
        let options = options.into();
        let select_options: Vec<crate::protocol::SelectOption> =
            values.iter().map(|v| v.clone().into()).collect();
        self.frame
            .locator_select_option_multiple(
                &self.selector,
                select_options,
                Some(self.with_timeout(options)),
            )
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Sets the file path(s) to upload to a file input element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-set-input-files>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn set_input_files(
        &self,
        file: &std::path::PathBuf,
        _options: impl Into<Option<()>>,
    ) -> Result<()> {
        self.frame
            .locator_set_input_files(&self.selector, file)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Sets multiple file paths to upload to a file input element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-set-input-files>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn set_input_files_multiple(
        &self,
        files: &[&std::path::PathBuf],
        _options: impl Into<Option<()>>,
    ) -> Result<()> {
        self.frame
            .locator_set_input_files_multiple(&self.selector, files)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Sets a file to upload using FilePayload (explicit name, mimeType, buffer).
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-set-input-files>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn set_input_files_payload(
        &self,
        file: crate::protocol::FilePayload,
        _options: impl Into<Option<()>>,
    ) -> Result<()> {
        self.frame
            .locator_set_input_files_payload(&self.selector, file)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Sets multiple files to upload using FilePayload.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-set-input-files>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn set_input_files_payload_multiple(
        &self,
        files: &[crate::protocol::FilePayload],
        _options: impl Into<Option<()>>,
    ) -> Result<()> {
        self.frame
            .locator_set_input_files_payload_multiple(&self.selector, files)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Dispatches a DOM event on the element.
    ///
    /// Unlike clicking or typing, `dispatch_event` directly sends the event without
    /// performing any actionability checks. It still waits for the element to be present
    /// in the DOM.
    ///
    /// # Arguments
    ///
    /// * `type_` - The event type to dispatch, e.g. `"click"`, `"focus"`, `"myevent"`.
    /// * `event_init` - Optional event initializer properties (e.g. `{"detail": "value"}` for
    ///   `CustomEvent`). Corresponds to the second argument of `new Event(type, init)`.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The element is not found within the timeout
    /// - The protocol call fails
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-dispatch-event>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn dispatch_event(
        &self,
        type_: &str,
        event_init: Option<serde_json::Value>,
    ) -> Result<()> {
        self.frame
            .locator_dispatch_event(&self.selector, type_, event_init)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns the bounding box of the element, or `None` if the element is not visible.
    ///
    /// The bounding box is in pixels, relative to the top-left corner of the page.
    /// Returns `None` when the element has `display: none` or is otherwise not part of
    /// the layout.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The element is not found within the timeout
    /// - The protocol call fails
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-bounding-box>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn bounding_box(&self) -> Result<Option<BoundingBox>> {
        self.frame
            .locator_bounding_box(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Scrolls the element into view if it is not already visible in the viewport.
    ///
    /// This is an alias for calling `element.scrollIntoView()` in the browser.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The element is not found within the timeout
    /// - The protocol call fails
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-scroll-into-view-if-needed>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn scroll_into_view_if_needed(&self) -> Result<()> {
        self.frame
            .locator_scroll_into_view_if_needed(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Takes a screenshot of the element and returns the image bytes.
    ///
    /// This method uses strict mode - it will fail if the selector matches multiple elements.
    /// Use `first()`, `last()`, or `nth()` to refine the selector to a single element.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-screenshot>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector, bytes_len = tracing::field::Empty))]
    pub async fn screenshot(
        &self,
        options: impl Into<Option<crate::protocol::ScreenshotOptions>>,
    ) -> Result<Vec<u8>> {
        let mut options = self.with_timeout(options.into());
        let timeout = options.timeout.unwrap_or(crate::DEFAULT_TIMEOUT_MS);
        let started = std::time::Instant::now();
        // Wait for the element as every locator action does, then take the
        // screenshot within what is left of the same deadline.
        let element = self
            .frame
            .locator_wait_for_element(&self.selector, timeout)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))?;
        options.timeout = Some(remaining_ms(timeout, started.elapsed()));
        let captured = element.screenshot(Some(options)).await;
        // The wait created the handle; a failed dispose only leaves it to live
        // as long as the page.
        let _ = crate::server::channel_owner::ChannelOwner::channel(element.as_ref())
            .send_no_result("dispose", serde_json::json!({}))
            .await;
        let bytes = captured.map_err(|e| self.wrap_error_with_selector(e))?;
        tracing::Span::current().record("bytes_len", bytes.len());
        Ok(bytes)
    }

    /// Performs a touch-tap on the element.
    ///
    /// This method dispatches a `touchstart` and `touchend` event on the element.
    /// For touch support to work, the browser context must be created with
    /// `has_touch: true`.
    ///
    /// # Arguments
    ///
    /// * `options` - Optional [`TapOptions`](crate::protocol::TapOptions) (force, modifiers, position, timeout, trial)
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The element is not found within the timeout
    /// - Actionability checks fail (unless `force: true`)
    /// - The browser context was not created with `has_touch: true`
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-tap>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn tap(&self, options: impl Into<Option<crate::protocol::TapOptions>>) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_tap(&self.selector, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Drags this element to the `target` element.
    ///
    /// Both this locator and `target` must resolve to elements in the same frame.
    /// Playwright performs a series of mouse events (move, press, move to target, release)
    /// to simulate the drag, so it drives real pointer-event chains, including
    /// UIs that call `setPointerCapture` in their `pointerdown` handler.
    ///
    /// `source_position` and `target_position` are offsets from the respective
    /// element's top-left corner. Setting `target_position` with a containing
    /// element (a canvas or stage) as `target` turns this into a drag to a
    /// coordinate rather than onto an element, which also covers "drag by a
    /// delta": compute the drop point from the source's position within the
    /// container. Prefer this over a held-button
    /// [`Mouse::move_to`](crate::protocol::Mouse::move_to) sequence, which can
    /// hang on headless Linux (see the note on that method).
    ///
    /// # Arguments
    ///
    /// * `target` - The locator of the element to drag onto
    /// * `options` - Optional [`DragToOptions`](crate::protocol::DragToOptions) (force, no_wait_after, timeout, trial,
    ///   source_position, target_position)
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use playwright_rs::{Playwright, DragToOptions, Position};
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let pw = Playwright::launch().await?;
    /// # let page = pw.chromium().launch().await?.new_page().await?;
    /// let handle = page.locator(".crop-handle");
    /// let stage = page.locator("#stage");
    ///
    /// // Drop the handle 180px right, 120px down from the stage's top-left corner.
    /// let opts = DragToOptions::builder()
    ///     .target_position(Position { x: 180.0, y: 120.0 })
    ///     .build();
    /// handle.drag_to(&stage, Some(opts)).await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Either element is not found within the timeout
    /// - Actionability checks fail (unless `force: true`)
    /// - The protocol call fails
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-drag-to>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn drag_to(
        &self,
        target: &Locator,
        options: impl Into<Option<crate::protocol::DragToOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_drag_to(
                &self.selector,
                &target.selector,
                Some(self.with_timeout(options)),
            )
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Drops files and/or data onto this element (external drag-and-drop).
    ///
    /// Simulates dragging files or data from outside the page onto the element,
    /// such as an upload drop zone, by dispatching `dragenter`/`dragover`/`drop`
    /// with a synthetic `DataTransfer`. Set `files` and/or `data` on the
    /// [`DropOptions`](crate::protocol::DropOptions). This is distinct from
    /// [`drag_to`](Self::drag_to), which drags one element onto another within
    /// the page.
    ///
    /// # Arguments
    ///
    /// * `options` - [`DropOptions`](crate::protocol::DropOptions) carrying the
    ///   files / data to drop, plus optional `position` and `timeout`.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The element is not found within the timeout
    /// - Actionability checks fail
    /// - The protocol call fails (e.g. neither files nor data were provided)
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-drop>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn drop(&self, options: crate::protocol::DropOptions) -> Result<()> {
        self.frame
            .locator_drop(&self.selector, self.with_timeout(Some(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Waits until the element satisfies the given state condition.
    ///
    /// If no state is specified, waits for the element to be `visible` (the default).
    ///
    /// This method is useful for waiting for lazy-rendered elements or elements that
    /// appear/disappear based on user interaction or async data loading.
    ///
    /// # Arguments
    ///
    /// * `options` - Optional [`WaitForOptions`](crate::protocol::WaitForOptions) specifying the `state` to wait for
    ///   (`Visible`, `Hidden`, `Attached`, or `Detached`) and a `timeout` in milliseconds.
    ///
    /// # Errors
    ///
    /// Returns an error if the element does not satisfy the expected state within the timeout.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-wait-for>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn wait_for(
        &self,
        options: impl Into<Option<crate::protocol::WaitForOptions>>,
    ) -> Result<()> {
        let options = options.into();
        self.frame
            .locator_wait_for(&self.selector, Some(self.with_timeout(options)))
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Evaluates a JavaScript expression in the scope of the matched element.
    ///
    /// The element is passed as the first argument to the expression. The expression
    /// can be any JavaScript function or expression that returns a JSON-serializable value.
    ///
    /// # Arguments
    ///
    /// * `expression` - JavaScript expression or function, e.g. `"(el) => el.textContent"`
    /// * `arg` - Optional argument passed as the second argument to the function
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The element is not found within the timeout
    /// - The JavaScript expression throws an error
    /// - The return value is not JSON-serializable
    ///
    /// # Example
    ///
    /// ```no_run
    /// use playwright_rs::Playwright;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let playwright = Playwright::launch().await?;
    /// let browser = playwright.chromium().launch().await?;
    /// let page = browser.new_page().await?;
    /// let _ = page.goto("data:text/html,<h1>Hello</h1>", None).await;
    ///
    /// let heading = page.locator("h1");
    /// let text: String = heading.evaluate("(el) => el.textContent", None::<()>).await?;
    /// assert_eq!(text, "Hello");
    ///
    /// // With an argument
    /// let result: String = heading
    ///     .evaluate("(el, suffix) => el.textContent + suffix", Some("!"))
    ///     .await?;
    /// assert_eq!(result, "Hello!");
    /// # browser.close().await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-evaluate>
    #[tracing::instrument(level = "info", skip_all, fields(selector = %self.selector))]
    pub async fn evaluate<R, T>(&self, expression: &str, arg: Option<T>) -> Result<R>
    where
        R: serde::de::DeserializeOwned,
        T: serde::Serialize,
    {
        let raw = self
            .frame
            .locator_evaluate(&self.selector, expression, arg)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))?;
        serde_json::from_value(raw).map_err(|e| {
            crate::error::Error::ProtocolError(format!(
                "evaluate result deserialization failed: {}",
                e
            ))
        })
    }

    /// Evaluates a JavaScript expression in the scope of all elements matching this locator.
    ///
    /// The array of all matched elements is passed as the first argument to the expression.
    /// Unlike [`evaluate()`](Self::evaluate), this does not use strict mode — all matching
    /// elements are collected and passed as an array.
    ///
    /// # Arguments
    ///
    /// * `expression` - JavaScript function that receives an array of elements
    /// * `arg` - Optional argument passed as the second argument to the function
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The JavaScript expression throws an error
    /// - The return value is not JSON-serializable
    ///
    /// # Example
    ///
    /// ```no_run
    /// use playwright_rs::Playwright;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let playwright = Playwright::launch().await?;
    /// let browser = playwright.chromium().launch().await?;
    /// let page = browser.new_page().await?;
    /// let _ = page.goto(
    ///     "data:text/html,<li class='item'>A</li><li class='item'>B</li>",
    ///     None
    /// ).await;
    ///
    /// let items = page.locator(".item");
    /// let texts: Vec<String> = items
    ///     .evaluate_all("(elements) => elements.map(e => e.textContent)", None::<()>)
    ///     .await?;
    /// assert_eq!(texts, vec!["A", "B"]);
    /// # browser.close().await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-evaluate-all>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn evaluate_all<R, T>(&self, expression: &str, arg: Option<T>) -> Result<R>
    where
        R: serde::de::DeserializeOwned,
        T: serde::Serialize,
    {
        let raw = self
            .frame
            .locator_evaluate_all(&self.selector, expression, arg)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))?;
        serde_json::from_value(raw).map_err(|e| {
            crate::error::Error::ProtocolError(format!(
                "evaluate_all result deserialization failed: {}",
                e
            ))
        })
    }

    /// Returns the ARIA accessibility tree snapshot as a YAML string.
    ///
    /// The snapshot describes the accessible roles, names, and properties of the matched
    /// element and its descendants. This is useful for writing stable accessibility assertions
    /// that are independent of CSS classes or DOM structure.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The element is not found within the timeout
    /// - The protocol call fails
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-aria-snapshot>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn aria_snapshot(
        &self,
        options: impl Into<Option<crate::protocol::AriaSnapshotOptions>>,
    ) -> Result<String> {
        let options = options.into();
        self.frame
            .locator_aria_snapshot(&self.selector, options.as_ref())
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// The accessibility tree of the matched element, as JSON rather than
    /// the YAML markup [`aria_snapshot`](Self::aria_snapshot) returns, so a
    /// caller can walk it instead of parsing text.
    ///
    /// Takes the same options; `mode`, `depth`, and `boxes` all apply.
    ///
    /// # Errors
    ///
    /// Returns an error if the element is not found within the timeout, or
    /// if the driver rejects the request.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-aria-snapshot-json>
    pub async fn aria_snapshot_json(
        &self,
        options: impl Into<Option<crate::protocol::AriaSnapshotOptions>>,
    ) -> Result<serde_json::Value> {
        let options = options.into();
        self.frame
            .locator_aria_snapshot_json(&self.selector, options.as_ref())
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns a new locator whose selector has been resolved to a
    /// best-practices canonical form — preferring test-ids, then ARIA
    /// roles, then accessible text. The resolved locator points at the
    /// same element(s) as `self` but uses a more robust selector that
    /// is less coupled to CSS classes or DOM structure. Useful as a
    /// building block for codegen helpers that want the "most stable
    /// selector for this element" primitive.
    ///
    /// See the module-level example for usage.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - No element matches the original selector
    /// - The protocol call fails
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-normalize>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn normalize(&self) -> Result<Locator> {
        let resolved = self
            .frame
            .frame_resolve_selector(&self.selector)
            .await
            .map_err(|e| self.wrap_error_with_selector(e))?;
        Ok(Locator {
            frame: Arc::clone(&self.frame),
            selector: resolved,
            page: self.page.clone(),
        })
    }

    /// Returns a new Locator with an attached description for traces and error messages.
    ///
    /// The description does not affect element matching — it is purely informational,
    /// appearing in trace viewer labels and error messages to make them more readable.
    ///
    /// Appends `>> internal:describe="description"` to the selector, matching
    /// playwright-python's behavior exactly.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-describe>
    pub fn describe(&self, description: &str) -> Locator {
        let escaped = json_quote(description);
        Locator::new(
            Arc::clone(&self.frame),
            format!("{} >> internal:describe={}", self.selector, escaped),
            self.page.clone(),
        )
    }

    /// Highlights the matched element in the browser for visual debugging.
    ///
    /// Draws a colored overlay over the element for a short period. This is a
    /// debugging tool and has no effect on test assertions or element state.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The element is not found within the timeout
    /// - The protocol call fails
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-highlight>
    #[tracing::instrument(level = "debug", skip_all, fields(selector = %self.selector))]
    pub async fn highlight(&self, options: impl Into<Option<HighlightOptions>>) -> Result<()> {
        let options = options.into();
        let style = options.and_then(|o| o.style);
        self.frame
            .locator_highlight(&self.selector, style.as_deref())
            .await
            .map_err(|e| self.wrap_error_with_selector(e))
    }

    /// Returns a [`FrameLocator`](crate::protocol::FrameLocator) for the content of an
    /// `<iframe>` element matched by this locator.
    ///
    /// This is a client-side operation — it creates a `FrameLocator` scoped to the matched
    /// iframe element, allowing you to interact with elements inside the iframe using the
    /// standard `FrameLocator` API.
    ///
    /// Equivalent to `page.frame_locator(selector)`, but starting from an existing `Locator`.
    ///
    /// See: <https://playwright.dev/docs/api/class-locator#locator-content-frame>
    pub fn content_frame(&self) -> crate::protocol::FrameLocator {
        crate::protocol::FrameLocator::new(
            Arc::clone(&self.frame),
            self.selector.clone(),
            self.page.clone(),
        )
    }
}

impl std::fmt::Debug for Locator {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Locator")
            .field("selector", &self.selector)
            .finish()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_escape_for_selector_case_insensitive() {
        assert_eq!(escape_for_selector("hello", false), "\"hello\"i");
    }

    #[test]
    fn test_escape_for_selector_exact() {
        assert_eq!(escape_for_selector("hello", true), "\"hello\"s");
    }

    #[test]
    fn test_escape_for_selector_with_quotes() {
        assert_eq!(
            escape_for_selector("say \"hi\"", false),
            "\"say \\\"hi\\\"\"i"
        );
    }

    #[test]
    fn test_get_by_text_selector_case_insensitive() {
        assert_eq!(
            get_by_text_selector("Click me", false),
            "internal:text=\"Click me\"i"
        );
    }

    #[test]
    fn test_get_by_text_selector_exact() {
        assert_eq!(
            get_by_text_selector("Click me", true),
            "internal:text=\"Click me\"s"
        );
    }

    #[test]
    fn test_get_by_label_selector() {
        assert_eq!(
            get_by_label_selector("Email", false),
            "internal:label=\"Email\"i"
        );
    }

    #[test]
    fn test_get_by_placeholder_selector() {
        assert_eq!(
            get_by_placeholder_selector("Enter name", false),
            "internal:attr=[placeholder=\"Enter name\"i]"
        );
    }

    #[test]
    fn test_get_by_alt_text_selector() {
        assert_eq!(
            get_by_alt_text_selector("Logo", true),
            "internal:attr=[alt=\"Logo\"s]"
        );
    }

    #[test]
    fn test_get_by_title_selector() {
        assert_eq!(
            get_by_title_selector("Help", false),
            "internal:attr=[title=\"Help\"i]"
        );
    }

    #[test]
    fn test_get_by_test_id_selector() {
        assert_eq!(
            get_by_test_id_selector("submit-btn"),
            "internal:testid=[data-testid=\"submit-btn\"s]"
        );
    }

    #[test]
    fn test_escape_for_attribute_selector_case_insensitive() {
        assert_eq!(
            escape_for_attribute_selector("Submit", false),
            "\"Submit\"i"
        );
    }

    #[test]
    fn test_escape_for_attribute_selector_exact() {
        assert_eq!(escape_for_attribute_selector("Submit", true), "\"Submit\"s");
    }

    #[test]
    fn test_escape_for_attribute_selector_escapes_quotes() {
        assert_eq!(
            escape_for_attribute_selector("Say \"hello\"", false),
            "\"Say \\\"hello\\\"\"i"
        );
    }

    #[test]
    fn test_escape_for_attribute_selector_escapes_backslashes() {
        assert_eq!(
            escape_for_attribute_selector("path\\to", true),
            "\"path\\\\to\"s"
        );
    }

    #[test]
    fn test_get_by_role_selector_role_only() {
        assert_eq!(
            get_by_role_selector(AriaRole::Button, None),
            "internal:role=button"
        );
    }

    #[test]
    fn test_get_by_role_selector_with_name() {
        let opts = GetByRoleOptions::default().name("Submit");
        assert_eq!(
            get_by_role_selector(AriaRole::Button, Some(opts)),
            "internal:role=button[name=\"Submit\"i]"
        );
    }

    #[test]
    fn test_filter_options_setters() {
        let opts = FilterOptions::default()
            .has_text("a")
            .has_not_text("b")
            .visible(false);
        assert_eq!(opts.has_text.as_deref(), Some("a"));
        assert_eq!(opts.has_not_text.as_deref(), Some("b"));
        assert_eq!(opts.visible, Some(false));
        assert_eq!(FilterOptions::default().visible, None);
    }

    #[test]
    fn a_shared_deadline_leaves_the_remainder_and_keeps_zero_as_no_timeout() {
        use std::time::Duration;
        assert_eq!(remaining_ms(5_000.0, Duration::from_millis(1_500)), 3_500.0);
        assert_eq!(remaining_ms(5_000.0, Duration::from_millis(6_000)), 1.0);
        assert_eq!(remaining_ms(0.0, Duration::from_millis(1_500)), 0.0);
    }

    #[test]
    fn within_selector_chains_the_child_under_the_parent() {
        assert_eq!(
            within_selector("internal:role=cell >> nth=1", "internal:role=row"),
            r#"internal:role=row >> internal:chain="internal:role=cell >> nth=1""#
        );
        assert_eq!(
            within_selector(r#"text="Save""#, "dialog"),
            r#"dialog >> internal:chain="text=\"Save\"""#
        );
    }

    #[test]
    fn filter_selector_appends_each_narrowing_in_order() {
        let options = FilterOptions::default()
            .has_text("Apple")
            .has_not_text("Pear")
            .visible(true);

        assert_eq!(
            filter_selector("tr", &options, Some("td.price"), Some("td.sold")),
            "tr >> internal:has-text=\"Apple\"i >> internal:has-not-text=\"Pear\"i \
             >> internal:has=\"td.price\" >> internal:has-not=\"td.sold\" >> visible=true"
        );
    }

    #[test]
    fn filter_selector_leaves_the_base_alone_when_nothing_is_set() {
        assert_eq!(
            filter_selector("tr", &FilterOptions::default(), None, None),
            "tr"
        );
    }

    #[test]
    fn filter_selector_spells_the_hidden_half() {
        let options = FilterOptions::default().visible(false);
        assert_eq!(
            filter_selector(".item", &options, None, None),
            ".item >> visible=false"
        );
    }

    #[test]
    fn test_get_by_role_selector_with_description() {
        let opts = GetByRoleOptions::default().description("Close dialog");
        assert_eq!(
            get_by_role_selector(AriaRole::Button, Some(opts)),
            "internal:role=button[description=\"Close dialog\"i]"
        );
        let exact = GetByRoleOptions::default().description("Close").exact(true);
        assert_eq!(
            get_by_role_selector(AriaRole::Button, Some(exact)),
            "internal:role=button[description=\"Close\"s]"
        );
    }

    #[test]
    fn test_get_by_role_selector_with_name_exact() {
        let opts = GetByRoleOptions::default().name("Submit").exact(true);
        assert_eq!(
            get_by_role_selector(AriaRole::Button, Some(opts)),
            "internal:role=button[name=\"Submit\"s]"
        );
    }

    #[test]
    fn test_get_by_role_selector_with_checked() {
        let opts = GetByRoleOptions::default().checked(true);
        assert_eq!(
            get_by_role_selector(AriaRole::Checkbox, Some(opts)),
            "internal:role=checkbox[checked=true]"
        );
    }

    #[test]
    fn test_get_by_role_selector_with_level() {
        let opts = GetByRoleOptions::default().level(2);
        assert_eq!(
            get_by_role_selector(AriaRole::Heading, Some(opts)),
            "internal:role=heading[level=2]"
        );
    }

    #[test]
    fn test_get_by_role_selector_with_disabled() {
        let opts = GetByRoleOptions::default().disabled(true);
        assert_eq!(
            get_by_role_selector(AriaRole::Button, Some(opts)),
            "internal:role=button[disabled=true]"
        );
    }

    #[test]
    fn test_get_by_role_selector_with_selected() {
        let opts = GetByRoleOptions::default().selected(true);
        assert_eq!(
            get_by_role_selector(AriaRole::Option, Some(opts)),
            "internal:role=option[selected=true]"
        );
    }

    #[test]
    fn test_get_by_role_selector_with_expanded() {
        let opts = GetByRoleOptions::default().expanded(true);
        assert_eq!(
            get_by_role_selector(AriaRole::Button, Some(opts)),
            "internal:role=button[expanded=true]"
        );
    }

    #[test]
    fn test_get_by_role_selector_include_hidden() {
        let opts = GetByRoleOptions::default().include_hidden(true);
        assert_eq!(
            get_by_role_selector(AriaRole::Button, Some(opts)),
            "internal:role=button[include-hidden=true]"
        );
    }

    #[test]
    fn test_get_by_role_selector_property_order() {
        // All properties: checked, disabled, selected, expanded, include-hidden, level, name, pressed
        let opts = GetByRoleOptions::default()
            .pressed(true)
            .name("OK")
            .checked(false)
            .disabled(true);
        assert_eq!(
            get_by_role_selector(AriaRole::Button, Some(opts)),
            "internal:role=button[checked=false][disabled=true][name=\"OK\"i][pressed=true]"
        );
    }

    #[test]
    fn test_get_by_role_selector_name_with_special_chars() {
        let opts = GetByRoleOptions::default()
            .name("Click \"here\" now")
            .exact(true);
        assert_eq!(
            get_by_role_selector(AriaRole::Link, Some(opts)),
            "internal:role=link[name=\"Click \\\"here\\\" now\"s]"
        );
    }

    #[test]
    fn test_aria_role_as_str() {
        assert_eq!(AriaRole::Button.as_str(), "button");
        assert_eq!(AriaRole::Heading.as_str(), "heading");
        assert_eq!(AriaRole::Link.as_str(), "link");
        assert_eq!(AriaRole::Checkbox.as_str(), "checkbox");
        assert_eq!(AriaRole::Alert.as_str(), "alert");
        assert_eq!(AriaRole::Navigation.as_str(), "navigation");
        assert_eq!(AriaRole::Progressbar.as_str(), "progressbar");
        assert_eq!(AriaRole::Treeitem.as_str(), "treeitem");
    }

    #[test]
    fn highlight_options_style_setter_writes_the_field() {
        let opts = HighlightOptions::default().style("outline: 2px solid red");
        assert_eq!(opts.style.as_deref(), Some("outline: 2px solid red"));
    }
}