Writing Tests

Locators

Target elements by user-visible intent first, then use explicit locators when ambiguity requires it.

Page8 of 28

Reading timeCalculating

Sections0

Documentation goal: this page is written as practical product documentation, with enough context to help a real QA engineer decide how to use the feature in a maintainable test suite.

Intent first

OrbitTest starts with the same clues a user has: visible text, form labels, button names, roles, and accessible names. This keeps tests aligned with behavior instead of DOM structure.

When explicit locators are useful

Explicit locators are still necessary when the screen contains repeated text or when a component has no useful accessible name. Use them intentionally, preferably with stable attributes such as test IDs.

Avoid brittle selectors

Avoid selectors that depend on layout position, generated classes, or nested DOM depth. They tend to fail during harmless refactors and make the suite noisy.

await orbit.click('Save changes');
await orbit.type('Email address', 'qa@example.com');
await orbit.click(orbit.getByAttribute('data-testid', 'profile-submit'));
await orbit.click(orbit.getByRole('button', 'Delete'));

Practical checklist

Keep the workflow readable enough that a QA engineer, developer, or product teammate can understand the intent without opening application source code.
Prefer user-visible names, stable configuration, and clear evidence over hidden assumptions or brittle implementation details.
Run the smallest useful check locally before adding it to CI, then verify that failures produce screenshots, logs, traces, or reports that explain what happened.
Review this part of the suite regularly so outdated examples, stale setup, and obsolete workarounds do not reduce trust in the automation.

Common mistakes to avoid

Do not add automation only to increase test count. Each page and test should protect a clear user journey, release risk, or debugging need.
Do not hide important behavior inside helpers so deeply that the test no longer explains what the user is doing.
Do not rely on fixed sleeps when the application can expose a meaningful ready state such as visible text, URL change, element availability, or completed evidence capture.
Do not ignore failing artifacts. A report, screenshot, trace, or log entry should feed back into better product code, better waits, or clearer test data setup.

Was this page useful?

Your response is saved in this browser and helps shape the docs experience.