Search documentation of Plushie

# Plushie.Automation.Selector (Plushie v0.7.2)

Copy Markdown View Source

Selector helpers for automation against a normalized Plushie tree.

This module resolves the selector forms accepted by `Plushie.Automation.Session` into either tree nodes or renderer interact selectors.

## Summary

### Functions

encode(selector, tree, window_id \\ nil)

Encodes an automation selector into the interact selector map expected by the renderer. An optional `window_id` scopes the selector to a specific window for multi-window apps.

find(tree, selector)

Finds the first element matching an automation selector.

find_all_with_windows(tree, arg2)

Finds all elements matching a selector, returning each with the window ID it belongs to. Used for ambiguity detection in multi-window apps.

find_node(tree, selector)

Finds the raw tree node for selectors that resolve directly to a widget.

find_window_subtree(node, window_id)

Finds the window subtree with the given window ID.

parse(selector)

Parses a window-qualified selector string into its components.

parse_selector(selector)

Parse a unified selector string into its typed form.

## Functions

# encode(selector, tree, window_id \\ nil)

    @spec encode(
      selector :: parsed_selector() | nil,
      tree :: map() | nil,
      window_id :: String.t() | nil
    ) :: map()

Encodes an automation selector into the interact selector map expected by the renderer. An optional `window_id` scopes the selector to a specific window for multi-window apps.

# find(tree, selector)

    @spec find(map() | nil, Plushie.Automation.Session.selector()) ::
      Plushie.Automation.Element.t() | nil

Finds the first element matching an automation selector.

# find_all_with_windows(tree, arg2)

    @spec find_all_with_windows(
      tree :: map() | nil,
      selector :: Plushie.Automation.Session.selector()
    ) :: [
      {Plushie.Automation.Element.t(), String.t() | nil}
    ]

Finds all elements matching a selector, returning each with the window ID it belongs to. Used for ambiguity detection in multi-window apps.

# find_node(tree, selector)

    @spec find_node(map() | nil, Plushie.Automation.Session.selector()) :: map() | nil

Finds the raw tree node for selectors that resolve directly to a widget.

# find_window_subtree(node, window_id)

    @spec find_window_subtree(map() | nil, String.t()) :: map() | nil

Finds the window subtree with the given window ID.

# parse(selector)

    @spec parse(Plushie.Automation.Session.selector()) ::
      {String.t() | nil, Plushie.Automation.Session.selector()}

Parses a window-qualified selector string into its components.

Returns `{window_id, selector}` where `window_id` is `nil` when no window qualifier is present.

## Examples

    iex> parse("main#save")
    {"main", "#save"}

    iex> parse("main#form/save")
    {"main", "#form/save"}

    iex> parse("#save")
    {nil, "#save"}

    iex> parse({:text, "Save"})
    {nil, {:text, "Save"}}

# parse_selector(selector)

    @spec parse_selector(String.t()) :: {String.t() | nil, parsed_selector()}

Parse a unified selector string into its typed form.

Supports all selector types in a single string syntax:

- `"form/email"` or `"#form/email"` - ID path selector
- `"main#form/email"` - window-qualified ID selector
- `":focused"` - state pseudo-selector
- `"main#:focused"` - window-qualified state selector
- `"[text=Save]"` - attribute selector
- `"[role=button]"` - attribute selector
- `"main#[text=Save]"` - window-qualified attribute selector

Returns `{window_id, resolved_selector}` where resolved_selector is one of: `"#id"` (string), `:focused` (atom), `{:text, "Save"}` (tuple), etc. Unknown pseudo-selectors resolve to `{:unknown_pseudo, name}` so lookup can fail without raising.