Power Next.js API Tester

Generate comprehensive test suites for Next.js API routes including unit tests, authentication checks, input validation, error handling, performance benchmarks, and cURL/HTTPie commands.

When to Use This Command

Run this command when you need to test a Next.js API route thoroughly with auto-generated test cases and manual testing commands.

• You built a new API route and need a complete test suite covering all HTTP methods
• You want to generate cURL and HTTPie commands for manual API testing
• You need authentication, validation, and error handling tests generated automatically
• You want a Postman or Thunder Client collection for your API routes

Use it also when:

• You need to set up Jest or Vitest configuration for API route testing
• You want performance benchmarks including response time and concurrency tests

Quick Start

Copy
# .claude/commands/power-nextjs-api-tester.md
name: power-nextjs-api-tester
description: Generate comprehensive API route test suites
arguments:
  route: API route path (e.g., /api/users)

Copy
# Generate tests for a specific API route
claude power-nextjs-api-tester "/api/users"

Expected output:
API Route Analysis: /api/users
  File: app/api/users/route.ts
  Methods: GET, POST
  Auth: Bearer token required
  Validation: Zod schema detected

Generated:
  - __tests__/api/users.test.ts (42 test cases)
  - test/fixtures/userData.ts (mock data)
  - curl-commands.sh (8 commands)
  - postman-collection.json

Core Concepts

Concept	Description
Route Discovery	Auto-detect the route file, HTTP methods, and middleware
Test Categories	Functionality, auth, validation, errors, performance
Mock Data	Generated test fixtures matching your route's schema
cURL Commands	Ready-to-run terminal commands for manual API testing
Collection Export	Postman/Thunder Client importable collections

Test Generation Pipeline:
  Route File ──> Analyze Handler ──> Detect Patterns
                                          │
            ┌─────────┬─────────┬─────────┼─────────┐
            v         v         v         v         v
         Basic     Auth     Validation  Error    Perf
         Tests     Tests     Tests     Tests    Tests

Configuration

Parameter	Default	Description
route	required	API route path (e.g., /api/users)
framework	auto-detect	Test framework: jest or vitest
coverage	70%	Minimum coverage threshold for all metrics
include-perf	true	Include performance benchmark tests
collection	postman	Export format: postman or thunder-client

Best Practices

1. Run tests in watch mode during development -- Use npm run test:api -- --watch to re-run tests automatically as you modify the API route handler.

2. Set up test database isolation -- Use beforeEach to reset database state between tests, preventing test interdependencies and flaky results.

3. Test both valid and invalid inputs -- The generated suite includes both happy-path and error-path tests. Review and customize the invalid input examples for your domain.

4. Use the generated cURL commands for debugging -- When a test fails, use the corresponding cURL command to reproduce the issue manually and inspect the response.

5. Maintain test fixtures separately -- Keep mock data in test/fixtures/ rather than inline in test files. This makes it easier to update test data across multiple test suites.

Common Issues

1. Route file not found -- The tester searches both App Router (app/api/) and Pages Router (pages/api/) directories. Verify your route file exists at the expected path.

2. Test framework not detected -- If neither jest.config.js nor vitest.config.js is found, the generator defaults to Jest. Install and configure your preferred framework first.

3. Authentication tests fail with mock tokens -- The generated auth tests use placeholder tokens. Replace YOUR_TOKEN_HERE with valid test credentials or mock the auth middleware.