API Test

API Test

Purpose: Comprehensive API endpoint testing Phases: Discover → Design → Implement → Run → Report Usage: /api-test [scope flags] [description]

Iron Laws

1. TEST EVERY STATUS CODE — Don't just test 200. Test 400, 401, 403, 404, 500. Every documented status code for an endpoint must have a test.
2. VALIDATE RESPONSE SHAPE — Assert the structure, not just the status code. A 200 with a malformed body is still a bug.
3. TEST AUTH BOUNDARIES — Every endpoint must be tested with and without valid auth. An unprotected endpoint is a security hole.

When to Use

• After implementing new API routes or handlers
• When adding authentication or authorization to endpoints
• When modifying request validation or response formats
• When auditing existing API coverage
• Before a release to verify API contract stability

When NOT to Use

• Unit testing pure functions or utilities -> /test-coverage
• Testing UI components -> /test-coverage or /add-story
• Debugging a specific API bug -> /debug
• Full CI validation -> /validate
• Load/performance testing -> dedicated performance tools

Constraints

• Create test files freely in the appropriate test directory
• Do not modify API source files without approval
• Do not call external/production APIs -- mock or use test server
• Every test file MUST include a test plan as a comment
• Tests must be safe to run in CI (no side effects on real data)

Gate Enforcement

CRITICAL: Do not mark any phase as complete without running commands and verifying output.

Note: Command examples use npm as default. Adapt to the project's package manager per ai-assistant-protocol — Project Commands.

Key gates:

1. Discovery must list all endpoints before designing tests
2. All tests must pass before generating the report
3. Report must include per-endpoint and per-status-code coverage

Scope Flags

Examples:

/api-test                                    # Test all API routes on current branch
/api-test --files=src/routes/users.ts        # Test specific route file
/api-test --route=/api/users                 # Test specific route pattern
/api-test --files=src/api/ --route=/api/auth # Test auth routes in api directory

Phase 1: Discover

Mode: Read-only -- detect framework, find routes, list endpoints.

Step 1.1: Detect API Framework

# Check package.json for framework
cat package.json | grep -E "(express|fastify|hono|@nestjs|next|nuxt|koa)"

# Check for route file patterns
find src -type f -name "*.ts" | head -30
ls src/routes/ src/api/ src/app/api/ src/pages/api/ 2>/dev/null

Identify the framework and its routing convention:

Step 1.2: Find Route Files

# Scope to --files or --route if provided, otherwise find all
grep -rn --include="*.ts" --include="*.tsx" -E "(router\.(get|post|put|patch|delete)|app\.(get|post|put|patch|delete)|@(Get|Post|Put|Patch|Delete)|export (async )?function (GET|POST|PUT|PATCH|DELETE))" src/

Step 1.3: List Endpoints

## Discovered Endpoints

| Method | Route | Handler File | Auth Required | Status |
|--------|-------|--------------|---------------|--------|
| GET | /api/users | src/routes/users.ts:12 | Yes | Untested |
| POST | /api/users | src/routes/users.ts:45 | Yes | Untested |
| GET | /api/users/:id | src/routes/users.ts:78 | Yes | Untested |
| DELETE | /api/users/:id | src/routes/users.ts:102 | Admin | Untested |

Step 1.4: Detect Auth Requirements

For each endpoint, detect auth requirements by reading the route definition and middleware chain:

1. Check for auth middleware on the route — Look for middleware like requireAuth, authenticate, isAuthenticated, @UseGuards(AuthGuard), or similar patterns applied to the route or router group.
2. Check for role/permission checks — Look for role guards like requireRole('admin'), @Roles('admin'), permission middleware, or inline role checks in the handler.
3. Classify each endpoint:
   • Public — No auth middleware. Accessible without a token.
   • Authenticated — Auth middleware present, but no role restriction. Any logged-in user can access.
   • Role-restricted — Auth middleware + role/permission check. Only specific roles can access (e.g., admin, editor).

