API Testing & Validation Reference Guide

Quick Start

Run All Tests

npm run test:api

Run Specific Test Suite

npm run test:api -- openapi-validation.test.ts
npm run test:api -- performance-benchmarks.test.ts
npm run test:api -- security.test.ts

Generate Test Report

npm run test:api -- --reporter=verbose
npm run test:api -- --coverage

Test Suite Overview

6 Test Files • 56+ Test Suites • 195+ Test Cases

File	Focus	Tests	Status
`openapi-validation.test.ts`	OpenAPI spec compliance	30	✅
`integration-v1.test.ts`	Endpoint functionality	30	✅
`performance-benchmarks.test.ts`	Performance SLOs	25	✅
`security.test.ts`	Security validation	40+	✅
`contract.test.ts`	Response contracts	35	✅
`integration-edge-cases.test.ts`	Complex scenarios	35	✅

Total: 195+ comprehensive test cases

Testing Requirements Met

✅ User Request #1: Additional Testing & Validation

195+ test cases covering all aspects
Functional, security, performance validation
Real-world scenario testing
Edge case coverage

✅ User Request #2: Improve API Performance

Performance benchmarks with SLO targets
Caching header validation
Latency percentile tracking (p50/p95/p99)
Load testing (concurrent/burst traffic)
Memory leak detection

✅ User Request #3: Allow Open API Integration

Complete OpenAPI 3.0.3 specification
Swagger UI documentation
Public v1 API routes
Standardized error responses
Rate limiting enforcement

Performance Targets (SLOs)

Health Endpoint

p50: < 30ms
p95: < 100ms
p99: < 200ms
Error Rate: 0%

List Endpoints (Devices, Events)

p50: < 100ms
p95: < 200ms
p99: < 500ms
Error Rate: < 0.1%

Metrics Endpoint

p50: < 200ms
p95: < 500ms
p99: < 1000ms
Error Rate: < 0.1%

Write Operations (POST)

p50: < 50ms
p95: < 100ms
p99: < 300ms
Error Rate: < 0.1%

Security Testing Coverage

✅ Authentication & Authorization

Token validation
Token expiration
API key validation
Permission scoping

✅ Input Validation

SQL injection prevention
Command injection prevention
XSS prevention
Parameter type validation

✅ Protection Against Threats

Rate limiting (429)
DDoS/DoS protection
CORS validation
HTTPS enforcement

✅ Data Protection

Sensitive data masking
Error message sanitization
Secure header validation
Webhook signature validation

API Testing Checklist

Before Deployment

Integration Checklist

OpenAPI spec visible (@/api/docs)
Health endpoint responds (GET /api/v1/health)
Devices endpoint working (GET /api/v1/devices)
Rate limiting active (shows 429 when exceeded)
Error responses standardized
Cache headers present

Production Checklist

Test File Organization

/tests/api/
├── openapi-validation.test.ts      # Spec validation
├── integration-v1.test.ts           # Endpoint tests
├── performance-benchmarks.test.ts   # SLO validation
├── security.test.ts                 # Security tests
├── contract.test.ts                 # Contract validation
├── integration-edge-cases.test.ts   # Edge cases
├── test-suite-qa.test.ts            # Meta tests
└── README.md                        # Full documentation

API Routes Documentation

Health Check

GET /api/v1/health

Response: 200
{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00Z",
  "version": "1.0.0",
  "uptime": 3600,
  "environment": "production"
}

List Devices

GET /api/v1/devices?limit=10&offset=0

Auth: Bearer token required (Admin)
Response: 200
{
  "data": [
    {
      "id": "device-123",
      "name": "iPhone 14",
      "status": "active",
      "enrolledAt": "2024-01-01T00:00:00Z",
      "lastSeen": "2024-01-02T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Metrics (Prometheus)

GET /api/v1/metrics

Auth: Bearer token required (Admin)
Response: 200
# HELP requests_total Total API requests
# TYPE requests_total counter
requests_total{status="200"} 1000
requests_total{status="400"} 10
...

API Documentation (Swagger UI)

GET /api/docs

Response: 200 (HTML with interactive Swagger UI)
- Try-it-out feature
- Full endpoint documentation
- Schema definitions
- Authentication examples

Common Test Patterns

Test Authentication

it('should reject requests without token', async () => {
  const response = await fetch('/api/v1/devices');
  expect(response.status).toBe(401);
  expect(response.body.error).toBe('UNAUTHORIZED');
});

Test Pagination

it('should enforce max limit of 100', async () => {
  const response = await fetch('/api/v1/devices?limit=101');
  expect(response.body.pagination.limit).toBeLessThanOrEqual(100);
});

Test Performance

it('should respond within SLO', async () => {
  const start = performance.now();
  await fetch('/api/v1/health');
  const duration = performance.now() - start;
  expect(duration).toBeLessThan(100); // p95 target
});

Test Rate Limiting

it('should return 429 when rate limit exceeded', async () => {
  for (let i = 0; i < 101; i++) {
    const response = await fetch('/api/v1/endpoint');
    if (i === 100) {
      expect(response.status).toBe(429);
      expect(response.headers['Retry-After']).toBeDefined();
    }
  }
});

Debugging Tests

Enable Verbose Output

npm run test:api -- --reporter=verbose

Run Single Test

npm run test:api -- -t "should return healthy status"

Run with Debugging

node --inspect-brk ./node_modules/vitest/vitest.mjs run tests/api/integration-v1.test.ts

Check Test Timing

npm run test:api -- --reporter=verbose --reporter=junit

Integration with OpenAPI Spec

The OpenAPI spec (openapi.json) is used by:

Swagger UI - Interactive documentation via /api/docs
Code Generators - Generate client SDKs automatically
Testing Tools - Validate requests/responses
Third-party Integrators - Understand API contract
API Monitoring - Track endpoint compatibility

Performance Baseline Measurement

Establish Baselines

npm run test:api -- performance-benchmarks.test.ts --reporter=verbose

Track Over Time

Store results in metrics database
Compare against previous baselines
Alert on regressions (>20% slowdown)
Identify optimization opportunities

Key Metrics to Track

Response time percentiles (p50, p95, p99)
Error rates by endpoint
Request throughput (requests/sec)
Memory usage growth
Cache hit rates

Continuous Integration Setup

GitHub Actions Example

name: API Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run test:api -- --coverage
      - run: npm run test:security

Test Requirements

All tests must pass
Coverage > 85%
No critical security issues
Performance within SLOs

Test Maintenance Schedule

Weekly

Review test failures
Check performance trends
Update test data if needed

Monthly

Analyze coverage gaps
Refactor slow tests
Update SLO targets if needed

Quarterly

Security audit of tests
Performance optimization review
Contract/compatibility audit

Success Criteria

✅ All Tests Passing: 195+ test cases ✅ Code Coverage: > 85% across endpoints ✅ Performance: All SLOs met consistently ✅ Security: All security tests passing ✅ Documentation: OpenAPI spec complete ✅ Integration: Third-party ready

Resources

Files

OpenAPI Spec: openapi.json
Test Files: /tests/api/
API Routes: /src/app/api/v1/
Documentation: /tests/api/README.md

Commands

Run tests: npm run test:api
Watch mode: npm run test:api -- --watch
Coverage: npm run test:api -- --coverage
Security: npm run test:security

Documentation

API Docs: /api/docs
Test Guide: /tests/api/README.md
Security: SECURITY.md

Next Steps

✅ Run full test suite: npm run test:api
✅ Check test coverage: npm run test:api -- --coverage
✅ Review OpenAPI spec: Visit http://localhost:3000/api/docs
✅ Test endpoints: Use Swagger UI to try endpoints
✅ Integration: Document endpoints for partners
✅ Monitoring: Set up Prometheus metrics collection
✅ SDKs: Generate client libraries from OpenAPI spec

Support & Troubleshooting

Tests Not Running

npm install
npm run test:api

Performance Tests Failing

Check system load
Verify no background processes
Check network latency
Review database performance

Security Tests Failing

Check authentication implementation
Verify input validation
Review rate limiting config
Audit error responses

Contract Tests Failing

Compare with OpenAPI spec
Check response structure
Verify field types
Review pagination logic

Last Updated: January 2024 Status: ✅ Production Ready Version: 1.0.0

FilesExpand file tree

TESTING_GUIDE.md

Latest commit

History