Skip to content

My5t3r10us/cesizen / .agents/skills/apex

Systematic implementation using APEX methodology (Analyze-Plan-Execute-eXamine) with optional parallel subagents, self-validation, and adversarial review. Use when implementing features, fixing bugs, or making code changes that benefit from structured workflow.

steps/step-08-run-tests.md

View on GitHub
---
name: step-08-run-tests
description: Run tests in a loop - fix issues until all pass
prev_step: steps/step-07-tests.md
next_step: steps/step-05-examine.md
---

# Step 8: Run Tests (Fix Loop)

## MANDATORY EXECUTION RULES (READ FIRST):

- πŸ›‘ NEVER give up after first failure
- πŸ›‘ NEVER start services without permission (unless auto_mode)
- πŸ›‘ NEVER infinite loop on same failure (max 3 attempts)
- βœ… ALWAYS loop until all tests pass
- βœ… ALWAYS ask user when stuck (unless auto_mode)
- βœ… ALWAYS clean up background processes
- πŸ“‹ YOU ARE A TEST RUNNER, fixing until green
- πŸ’¬ FOCUS on "Run β†’ Fail β†’ Fix β†’ Repeat until green"
- 🚫 FORBIDDEN to ignore configuration errors

## EXECUTION PROTOCOLS:

- 🎯 Check requirements before running
- πŸ’Ύ Log each test run (if save_mode)
- πŸ“– Analyze failures before fixing
- 🚫 FORBIDDEN to proceed with failing tests (without explicit skip)

## CONTEXT BOUNDARIES:

- Tests were created in step-07
- Tests may require services (DB, server)
- Failures may be code bugs or test bugs
- Loop until all green or user decides to skip

## YOUR TASK:

Run tests, fix any failures, and loop until ALL tests pass.

---

<available_state>
From previous steps:

| Variable | Description |
|----------|-------------|
| `{task_description}` | What was implemented |
| `{task_id}` | Kebab-case identifier |
| `{auto_mode}` | Auto-start servers, auto-retry |
| `{examine_mode}` | Auto-proceed to review after |
| `{save_mode}` | Save outputs to files |
| `{output_dir}` | Path to output (if save_mode) |
| Tests created | From step-07 |
| Test command | Discovered in step-07 |
</available_state>

---

## EXECUTION SEQUENCE:

### 1. Initialize Save Output (if save_mode)

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

```bash
bash {skill_dir}/scripts/update-progress.sh "{task_id}" "08" "run-tests" "in_progress"
```

Append logs to `{output_dir}/08-run-tests.md` as you work.

### 2. Check Requirements

**Identify required services:**
```bash
cat package.json | grep -A 10 '"scripts"'
```

Common: Database, dev server, Redis

**Check if running:**
```bash
curl -s http://localhost:3000 > /dev/null 2>&1 && echo "Server running"
```

### 3. Handle Missing Services

**If `{auto_mode}` = true:**
β†’ Use the test command's own server lifecycle. Playwright starts CESIZen through
`playwright.config.ts`; do not launch a detached development server by default.

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

```yaml
questions:
  - header: "Services"
    question: "Tests require services that aren't running. How proceed?"
    options:
      - label: "I'll start manually"
        description: "Give me a moment to start them"
      - label: "Start automatically"
        description: "Try to start services automatically"
      - label: "Skip tests needing services"
        description: "Only run tests that don't need services"
      - label: "Skip test step"
        description: "Continue without running tests"
    multiSelect: false
```

### 4. Run Test Loop

**CRITICAL: Loop until all pass**

```
max_attempts = 10
attempt = 0

WHILE attempt < max_attempts:
    attempt += 1

    1. Run tests
    2. If all pass β†’ EXIT (success)
    3. If failure:
       a. Analyze failure
       b. Determine: code bug or test bug?
       c. Fix the issue
       d. CONTINUE LOOP
    4. If same failure 3x β†’ ASK USER
```

**Run tests:**
```bash
bun run test
```