Auth boundaries MUST be tested. Update the "Auth Required" column in the endpoints table with the detected classification (Public / Auth / Admin / etc.).

Step 1.5: Identify Nested Resources

Check for nested route patterns (e.g., /posts/:id/comments, /users/:id/orders). For each nested resource:

1. Identify the parent-child relationship (e.g., comments belong to a post)
2. Note the parent ID parameter name
3. Flag for additional test cases: valid parent, non-existent parent (404), parent-child relationship integrity

Phase 2: Design

Mode: Read-only -- categorize endpoints, plan test cases.

Step 2.1: Categorize Endpoints

For each endpoint, determine required test categories:

Step 2.2: Design Test Plan

## Test Plan: [Route Group]

### GET /api/users
| Test Case | Expected Status | Assertions |
|-----------|-----------------|------------|
| List users with valid auth | 200 | Array response, user shape |
| List users without auth | 401 | Error response shape |
| List users with pagination | 200 | Correct page size, metadata |

### POST /api/users
| Test Case | Expected Status | Assertions |
|-----------|-----------------|------------|
| Create user with valid data | 201 | User shape, id assigned |
| Create user without auth | 401 | Error response |
| Create user with missing name | 400 | Validation error, field name |
| Create user with duplicate email | 409 | Conflict error |

**Estimated tests:** N

Step 2.3: Nested Resource Test Cases

For nested resources (e.g., /posts/:id/comments):

1. Valid parent ID — Test with a parent that exists and has children. Assert the response contains only children of the specified parent.
2. Non-existent parent ID — Test with a parent ID that does not exist. Should return 404.
3. Parent-child relationship integrity — Verify that resources only return children of the specified parent, not children of other parents.

### GET /api/posts/:id/comments
| Test Case | Expected Status | Assertions |
|-----------|-----------------|------------|
| List comments for valid post | 200 | Array of comments, all belong to post |
| List comments for non-existent post | 404 | Error response |
| List comments for invalid post ID format | 400 | Validation error |
| Verify comments only belong to parent post | 200 | No comments from other posts |

Step 2.4: Approval Gate

CRITICAL: Present the test plan to the user before writing any tests.

## API Test Plan

| Endpoint | Auth | Tests Planned |
|----------|------|--------------|
| GET /api/posts | Public | happy path, empty state, pagination |
| POST /api/posts | Auth | happy path, 401 unauth, validation errors |
| GET /api/posts/:id/comments | Public | happy path, non-existent parent 404, invalid ID |
| DELETE /api/posts/:id | Admin | happy path, 401 unauth, 403 wrong role, 404 not found |

Estimated tests: N

GATE: User must approve test plan before proceeding. If the user requests changes to the test plan, update it and present again.

Phase 3: Implement

Mode: Full access -- write tests using project's test runner.

See references/api-test-patterns.md for request/response testing patterns, auth testing helpers, and error response validation. See references/api-mock-patterns.md for external service mocking strategies, database setup, and test data factories.

Step 3.0: Verify Test Infrastructure

Before writing tests, verify test infrastructure is in place:

1. Check for existing test setup — Look for existing test utilities (supertest configuration, test helpers, factories, auth helpers). If they exist, reuse them.
2. If no test setup exists, create one:
   • Test server: Import the app/server, create a test instance. Do not start on a real port -- use supertest or equivalent in-process testing.
   • Test database: Configure a test database (in-memory, transaction rollback, or isolated test DB). See references/api-mock-patterns.md for strategies.
   • Auth helpers: Create token generation helpers for each role needed (admin, user, unauthenticated). See references/api-mock-patterns.md for auth helper patterns.
   • Data factories: Create factory functions for test entities (posts, comments, users) with sensible defaults and easy overrides.
3. Ensure proper setup/teardown:
   • beforeAll — Start test server, connect to test database, run migrations/seed
   • afterAll — Disconnect database, clean up server
   • beforeEach / afterEach — Reset database state between tests (truncate tables or rollback transactions)

