API Testing

API Testing Agent

Purpose

Validates SYNTHEX API endpoints for correctness, security, and contract compliance. Tests all HTTP methods, validates Zod schemas, verifies authentication flows, and monitors for breaking changes across the Next.js App Router API surface.

When to Use

Activate this skill when:

• Creating or modifying API routes in app/api/
• Testing endpoint request/response contracts
• Validating API security (auth, rate limiting, CORS)
• Checking for breaking changes after schema updates
• Generating OpenAPI documentation from routes

When NOT to Use This Skill

• When testing UI components or visual regressions (use design or ui-ux)
• When validating database schema changes (use database-prisma)
• When reviewing general code quality without API focus (use code-review)
• When performing E2E user flow testing (use Playwright directly)
• Instead use: code-review for non-API code, database-prisma for schema work

Tech Stack

• Framework: Next.js 14+ App Router
• Language: TypeScript (strict mode)
• Database: Prisma ORM with PostgreSQL/Supabase
• Authentication: JWT with secure httpOnly cookies
• Deployment: Vercel Serverless Functions
• Validation: Zod schemas

Instructions

1. Identify target endpoints — Scan app/api/ for route handlers matching the test scope
2. Validate HTTP methods — Test all supported methods (GET, POST, PATCH, DELETE) per route
3. Test request body validation — Send valid and invalid payloads against Zod schemas
4. Verify response codes — Confirm correct status codes for success, error, and edge cases
5. Check authentication — Verify APISecurityChecker integration on protected routes
6. Test authorization — Confirm role-based access control (admin vs user vs anonymous)
7. Validate rate limiting — Verify request throttling is active and correctly configured
8. Check CORS — Confirm only whitelisted origins are allowed
9. Test error handling — Verify graceful error responses with no sensitive data leakage
10. Generate report — Output test results with pass/fail status per endpoint

Input Specification

Output Specification

Error Handling

Key Directories

• app/api/ — API route handlers
• lib/security/ — Security utilities (APISecurityChecker)
• lib/api/define-route.ts — Zod route contracts
• types/ — TypeScript interfaces

Commands

pnpm test --filter=api          # Run API tests
pnpm turbo run type-check       # Type check API routes
pnpm run lint                   # Validate schemas

Integration Points

• Works with database-prisma for data validation
• Coordinates with code-review for endpoint coverage
• Reports to client-retention for SLA monitoring

Capability Uplift — Override Defaults

NEVER mock the database in integration tests — past incidents showed that mock/prod divergence caused production failures that passing tests masked. Never skip the unauthenticated (401) or wrong-org (403) test cases — these are the most commonly exploited paths. Never use pnpm — this project uses npm.

INSTEAD every API route test suite covers these cases in this order:

describe('POST /api/resource', () => {
  it('returns 401 when unauthenticated', async () => { ... })
  it('returns 403 when accessing another org', async () => { ... })
  it('returns 400 when body is invalid', async () => { ... })
  it('returns 201 on success', async () => { ... })
})

Tests run against real Supabase (test database). The test user is a real auth.users row. The org is a real Organization row. No mocks for DB calls.

REFERENCE .claude/skills/synthex-standards/references/code-standards.md

Review Board Output

When invoked as part of the Synthex Review Board pipeline, produce output matching the schema in .claude/skills/review-board/_shared/output-schema.md.

Map this skill's findings to the shared format:

• specialist: Use this skill's name from frontmatter
• severity: Map findings to CRITICAL/HIGH/MEDIUM/LOW per .claude/skills/review-board/_shared/severity-levels.md
• confidence: Assign 0-100 based on certainty. Only findings >= 80 are shown to the developer.
• verdict: BLOCK if any CRITICAL finding exists, otherwise PASS
• Include file, line, issue, fix, and optional reference for each finding
• If no findings, return empty findings array with verdict PASS