Documentation
Best Practices
Guides for authoring, running and analysing tests across web automation, API and performance — plus setup, collaboration and release notes.
Maintainable step/element design
Structure steps, elements, and data so changes are cheap and the suite stays readable.
Key takeaway: centralize locators in Elements and common flows in Step Groups, so a UI change is fixed once and applies everywhere it's used.
Reuse elements and step groups
- Store locators as reusable Elements and reference them everywhere, so a UI change is fixed in one place instead of across many steps.
- Build reusable Step Groups for common flows and compose testcases from them to avoid duplication — a change to a Step Group applies everywhere it is used.
- Compose, don't copy — nest existing Step Groups inside larger flows instead of duplicating the same step sequence in multiple testcases.
Example: create a "Login" Step Group once and reuse it across every testcase that needs to sign in.
Locate and name reliably
- Prefer stable locators (IDs, stable attributes) over brittle absolute XPaths or auto-generated selectors that break on small layout changes.
- Name steps by intent, not by raw action, so the testcase reads as a scenario.
- Name elements descriptively (e.g. UsernameInput, LoginButton) so they are easy to find and reuse.
- Keep one element per real control instead of duplicating near-identical locators, so updates stay centralized and reuse is obvious.
Variables & test data
Use variables for anything that changes, and keep dataset headers unique — headers map to variables across the project. Reference each type with its own syntax:
| Type | Reference | Use for |
|---|---|---|
| Data Sets | @{columnName} | Fixed, reusable values stored in a table (data-driven inputs) |
| Random Variables | ${__variableName} | Unique generated data (names, numbers, dates) to avoid collisions |
| Runtime Variables | ${variableName} | Values captured during a run (e.g. extracted from a response) and reused later |
- Keep dataset headers unique across the project — headers map to variables, and duplicate headers block CSV import.
- Give Random Variable functions valid inputs — length of at least 1 for alpha/number, both From and To (non-zero) for range, and a format for date/datetime.
- Isolate sensitive data — keep credentials and tokens in variables/datasets instead of hardcoding them into steps, and avoid putting real secrets in shared datasets.
Plan around referential integrity
- Elements, datasets, and columns that are referenced by testcases or step groups can't be renamed or deleted until those references are removed.
- Disable steps you're temporarily not using instead of deleting them, so you don't lose work or break references.
- Check the "where used" details before changing shared assets — the delete/update dialog lists every testcase, step group, or element that references a column or asset, so you can update usages in the right order.
- Prefer renaming over delete-and-recreate for shared assets, so existing references stay intact instead of breaking.
Related guides