API Test Suite Builder

Tier: POWERFUL

Category: Engineering

Domain: Testing / API Quality

---

Overview

Scans API route definitions across frameworks (Next.js App Router, Express, FastAPI, Django REST) and

auto-generates comprehensive test suites covering auth, input validation, error codes, pagination, file

uploads, and rate limiting. Outputs ready-to-run test files for Vitest+Supertest (Node) or Pytest+httpx

(Python).

---

Core Capabilities

• Route detection — scan source files to extract all API endpoints
• Auth coverage — valid/invalid/expired tokens, missing auth header
• Input validation — missing fields, wrong types, boundary values, injection attempts
• Error code matrix — 400/401/403/404/422/500 for each route
• Pagination — first/last/empty/oversized pages
• File uploads — valid, oversized, wrong MIME type, empty
• Rate limiting — burst detection, per-user vs global limits

---

When to Use

• New API added — generate test scaffold before writing implementation (TDD)
• Legacy API with no tests — scan and generate baseline coverage
• API contract review — verify existing tests match current route definitions
• Pre-release regression check — ensure all routes have at least smoke tests
• Security audit prep — generate adversarial input tests

---

Route Detection

Next.js App Router

# Find all route handlers
find ./app/api -name "route.ts" -o -name "route.js" | sort

Extract HTTP methods from each route file
grep -rn "export async function\|export function" app/api/**/route.ts | \
  grep -oE "(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)" | sort -u

Full route map
find ./app/api -name "route.ts" | while read f; do
  route=$(echo $f | sed 's|./app||' | sed 's|/route.ts||')
  methods=$(grep -oE "export (async )?function (GET|POST|PUT|PATCH|DELETE)" "$f" | \
    grep -oE "(GET|POST|PUT|PATCH|DELETE)")
  echo "$methods $route"
done

Express

# Find all router files
find ./src -name ".ts" -o -name ".js" | xargs grep -l "router\.\(get\|post\|put\|delete\|patch\)" 2>/dev/null

Extract routes with line numbers
grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" \
  src/ --include=".ts" | grep -oE "(get|post|put|delete|patch)\(['\"][^'\"]['\"]"

Generate route map
grep -rn "router\.\|app\." src/ --include="*.ts" | \
  grep -oE "\.(get|post|put|delete|patch)\(['\"][^'\"]+['\"]" | \
  sed "s/\.\(.\)('\(.\)'/\U\1 \2/"

FastAPI

# Find all route decorators
grep -rn "@app\.\|@router\." . --include="*.py" | \
  grep -E "@(app|router)\.(get|post|put|delete|patch)"

Extract with path and function name
grep -rn "@\(app\|router\)\.\(get\|post\|put\|delete\|patch\)" . --include="*.py" | \
  grep -oE "@(app|router)\.(get|post|put|delete|patch)\(['\"][^'\"]*['\"]"

Django REST Framework

# urlpatterns extraction
grep -rn "path\|re_path\|url(" . --include="*.py" | grep "urlpatterns" -A 50 | \
  grep -E "path\(['\"]" | grep -oE "['\"][^'\"]+['\"]" | head -40

ViewSet router registration
grep -rn "router\.register\|DefaultRouter\|SimpleRouter" . --include="*.py"

---

Test Generation Patterns

Auth Test Matrix

For every authenticated endpoint, generate:

| Test Case | Expected Status |

|-----------|----------------|

| No Authorization header | 401 |

| Invalid token format | 401 |

| Valid token, wrong user role | 403 |

| Expired JWT token | 401 |

| Valid token, correct role | 2xx |

| Token from deleted user | 401 |

Input Validation Matrix

For every POST/PUT/PATCH endpoint with a request body:

| Test Case | Expected Status |

|-----------|----------------|

| Empty body {} | 400 or 422 |

| Missing required fields (one at a time) | 400 or 422 |

| Wrong type (string where int expected) | 400 or 422 |

| Boundary: value at min-1 | 400 or 422 |

| Boundary: value at min | 2xx |

| Boundary: value at max | 2xx |

| Boundary: value at max+1 | 400 or 422 |

| SQL injection in string field | 400 or 200 (sanitized) |

| XSS payload in string field | 400 or 200 (sanitized) |

| Null values for required fields | 400 or 422 |

---

Example Test Files

→ See references/example-test-files.md for details

Generating Tests from Route Scan

When given a codebase, follow this process:

• Scan routes using the detection commands above
• Read each route handler to understand:

- Expected request body schema

- Auth requirements (middleware, decorators)

- Return types and status codes

- Business rules (ownership, role checks)

• Generate test file per route group using the patterns above
• Name tests descriptively: "returns 401 when token is expired" not "auth test 3"
• Use factories/fixtures for test data — never hardcode IDs
• Assert response shape, not just status code

---

Common Pitfalls

• Testing only happy paths — 80% of bugs live in error paths; test those first
• Hardcoded test data IDs — use factories/fixtures; IDs change between environments
• Shared state between tests — always clean up in afterEach/afterAll
• Testing implementation, not behavior — test what the API returns, not how it does it
• Missing boundary tests — off-by-one errors are extremely common in pagination and limits
• Not testing token expiry — expired tokens behave differently from invalid ones
• Ignoring Content-Type — test that API rejects wrong content types (xml when json expected)

---

Best Practices

• One describe block per endpoint — keeps failures isolated and readable
• Seed minimal data — don't load the entire DB; create only what the test needs
• Use beforeAll for shared setup, afterAll for cleanup — not beforeEach for expensive ops
• Assert specific error messages/fields, not just status codes
• Test that sensitive fields (password, secret) are never in responses
• For auth tests, always test the "missing header" case separately from "invalid token"
• Add rate limit tests last — they can interfere with other test suites if run in parallel