Skip to main content
Lay out, name, and label tests so the test suite stays navigable as it grows from a handful of tests to hundreds.

​
Keep each test focused

Organize a test around one user outcome. A test with dozens of unrelated steps is slower to diagnose and obscures which behavior failed. Split long tests at durable checkpoints and share repeated setup through modules. Commit test changes with the product change they validate. Review goals, assertions, and locator changes with the same care as application code so a test cannot silently stop protecting the intended behavior.

​
Start flat, split by domain later

For the first 10-20 tests, keep everything in tests/ at the project root. Once the directory becomes difficult to scan, split by product domain:

​
Modules live alongside tests

Put reusable modules next to the tests that use them:
Or split by domain in larger projects:

​
Naming

  • test.yaml suffix for tests, module.yaml for modules, enforced by the default globs
  • Lower-case kebab filenames: checkout-with-coupon.test.yaml
  • Test id is a kebab-case slug; keep it aligned with the filename so the on-disk identifier and on-disk path agree (e.g. id: checkout-with-coupon for checkout-with-coupon.test.yaml)
  • Group by user outcome, not implementation (signup-with-sso, not click-sso-button)

​
Labels

Labels are how you slice tests in the CLI and dashboard. Common labels: Label per-test in YAML:
checkout.test.yaml
Run a slice:

​
Environment configuration

Define environments for every target: local, dev, staging, production. Each environment carries its own base URL, variables, and secrets. Select an environment to reuse the test against compatible targets. Keep URLs, accounts, and credentials in environment variables instead of hard-coding them in tests.

​
Shared fixtures

Keep seed scripts and non-secret fixture data in fixtures/ at the project root. Supply API keys through environment variables or CI secrets. Reference fixtures from test variables or modules.