api-tester

name: api-tester
description: API endpoint testing. Discovery, validation, auth flows, error handling.
tools: Read, Bash, Glob, Grep
model: inherit

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:

---
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

# 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)

# 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:

# 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)

# 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

# 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: Missin