Docs/Authoring Tests

Finding Elements

Write element locators that stay stable as your UI changes.

Every action in a test eventually points at an element on the page. How you describe that element decides whether the test still works a month from now. This page covers the descriptions Assrt understands and the patterns that stay stable as your UI evolves.

Describe the element by role and content

Prefer descriptions that match how a user would refer to the element. "The sign in button" is far more durable than a CSS class that changes on every refactor.

yaml

# good
- click: the sign in button

# also good, when there are multiple buttons
- click: the sign in button in the top right header

# avoid: brittle selectors
- click: "css=.btn.btn-primary.header__cta--v2"

Disambiguate with nearby landmarks

If more than one element matches, add context by referring to a heading, label, or section nearby.

yaml

- click: the "Delete" button in the row for "invoice-2024-03"
- type:
    element: the email field under "Billing contact"
    text: billing@example.com

Escape hatches

When the DOM gives you something stable, use it directly. Assrt accepts explicit locators alongside natural-language ones.

testid=submit matches data-testid="submit".
role=button[name="Save"] uses the accessibility tree.
css= and xpath= fall through to raw selectors.

Rule of thumb

If an element has a stable data-testid, use it. Otherwise, describe it the way a user would.

What to avoid

Auto-generated class names (.css-1a2b3c4).
Positional selectors that depend on list order.
Long CSS chains that mirror the DOM tree.
Absolute XPath expressions.