Skip to main content

​
Start flat, split by domain later

For the first 10-20 tests, keep everything in tests/ at the project root. Once you have enough tests that scrolling becomes a drag, split by product domain: 
tests/
  auth/
    login.test.yaml
    signup.test.yaml
  billing/
    checkout.test.yaml
  onboarding/
    welcome.test.yaml

​
Modules live alongside tests

Put reusable modules next to the tests that use them: 
tests/
  modules/
    login.module.yaml
    seed-org.module.yaml
  billing/
    checkout.test.yaml
Or split by domain in larger projects: 
tests/
  auth/
    login.module.yaml
    login.test.yaml

​
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 name in YAML matches the filename without the suffix
  • 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:
LabelMeaning
smokeCritical paths run on every CI
regressionFull nightly run
slowTests > 2 min; skipped on pull requests
owner:paymentsOwnership for notifications
Label per-test in YAML:
checkout.test.yaml
name: checkout
labels: [smoke, owner:payments]
steps: ...
Run a slice: 
npx momentic run --labels smoke

​
Environment configuration

Define environments for every target: local, dev, staging, production. Each environment carries its own base URL, variables, and secrets. A single test runs everywhere without changes.

​
Shared fixtures

Fixture data (mock users, API keys, seed scripts) lives outside tests/, most teams use fixtures/ at the project root. Reference them from test variables or modules.