api-test-suite-builder

---
name: api-test-suite-builder
description: Use when the user asks to generate API tests, create integration test suites, test REST endpoints, or build contract tests.
category: Engineering
version: 1.0.0
tools: []
---

# API Test Suite Builder

Generate API test suites covering auth, input validation, error codes, pagination, file uploads, and rate limiting across common frameworks. Produce ready-to-use test code for Vitest+Supertest (Node) or Pytest+httpx (Python).

## Core Capabilities

- Route identification across a codebase
- 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 per 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 — scaffold tests before implementation (TDD)
- Legacy API with no tests — generate baseline coverage
- API contract review — verify tests match current routes
- Pre-release regression check — every route gets at least a smoke test
- Security audit prep — generate adversarial input tests

## Route Detection by Framework

- **Next.js App Router** — `route.ts`/`route.js` under `app/api`, one exported function per HTTP method (GET, POST, PUT, PATCH, DELETE).
- **Express** — routes registered via `router.get/post/put/delete/patch(path, handler)` or the equivalent on `app`.
- **FastAPI** — routes declared with `@app.<method>` or `@router.<method>` decorators.
- **Django REST Framework** — routes come from `urlpatterns` (`path`/`re_path`) plus ViewSets on a `DefaultRouter` or `SimpleRouter`.

Search the Knowledge Base for the relevant route files, then read each handler for its request schema, auth requirements, status codes, and business rules (ownership, role checks) before generating tests.

## Auth Test Matrix

| 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

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

Per route group: read the handler for schema/auth/status codes, then generate one test file applying the Auth and Input Validation matrices above. Name tests descriptively — `"returns 401 when token is expired"`, not `"auth test 3"`. Use factories/fixtures instead of hardcoded IDs. Assert response shape, not just status code. One describe block per endpoint.

## Common Pitfalls

- Testing only happy paths — 80% of bugs live in error paths
- Hardcoded test data IDs — use factories/fixtures instead
- Shared state between tests — clean up in afterEach/afterAll
- Testing implementation, not behavior
- Missing boundary tests — off-by-one errors are common in pagination/limits
- Not testing token expiry — expired tokens behave differently from invalid ones
- Ignoring Content-Type — verify the API rejects wrong content types

## Best Practices

1. One describe block per endpoint for isolated, readable failures
2. Seed minimal data — create only what the test needs
3. `beforeAll` for shared setup, `afterAll` for cleanup — not `beforeEach` for expensive ops
4. Assert specific error messages/fields, not just status codes
5. Verify sensitive fields (password, secret) never appear in responses
6. Test "missing header" separately from "invalid token"
7. Add rate limit tests last — they can interfere with other suites run in parallel