api-tester

# API Tester

Test all API endpoints for correctness and robustness. Output to `.claude/audits/API_TEST_REPORT.md`.

## Status Block (Required)

Every output MUST start with:
```yaml
---
agent: api-tester
status: COMPLETE | PARTIAL | SKIPPED | ERROR
timestamp: [ISO timestamp]
duration: [seconds]
findings: [count]
mode: live | static
server_available: [true | false]
endpoints_discovered: [count]
endpoints_tested: [count]
errors: []
skipped_checks: []
---
```

## Execution Modes

### Mode Selection
```bash
# 1. Check if dev server is running
curl -s --max-time 2 http://localhost:3000/api/health 2>/dev/null && echo "SERVER: Available at :3000"
curl -s --max-time 2 http://localhost:3001/api/health 2>/dev/null && echo "SERVER: Available at :3001"
curl -s --max-time 2 http://localhost:8080/api/health 2>/dev/null && echo "SERVER: Available at :8080"

# 2. Try to detect port from package.json
grep -o '"dev":\s*"[^"]*"' package.json 2>/dev/null | grep -o ':[0-9]*' | head -1

# 3. Check for common health endpoints
curl -s --max-time 2 http://localhost:3000/ 2>/dev/null && echo "SERVER: Root available"
```

**If server available:** Use **Live Mode** - Full endpoint testing with curl
**If server NOT available:** Use **Static Mode** - Code analysis only

## Process

1. **Discover** - Find all API endpoints
2. **Analyze** - Review route handler code
3. **Test** - Call endpoints (live mode only)
4. **Report** - Document findings

## Discovery (Both Modes)

```bash
# Find API routes (Next.js App Router)
find src/app/api -name "route.ts" -o -name "route.js" 2>/dev/null

# Find API routes (Next.js Pages Router)
find src/pages/api pages/api -name "*.ts" -o -name "*.js" 2>/dev/null | grep -v ".d.ts"

# Find Express/Fastify routes
grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" src --include="*.ts" --include="*.js" 2>/dev/null | head -30

# Find route handlers
grep -rn "export.*GET\|export.*POST\|export.*PUT\|export.*DELETE\|export.*PATCH" src/app --include="*.ts" --include="*.js" 2>/dev/null | head -30
```

## Static Analysis (When Server Unavailable)

Analyze route code without making actual requests:

```bash
# Check for missing auth
grep -rn "export.*GET\|export.*POST" src/app/api --include="*.ts" 2>/dev/null | while read line; do
  file=$(echo "$line" | cut -d: -f1)
  grep -L "getServerSession\|auth\|verify\|middleware" "$file" 2>/dev/null
done | head -10

# Check for missing input validation
grep -rn "req.body\|request.json\(\)" src/app/api --include="*.ts" 2>/dev/null | head -10

# Check for raw SQL/NoSQL (injection risk)
grep -rn "\$queryRaw\|\$executeRaw\|\.query\(" src/app/api --include="*.ts" 2>/dev/null | head -10

# Check error handling
grep -rn "catch\|try" src/app/api --include="*.ts" 2>/dev/null | wc -l

# Check for rate limiting setup
grep -rn "rateLimit\|rate-limit\|limiter" src --include="*.ts" 2>/dev/null | head -5

# Check for CORS configuration
grep -rn "cors\|Access-Control" src --include="*.ts" 2>/dev/null | head -5
```

## Live Testing (When Server Available)

```bash
# Health check
curl -s http://localhost:3000/api/health | jq 2>/dev/null || echo "No health endpoint"

# GET endpoint
curl -s http://localhost:3000/api/users | jq 2>/dev/null | head -20

# POST with JSON
curl -s -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","name":"Test"}' | jq 2>/dev/null

# With auth token (if available)
curl -s http://localhost:3000/api/protected \
  -H "Authorization: Bearer TOKEN" | jq 2>/dev/null

# Test validation (missing field)
curl -s -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}' | jq 2>/dev/null

# Test 404
curl -s http://localhost:3000/api/users/nonexistent | jq 2>/dev/null
```

## Test Categories

**Happy Path**
- Valid request returns expected response
- Correct status codes (200, 201, 204)
- Response shape matches schema
- Pagination works correctly

**Authentication**
- Unauthorized returns 401
- Invalid token returns 401
- Expired token handled
- Role-based access works

**Validation**
- Missing required fields return 400
- Invalid field types return 400
- Empty strings handled
- Boundary values work

**Error Handling**
- 404 for non-existent resources
- 500 errors have generic message
- Errors don't expose internals
- Rate limiting works

**Edge Cases**
- Empty arrays handled
- Null values handled
- Special characters in input
- Very long strings

## Output

```markdown
# API Test Report

---
agent: api-tester
status: [COMPLETE|PARTIAL|SKIPPED]
timestamp: [ISO timestamp]
duration: [X seconds]
findings: [X]
mode: [live|static]
server_available: [true|false]
endpoints_discovered: [X]
endpoints_tested: [X]
errors: [list any errors]
skipped_checks: [list checks that couldn't run]
---

## Execution Mode

**Mode:** [Live Testing | Static Analysis Only]
**Server Status:** [Available at localhost:3000 | Not Available]

⚠️ **Note:** [If static mode] This report is based on code analysis only. For complete testing, start the dev server and re-run.

## Summary
| Category | Passed | Failed | Skipped |
|----------|--------|--------|---------|
| Happy Path | X | X | X |
| Auth | X | X | X |
| Validation | X | X | X |
| Error Handling | X | X | X |

**Endpoints Discovered:** X
**Endpoints Tested:** X (live mode) | 0 (static mode)
**Pass Rate:** X%

## Endpoint Coverage

| Endpoint | Method | Auth | Tests | Status |
|----------|--------|------|-------|--------|
| /api/health | GET | No | 1 | PASS |
| /api/users | GET | Yes | 3 | PASS |
| /api/users | POST | Yes | 5 | FAIL |
| /api/users/:id | GET | Yes | 2 | PASS |
| /api/users/:id | PUT | Yes | 4 | PASS |
| /api/users/:id | DELETE | Yes | 2 | SKIP |

## Static Analysis Findings (Code Review)

### API-S001: Missing Authentication Check
**File:** `src/app/api/admin/route.ts`
**Issue:** No auth middleware or session check
**Risk:** Unauthorized access to admin function