Step 3.1: Set Up Test Utilities (see references/api-mock-patterns.md for database strategies, MSW setup, factories, and contract testing)

Create or reuse API test helpers:

/**
 * Test Plan: API Test Utilities
 *
 * Provides authenticated request helpers, response validators,
 * and test data factories for API endpoint testing.
 */

// Helper for making authenticated requests
function authRequest(method: string, path: string, token?: string) {
  const req = request(app)[method](path);
  if (token) req.set('Authorization', `Bearer ${token}`);
  return req;
}

// Helper for validating error response shape
function expectErrorResponse(res: Response, statusCode: number) {
  expect(res.status).toBe(statusCode);
  expect(res.body).toHaveProperty('error');
  expect(res.body.error).toHaveProperty('message');
}

Step 3.2: Write Tests Per Endpoint

Organize tests by endpoint, with describe blocks per route:

describe('GET /api/users', () => {
  describe('authentication', () => {
    it('should return 401 when no auth token provided', async () => {
      const res = await request(app).get('/api/users');
      expect(res.status).toBe(401);
    });

    it('should return 403 when user lacks required role', async () => {
      const res = await request(app)
        .get('/api/users')
        .set('Authorization', `Bearer ${viewerToken}`);
      expect(res.status).toBe(403);
    });
  });

  describe('happy path', () => {
    it('should return 200 with array of users', async () => {
      const res = await request(app)
        .get('/api/users')
        .set('Authorization', `Bearer ${adminToken}`);
      expect(res.status).toBe(200);
      expect(Array.isArray(res.body.data)).toBe(true);
      expect(res.body.data[0]).toMatchObject({
        id: expect.any(String),
        name: expect.any(String),
        email: expect.any(String),
      });
    });
  });

  describe('validation', () => {
    it('should return 400 when page param is negative', async () => {
      const res = await request(app)
        .get('/api/users?page=-1')
        .set('Authorization', `Bearer ${adminToken}`);
      expect(res.status).toBe(400);
    });
  });
});

Step 3.3: Verify Test Isolation

• Each test must set up its own data (use factories or beforeEach)
• Clean up created resources in afterEach or use transactions
• Never depend on test execution order

Phase 4: Run

Mode: Execute tests and collect results.

Step 4.1: Run Tests

npm run test -- path/to/api/tests/          # All API tests
npm run test -- path/to/api/tests/users.spec.ts  # Specific endpoint

Step 4.2: Fix Failures

Common API test issues:

Phase 5: Report

Mode: Generate coverage report.

Step 5.1: Endpoint Coverage Report

## API Test Coverage Report

### Summary
- **Endpoints discovered:** N
- **Endpoints tested:** M
- **Total tests:** T
- **Pass rate:** P%

### Coverage by Endpoint

| Method | Route | Tests | Status Codes Covered | Pass |
|--------|-------|-------|----------------------|------|
| GET | /api/users | 5 | 200, 400, 401, 403 | All |
| POST | /api/users | 6 | 201, 400, 401, 409 | All |
| GET | /api/users/:id | 4 | 200, 401, 404 | All |
| DELETE | /api/users/:id | 4 | 204, 401, 403, 404 | All |

### Coverage by Status Code

| Status Code | Meaning | Tests |
|-------------|---------|-------|
| 200 | OK | 8 |
| 201 | Created | 2 |
| 204 | No Content | 1 |
| 400 | Bad Request | 5 |
| 401 | Unauthorized | 4 |
| 403 | Forbidden | 3 |
| 404 | Not Found | 3 |
| 409 | Conflict | 1 |

### Gaps
- [any untested endpoints or status codes]

### Issues Found
- [any issues discovered during testing]

Acceptance Tests

Quick Reference

Converted and distributed by TomeVault — claim your Tome and manage your conversions.