---
name: step-07-tests
description: Test analysis and creation - identify gaps and write tests
prev_step: steps/step-04-validate.md
next_step: steps/step-08-run-tests.md
---

# Step 7: Tests (Analysis & Creation)

## MANDATORY EXECUTION RULES:

- NEVER skip test coverage analysis
- NEVER write tests without reading existing patterns
- ALWAYS identify untested code paths
- ALWAYS follow existing test patterns
- ALWAYS create meaningful assertions
- YOU ARE A TEST ENGINEER, ensuring quality
- FORBIDDEN to write redundant tests

## YOUR TASK:

Analyze test coverage for the implementation, identify gaps, and create comprehensive tests.

---

<available_state>
From previous steps:

| Variable | Description |
|----------|-------------|
| `{task_description}` | What was implemented |
| `{task_id}` | Kebab-case identifier |
| `{auto_mode}` | Skip confirmations |
| `{save_mode}` | Save outputs to files |
| `{economy_mode}` | No subagents, direct tools |
| `{output_dir}` | Path to output (if save_mode) |
| Files modified | From step-03 |
</available_state>

---

## EXECUTION SEQUENCE:

### 1. Analyze Existing Tests

**If `{economy_mode}` = true:**

Use direct tools:
1. Glob for test files: `**/*.test.ts`, `**/*.spec.ts`
2. Read 1-2 similar test files for patterns
3. Identify test framework (jest, vitest, etc.)

**If `{economy_mode}` = false:**

Launch exploration agent:
```
Analyze test structure for: {task_description}

Find:
1. Test file naming conventions
2. Test patterns used (describe/it, test())
3. Mocking patterns
4. Assertion style (expect, assert)
5. Coverage of similar features
```

### 2. Identify Test Gaps

For each modified file, determine:

```markdown
## Test Coverage Analysis

### `src/auth/handler.ts`
**Existing coverage:** 60%
**New code coverage:** 0%

**Untested paths:**
- [ ] `validateToken` happy path
- [ ] `validateToken` expired token error
- [ ] `validateToken` invalid signature error

### `src/api/auth/route.ts`
**Existing coverage:** 80%
**New code coverage:** 0%

**Untested paths:**
- [ ] POST endpoint with valid credentials
- [ ] POST endpoint with invalid credentials
```

### 3. Plan Test Creation

```markdown
## Test Plan

### New Test Files
- `src/auth/__tests__/handler.test.ts`
  - Test validateToken function
  - 3 test cases planned

### Update Existing Tests
- `src/api/auth/__tests__/route.test.ts`
  - Add integration tests for new endpoint
  - 2 test cases planned

### Test Cases Summary
| File | Function | Test Case | Priority |
|------|----------|-----------|----------|
| handler.test.ts | validateToken | Valid token returns payload | High |
| handler.test.ts | validateToken | Expired token throws error | High |
| handler.test.ts | validateToken | Invalid signature throws | Medium |
```

### 4. Write Tests

Follow existing patterns:

```typescript
// Example pattern (adapt to project style)
describe('validateToken', () => {
  it('should return payload for valid token', async () => {
    // Arrange
    const validToken = createTestToken({ userId: '123' });

    // Act
    const result = await validateToken(validToken);

    // Assert
    expect(result.userId).toBe('123');
  });

  it('should throw for expired token', async () => {
    // Arrange
    const expiredToken = createTestToken({ exp: Date.now() - 1000 });

    // Act & Assert
    await expect(validateToken(expiredToken)).rejects.toThrow('Token expired');
  });
});
```

**Economy mode:** Create essential tests only:
- 1 happy path test
- 1 error case test
- Skip edge cases unless critical

### 5. Verify Tests Compile

```bash
pnpm run typecheck
```

Fix any type errors in tests.

### 6. Save Output (if save_mode)

**If `{save_mode}` = true:**

Write to `{output_dir}/07-tests.md`:
- Coverage analysis
- Test plan
- Tests created
- Timestamp
- Update 00-context.md Progress table: 07-tests -> Complete

### 7. Present Test Summary

```
**Test Creation Complete**

**New test files:** {count}
**Test cases added:** {count}

**Coverage improvement:**
- Before: {X}%
- After: {Y}% (estimated)

**Tests ready to run.**
```

**Proceed directly to step-08-run-tests.md**

---

## SUCCESS METRICS:

- Existing test patterns identified
- Coverage gaps documented
- Tests follow project conventions
- Tests compile without errors
- Meaningful assertions present

## FAILURE MODES:

- Writing tests without reading existing patterns
- Creating redundant test coverage
- Tests that don't compile
- Meaningless assertions (just checking truthy)
- Using subagents in economy_mode

---

## NEXT STEP:

Always proceed to `./step-08-run-tests.md` to run the tests.
