---
name: step-08-run-tests
description: Test runner - execute tests until all pass
prev_step: steps/step-07-tests.md
next_step: COMPLETE
---

# Step 8: Run Tests

## MANDATORY EXECUTION RULES:

- NEVER claim tests pass when they don't
- NEVER give up after first failure
- ALWAYS run full test suite
- ALWAYS fix failing tests before proceeding
- ALWAYS re-run after each fix
- YOU ARE A TEST RUNNER, ensuring green build
- FORBIDDEN to proceed with failing tests

## YOUR TASK:

Run the test suite, fix any failures, and ensure all tests pass.

---

<available_state>
From previous steps:

| Variable | Description |
|----------|-------------|
| `{task_description}` | What was implemented |
| `{task_id}` | Kebab-case identifier |
| `{auto_mode}` | Auto-fix test failures |
| `{save_mode}` | Save outputs to files |
| `{output_dir}` | Path to output (if save_mode) |
| Tests created | From step-07 |
</available_state>

---

## EXECUTION SEQUENCE:

### 1. Run Test Suite

```bash
pnpm run test
```

Or for specific tests:
```bash
pnpm run test -- --filter="auth"
```

### 2. Analyze Results

**If ALL PASS:**
Skip to step 5 (Summary).

**If FAILURES:**
For each failing test:

```markdown
## Failing Test Analysis

### Test: `validateToken should throw for expired token`
**File:** `src/auth/__tests__/handler.test.ts:25`
**Error:** `Expected: "Token expired", Received: "Invalid token"`

**Root Cause Analysis:**
- [ ] Test bug: Incorrect assertion
- [x] Code bug: Wrong error message
- [ ] Setup issue: Missing mock

**Fix:** Update error message in `validateToken` to be "Token expired"
```

### 3. Fix Failures

**Loop until green:**

```
WHILE tests failing:
  1. Identify root cause (test bug vs code bug)
  2. Apply fix
  3. Re-run tests
  4. Log result
```

**If `{auto_mode}` = true:**
Auto-fix obvious issues, continue loop.

**If `{auto_mode}` = false AND stuck:**

```yaml
questions:
  - header: "Test Fix"
    question: "Test is still failing. How should we proceed?"
    options:
      - label: "Try alternative fix (Recommended)"
        description: "Attempt a different approach"
      - label: "Skip this test"
        description: "Mark as skipped with TODO"
      - label: "Discuss the issue"
        description: "Need help understanding the failure"
    multiSelect: false
```

### 4. Verify All Green

Final run:
```bash
pnpm run test
```

**MUST show all tests passing.**

### 5. Save Output (if save_mode)

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

Write to `{output_dir}/08-run-tests.md`:
- Test run results
- Failures encountered and fixes
- Final status
- Timestamp
- Update 00-context.md Progress table: 08-run-tests -> Complete

### 6. Test Summary

```
**Test Run Complete**

**Total tests:** {count}
**Passing:** {count}
**Failed:** 0

**Iterations to green:** {count}

**Fixes applied:**
- Fixed error message in validateToken
- Fixed mock setup in route.test.ts

**All tests passing.**
```

### 7. Determine Next Step

```
IF {examine_mode} = true AND not already examined:
    -> Load step-05-examine.md

ELSE:
    -> Workflow complete - show final summary
```

---

## SUCCESS METRICS:

- All tests executed
- All failures investigated
- Root causes identified
- Fixes applied correctly
- All tests passing at end

## FAILURE MODES:

- Claiming green when tests fail
- Giving up after first failure
- Skipping tests without good reason
- Not re-running after fixes
- Not logging fix iterations

---

## NEXT STEP:

- **If examine_mode and not examined:** Load `./step-05-examine.md`
- **Otherwise:** Workflow complete - show final summary

## FINAL SUMMARY TEMPLATE:

```
**APEX Workflow Complete**

**Task:** {task_description}
**Task ID:** {task_id}

**Implementation:**
- Files modified: {count}
- Files created: {count}

**Quality:**
- Typecheck: Pass
- Lint: Pass
- Tests: {count}/{count} passing

**Review:** {examined ? "Complete" : "Skipped"}
**Findings resolved:** {count}

**Output saved:** {output_dir or "Not saved"}

**Next steps:**
- [ ] Review changes: `git diff`
- [ ] Commit: `git commit -m "{task_description}"`
- [ ] Push and create PR
```