**Log each run:**
```
**Run #{attempt}:**
- Total: 5, Passed: 3, Failed: 2
- Fixing: {description}
```

### 5. Handle Failures

For each failing test:

```
**Analyzing:**
Test: "creates user with valid data"
File: src/auth/register.test.ts:25
Error: Expected 201, got 500
Stack: TypeError: Cannot read 'email' of undefined

**Diagnosis:** Code bug - null handling
**Fix:** Add null check in handler
```

**Fix location:**
| Error Type | Fix |
|------------|-----|
| Assertion failed | Usually code bug |
| TypeError in code | Code bug |
| TypeError in test | Test bug |
| Timeout | async/await issue |
| Import error | Missing dep |

### 6. Handle Stuck (3x same failure)

**If `{auto_mode}` = true:**
β†’ Try different approach once, then continue

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

```yaml
questions:
  - header: "Stuck"
    question: "Test keeps failing. How proceed?"
    options:
      - label: "I'll debug manually"
        description: "Let me investigate"
      - label: "Skip this test"
        description: "Mark as skip, continue others"
      - label: "Delete test"
        description: "Remove this test entirely"
      - label: "Keep trying"
        description: "Try more approaches"
    multiSelect: false
```

### 7. Handle Config Errors

| Error | Solution |
|-------|----------|
| Cannot find module | Check imports and run `bun install` |
| Connection refused | DB/server not running |
| Timeout | Increase timeout, check async |

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

```yaml
questions:
  - header: "Config"
    question: "Configuration issue detected. How proceed?"
    options:
      - label: "I'll fix manually"
        description: "Let me handle config"
      - label: "Try automatic fix"
        description: "Attempt suggested fix"
      - label: "Skip tests"
        description: "Continue without tests"
    multiSelect: false
```

### 8. Success - All Passing

```
**βœ“ All Tests Passing**

**Results:**
- Total: {count}
- Passed: {count}
- Failed: 0

**Attempts:** {count}

**Tests:**
- src/auth/register.test.ts - 3 tests
- src/utils/validation.test.ts - 2 tests
```

### 9. Complete Save Output (if save_mode)

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

Append to `{output_dir}/08-run-tests.md`:
```markdown
---
## Step Complete
**Status:** βœ“ Complete
**Tests passed:** {count}
**Attempts:** {count}
**Next:** {next step}
**Timestamp:** {ISO timestamp}
```

### 10. Determine Next Step

**If `{examine_mode}` = true:**
β†’ Load step-05-examine.md

**If `{verify_mode}` = true:**
β†’ Load step-10-verify.md

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

```yaml
questions:
  - header: "Next"
    question: "All tests passing. What next?"
    options:
      - label: "Run adversarial review"
        description: "Deep review for security/logic"
      - label: "Verify feature"
        description: "Launch app and test feature works"
      - label: "Complete workflow"
        description: "Finalize and show summary"
    multiSelect: false
```

**Else:**
β†’ Complete workflow

---

## SUCCESS METRICS:

βœ… All tests passing
βœ… No stuck failures without user decision
βœ… Config issues resolved
βœ… Services cleaned up
βœ… Clear summary

## FAILURE MODES:

❌ Giving up after first failure
❌ Infinite loop on same failure
❌ Starting services without permission
❌ Not cleaning up background processes
❌ Ignoring config errors
❌ **CRITICAL**: Not using AskUserQuestion when stuck

## RUN PROTOCOLS:

- Loop until green
- Analyze before fixing
- Ask user when stuck (3x)
- Clean up services
- Clear summary at end

---

## NEXT STEP:

Based on flags (check in order):
- **If examine_mode:** Load `./step-05-examine.md`
- **If verify_mode:** Load `./step-10-verify.md` to verify feature
- **If pr_mode:** Load `./step-09-finish.md` to create pull request
- **Otherwise:** Workflow complete - show summary

<critical>
Remember: Loop until ALL tests pass - don't give up after first failure!
</critical>
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why β€” repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" β€” or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself β€” your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall