> ## Documentation Index
> Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Test organization

> Directory layouts, naming, and labeling patterns that scale past a handful of tests.

How to lay out, name, and label tests so the test suite stays navigable as it
grows from a handful of tests to hundreds.

## 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**:

```text theme={null}
tests/
  auth/
    login.test.yaml
    signup.test.yaml
  billing/
    checkout.test.yaml
  onboarding/
    welcome.test.yaml
```

## Modules live alongside tests

Put reusable [modules](/core-concepts/modules) next to the tests that use them:

```text theme={null}
tests/
  modules/
    login.module.yaml
    seed-org.module.yaml
  billing/
    checkout.test.yaml
```

Or split by domain in larger projects:

```text theme={null}
tests/
  auth/
    login.module.yaml
    login.test.yaml
```

## Naming

* `test.yaml` suffix for tests, `module.yaml` for modules, enforced by the
  default [globs](/configuration/test-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            | Meaning                                 |
| ---------------- | --------------------------------------- |
| `smoke`          | Critical paths run on every CI          |
| `regression`     | Full nightly run                        |
| `slow`           | Tests > 2 min; skipped on pull requests |
| `owner:payments` | Ownership for notifications             |

Label per-test in YAML:

```yaml checkout.test.yaml theme={null}
fileType: momentic/test/v2
id: checkout
labels: [smoke, owner:payments]
steps: ...
```

Run a slice:

```bash theme={null}
npx momentic run --labels smoke
```

## Environment configuration

Define [environments](/configuration/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.