# `Playwright.Selectors`
[🔗](https://github.com/ftes/playwright_ex/blob/v1.65.0-rc.3/lib/playwright/api/selectors.ex#L7)

Selectors can be used to install custom selector engines. See [extensibility](https://playwright.dev/docs/extensibility) for more
information.

*Since Playwright 1.8.*

The examples alias the modules they use (`alias Playwright.{Locator, Page}`).

# `register_options`

```elixir
@type register_options() ::
  [{:content_script, boolean()}] | %{optional(:content_script) =&gt; boolean()}
```

Options of `register/4`, see its docs.

# `t`

```elixir
@type t() :: %Playwright.Selectors{
  conn: term(),
  guid: term(),
  initializer: term(),
  table: term(),
  type: term()
}
```

A `Selectors` handle. Compare handles with `==`, their fields are internal.

# `register`

```elixir
@spec register(
  t(),
  String.t(),
  String.t()
  | %{optional(:path) =&gt; String.t(), optional(:content) =&gt; String.t()},
  register_options()
) :: :ok | {:error, Playwright.error()}
```

Selectors must be registered before creating the page.

**Usage**

An example of registering selector engine that queries elements based on a tag name:

```elixir
# Must be a script that evaluates to a selector engine instance.
tag_name_engine = """
{
  // Returns the first element matching given selector in the root's subtree.
  query(root, selector) {
    return root.querySelector(selector);
  },

  // Returns all elements matching given selector in the root's subtree.
  queryAll(root, selector) {
    return Array.from(root.querySelectorAll(selector));
  }
}
"""

# Register the engine. Selectors will be prefixed with "tag=".
Playwright.selectors(playwright) |> Selectors.register!("tag", tag_name_engine)

# Or Playwright.chromium/1 or Playwright.webkit/1.
browser = BrowserType.launch!(Playwright.firefox(playwright))
page = Browser.new_page!(browser)
Page.set_content!(page, "<div><button>Click me</button></div>")

# Use the selector prefixed with its name.
button = Page.locator(page, "tag=button")
# We can combine it with built-in locators.
Page.locator(page, "tag=div") |> Locator.get_by_text("Click me") |> Locator.click!()
# Can use it in any methods supporting selectors.
button_count = Page.locator(page, "tag=button") |> Locator.count!()

Browser.close!(browser)
```

*Since Playwright 1.8.*

## Arguments

* `name` - Name that is used in selectors as a prefix, e.g. `{name: 'foo'}` enables `foo=myselectorbody` selectors. May only
  contain `[a-zA-Z0-9_]` characters.
* `script` - Script that evaluates to a selector engine instance. The script is evaluated in the page context.
  * `:path` - Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the
    current working directory. Optional.
  * `:content` - Raw script content. Optional.

## Options

* `:content_script` (`t:boolean/0`) - Whether to run this selector engine in isolated JavaScript environment. This environment has access to the same DOM, but
  not any JavaScript objects from the frame's scripts. Defaults to `false`. Note that running as a content script is not
  guaranteed when this engine is used together with other registered engines.

# `register!`

```elixir
@spec register!(
  t(),
  String.t(),
  String.t()
  | %{optional(:path) =&gt; String.t(), optional(:content) =&gt; String.t()},
  register_options()
) :: :ok
```

Like `register/4`, but returns the value and raises on error.

# `set_test_id_attribute`

```elixir
@spec set_test_id_attribute(t(), String.t()) :: :ok
```

Defines custom attribute name to be used in `Playwright.Page.get_by_test_id/2`. `data-testid` is used by default.

*Since Playwright 1.27.*

## Arguments

* `attribute_name` - Test id attribute name. To match elements with any of several attributes, pass them as a
  comma-separated list, e.g. `"data-pw,data-ti"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
