> For the complete documentation index, see [llms.txt](https://docs.does.qa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.does.qa/better-coverage/choose-durable-selectors.md).

# Choose durable selectors

An [Element](/getting-started/terminology.md) is the reusable page object your Test Steps use. A [Selector](/getting-started/terminology.md) is the rule inside that Element that finds it on the page. Durable Selectors keep Flows working when styles and layout change.

To create an Element (from **Assets → Elements** or **+** on a Test Step), including **Automatic** with a **Description**, see [Creating Elements](/elements/creating-elements.md). This guide is about choosing Selectors that last.

```mermaid
flowchart TD
  start["Need a durable Selector"] --> tid{"Test ID available?"}
  tid -->|Yes| useTid["Prefer Test ID"]
  tid -->|No| css{"Stable id name or attribute?"}
  css -->|Yes| useCss["Prefer CSS"]
  css -->|No| text{"Stable visible label?"}
  text -->|Yes| useText["Prefer Visible Text"]
  text -->|No| xpath["Use XPath for DOM relationships"]
```

## Prefer Selectors built for testing

| Selector type                                            | Prefer it when                                                  |
| -------------------------------------------------------- | --------------------------------------------------------------- |
| [Test ID](/elements/selector-types/test-id.md)           | The application exposes a dedicated test attribute              |
| [CSS](/elements/selector-types/css.md)                   | You have a stable id, name, or attribute that names the control |
| [Visible Text](/elements/selector-types/visible-text.md) | The user-visible label is the clearest identity                 |
| [XPath](/elements/selector-types/xpath.md)               | You need a DOM relationship the other types do not cover        |

Start with a [Test ID](/elements/selector-types/test-id.md) when your team can add one. It describes the control for testing, so styling and copy changes are less likely to break the Flow.

**Automatic** Elements generate a Selector from a **Description**. That is a fast way to start. When you need a Selector you can edit and harden, switch the Element to **Manual** and apply the preferences above. See [Creating Elements](/elements/creating-elements.md).

## Set a Manual Selector

{% stepper %}
{% step %}

## Open the Element

Open the Element from **Assets → Elements**, or edit it from the Test Step that uses it. For the full create flow, see [Creating Elements](/elements/creating-elements.md).
{% endstep %}

{% step %}

## Use Manual configuration

Set **Element configuration** to **Manual**, then pick a **Type**:

* [Test ID](/elements/selector-types/test-id.md)
* [CSS](/elements/selector-types/css.md)
* [Visible Text](/elements/selector-types/visible-text.md)
* [XPath](/elements/selector-types/xpath.md)
  {% endstep %}

{% step %}

## Enter a tight Selector

Fill **Selector**, **Text**, or **Test ID** for that type. Keep the expression tight to the control you mean to use, not a large layout wrapper.

Turn on **Dynamic Selector** only when the expression itself must include a [Value](/values/value-store.md).
{% endstep %}

{% step %}

## Reuse it in Test Steps

In [**Touch**](/test-steps/action/touch.md), [**Set value**](/test-steps/action/set-value.md), [**Check text**](/test-steps/check/check-text.md), or another step, choose the Element you saved. One Element can power many steps and Flows.
{% endstep %}
{% endstepper %}

## Habits that keep Elements durable

* Name the control, not its colour or position on the day you wrote the test.
* Prefer attributes your team owns for testing over auto-generated class names.
* When the control lives inside Shadow DOM, use a Manual [CSS](/elements/selector-types/css.md) Selector with a `>>>` prefix. See [Shadow DOM](/elements/selector-types/shadow-dom.md).
* When a step fails to find the Element, open the Element and update the Selector before you add extra [Wait](/test-steps/runner.md) steps.
* Reuse one Element across Flows instead of recreating the same Selector in each Flow.
* After an **Automatic** Description gets you moving, switch to **Manual** when you are ready to lock in a durable Selector.

{% hint style="info" %}
**Pro tip:** If [**Touch**](/test-steps/action/touch.md) reports the Element as overlapped or not clickable, fix the Selector or the page state first. Touch already waits and scrolls for the Element.
{% endhint %}

## Related

* [Creating Elements](/elements/creating-elements.md)
* [Selector Types](/elements/selector-types.md)
* [Create and run your first Flow](/getting-started/create-and-run-your-first-flow.md)
* [Test ID](/elements/selector-types/test-id.md)
* [CSS](/elements/selector-types/css.md)
* [Shadow DOM](/elements/selector-types/shadow-dom.md)
* [Visible Text](/elements/selector-types/visible-text.md)
* [XPath](/elements/selector-types/xpath.md)
* [Terminology](/getting-started/terminology.md)
* [Touch](/test-steps/action/touch.md)