API Testing Guide

Comprehensive API validation covering functional correctness, security, and performance across all services and third-party integrations.

Test Strategy

When setting up API tests for a new service, create a base test class with shared auth, retry logic, and response validation helpers before writing individual test cases. This prevents duplicated setup code and ensures consistent assertion patterns across the suite.

See Test Suite for the full vitest + fetch test suite code.

Security Checklist

Cover the OWASP API Security Top 10 in every test suite:

• Authentication/Authorization: Test that unauthenticated requests return 401, and unauthorized requests return 403. Verify token expiration, refresh flows, and privilege escalation attempts.

• Input sanitization: Test SQL injection, XSS payloads, and command injection via query parameters, request bodies, and headers.

• Rate limiting: Verify that burst requests trigger 429 responses. Test per-user and per-IP limits.

• Mass assignment: Send unexpected fields in POST/PATCH requests and verify they are ignored.

• BOLA (Broken Object-Level Authorization): Request resources belonging to other users and verify 403/404 responses.

• SSRF: Test URL parameters with internal network addresses and verify they are rejected.

• Data encryption: Verify sensitive data is not returned in plaintext (e.g., passwords, tokens in response bodies).

Load Testing

Performance thresholds

• API response times under 200ms for 95th percentile

• Error rates below 0.1% under normal load

• System handles 10x normal traffic capacity without degradation

• Cache effectiveness validated (hit rates, performance impact)

Tools

• k6: Script-based load testing, integrates with CI/CD. Use for sustained load and spike tests.

• Locust: Python-based, good for complex user flows. Use for scenario-based load profiles.

• Run load tests in CI on every release branch. Flag any test exceeding 30 seconds for optimization or move to a nightly pipeline.

Endpoint Coverage

Maintain a test matrix mapping every route (method + path) to at least:

• One functional test (happy path)

• One negative-input test (validation, malformed data)

• One auth/authz test (missing token, wrong role)

Review the coverage matrix each sprint. Any gaps are flagged in CI as warnings.

Workflow

• API Discovery: Catalog all APIs with complete endpoint inventory. Analyze specs and contract requirements.

• Test Strategy: Design test strategy covering functional, performance, and security. Create test data management plan.

• Implementation: Build automated test suites (vitest + fetch, REST Assured, k6). Integrate into CI/CD with quality gates.

• Monitoring: Set up production API monitoring. Analyze results and continuously optimize test strategy.

Reference

HTTP Status Code Cheat Sheet

Code When to assert

200 Successful GET, PATCH

201 Successful POST (resource created)

204 Successful DELETE

400 Invalid input, malformed request

401 Missing or expired authentication

403 Authenticated but unauthorized

404 Resource not found

409 Conflict (duplicate resource)

429 Rate limit exceeded

500 Server error (should never appear in production tests)

CI Integration

• Full test suite should complete in under 15 minutes.

• Run functional and security tests on every pull request.

• Run load tests on release branches.

• Any test exceeding 30 seconds is flagged for optimization.

Scripts

scripts/discover_endpoints.sh

Scan a project directory for API endpoint definitions across common frameworks: Express.js, FastAPI, Flask, and Spring Boot. Outputs a Markdown table with HTTP method, path, source file:line, and framework. Useful for building an endpoint coverage matrix.

scripts/discover_endpoints.sh ./src scripts/discover_endpoints.sh /path/to/fastapi-project

scripts/generate_test_skeleton.py

Generate test skeleton files from an OpenAPI/Swagger JSON specification. Produces test stubs for each endpoint with method, path, expected status codes, and example request bodies. Supports pytest, vitest, and Playwright output formats.

scripts/generate_test_skeleton.py --spec openapi.json --framework vitest scripts/generate_test_skeleton.py --spec swagger.json --framework pytest