# Test Organization (Humand E2E)

Organize tests by module and classify them with standard tags and annotations.

## Directory conventions

- Specs (planning): `specs/{module}.spec.md`
- Tests: `tests/{module}/*.spec.ts`
- Page objects: `pages/*Page.ts`
- Fixtures: `fixtures/*.fixture.ts`

## Spec structure

Prefer this order in `specs/{module}.spec.md`:

1. Title
2. Owner
3. Module
4. Base URL
5. `## Preconditions`
6. `## Smoke`
7. `## Regression`
8. `## Functional`
9. `## Data dependencies / notes`

## Naming

- Test file: `{feature}.spec.ts`
- `describe`: `'{Module} - {Feature}'`
- Test name: action-focused sentence (`creates a new cycle and navigates to wizard`)

## Tags (execution filtering)

- `@smoke`: critical path
- `@regression`: behavior that must remain stable
- `@functional`: broader user journeys
- `@slow`: tests with longer runtime

Examples:

```ts
test('page loads', { tag: ['@smoke'] }, async () => {});
test.describe('Goals - Cycle Wizard', { tag: ['@regression'] }, () => {});
```

## Annotations (metadata)

Standard metadata:

- `owner`
- `module`
- `severity`
- optional: `jira`, `issue`

Example:

```ts
test.describe('Goals - Cycles List', {
  annotation: [
    { type: 'owner', description: 'christian.torres' },
    { type: 'module', description: 'goals' },
    { type: 'severity', description: 'critical' },
  ],
}, () => {});
```

## Stability rules

- Keep each test independent.
- Do not rely on test execution order.
- Use explicit setup/teardown when test data is required.
- Mutating tests should create their own unique data instead of relying on seeded rows.