This Claude skill is a comprehensive toolkit for testing and debugging Next.js API routes. It streamlines the development lifecycle by providing automated workflows for response validation, authentication flow verification, and troubleshooting common HTTP errors. By integrating structured checklists and performance benchmarking, it ensures that API endpoints are robust, secure, and performant.

When should I use api-testing?

api-testing is useful in the following scenarios: • Troubleshooting 500 Internal Server Errors: Systematically diagnose server-side failures by inspecting logs, verifying database connectivity, and validating environment variables. • Authentication & Authorization Testing: Validate secure routes by simulating login sequences, retrieving tokens, and testing access control for protected API endpoints. • API Response Validation: Automatically verify that endpoints return the correct JSON structures, data types, and HTTP status codes for various request methods (GET, POST, PUT, DELETE). • Performance & Concurrency Testing: Measure API response latency and evaluate how the system handles multiple simultaneous requests to ensure stability under load. • Edge Case Verification: Use the testing checklist to ensure APIs gracefully handle empty states, null values, and invalid input payloads.

name	api-testing
description	Test and debug Next.js API routes, validate responses, check authentication, and troubleshoot API errors. Use when testing API endpoints, debugging 500 errors, validating API responses, or checking authentication flows.
allowed-tools	Read, Bash, Grep, Glob

API Testing & Debugging

Expert assistance for testing and debugging Next.js API routes in the MantisNXT project.

Capabilities

API Route Testing: Test GET, POST, PUT, DELETE endpoints
Response Validation: Verify JSON responses and status codes
Authentication Testing: Validate auth flows and protected routes
Error Debugging: Diagnose 400, 401, 403, 404, 500 errors
Performance Testing: Check API response times

Quick Testing Commands

Test API Endpoints

# Test inventory API
curl -s "http://localhost:3000/api/inventory?limit=5"

# Test analytics API
curl -s "http://localhost:3000/api/analytics/recommendations?limit=5"

# Test supplier API
curl -s "http://localhost:3000/api/suppliers"

# Test stock movements
curl -s "http://localhost:3000/api/stock-movements?limit=5"

# Test health check
curl -s "http://localhost:3000/api/health"

Test with Authentication

# Login and get token
TOKEN=$(curl -s -X POST "http://localhost:3000/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}' \
  | jq -r '.token')

# Use token for authenticated request
curl -s "http://localhost:3000/api/protected-route" \
  -H "Authorization: Bearer $TOKEN"

Test POST Endpoints

# Test creating inventory item
curl -X POST "http://localhost:3000/api/inventory" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TEST-001",
    "name": "Test Product",
    "quantity": 100
  }'

# Test pricelist upload
curl -X POST "http://localhost:3000/api/suppliers/pricelists/upload" \
  -F "file=@path/to/pricelist.xlsx" \
  -F "supplierId=123"

API Routes Location

All API routes are in src/app/api/:

src/app/api/
├── auth/
│   ├── login/route.ts
│   └── status/route.ts
├── inventory/route.ts
├── suppliers/
│   ├── route.ts
│   └── pricelists/upload/route.ts
├── analytics/
│   ├── recommendations/route.ts
│   └── predictions/route.ts
├── stock-movements/route.ts
├── health/route.ts
└── upload/route.ts

Common Debugging Steps

500 Internal Server Error

Check server logs for error details
Verify database connection
Check for missing environment variables
Validate request payload matches expected schema
Look for unhandled Promise rejections

404 Not Found

Verify route file exists at correct path
Check route file exports Route Handler correctly
Ensure dynamic segments match request

401 Unauthorized

Check authentication middleware
Verify token is valid and not expired
Check Authorization header format
Validate user permissions

400 Bad Request

Validate request payload structure
Check required fields are present
Verify data types match expectations
Review validation schema

Response Format Standards

All API responses should follow this structure:

// Success response
{
  "success": true,
  "data": { /* response data */ },
  "message": "Operation completed successfully"
}

// Error response
{
  "success": false,
  "error": "Error message",
  "details": { /* additional error info */ }
}

Testing Checklist

Test happy path scenarios
Test error cases (invalid input, missing fields)
Test authentication (with/without token)
Test authorization (correct permissions)
Test edge cases (empty arrays, null values)
Verify response status codes
Check response payload structure
Test pagination parameters
Validate query parameter handling

Performance Testing

# Quick response time check
time curl -s "http://localhost:3000/api/inventory" > /dev/null

# Test concurrent requests
for i in {1..10}; do
  curl -s "http://localhost:3000/api/health" &
done
wait

Best Practices

Always test locally first before deploying
Use meaningful test data that represents real scenarios
Check logs for detailed error information
Test auth flows separately from business logic
Validate all status codes match expectations
Use TypeScript types to catch errors early
Handle all error cases gracefully

Environment Variables

Required for API testing:

DATABASE_URL=postgresql://...
NEXT_PUBLIC_API_URL=http://localhost:3000
NODE_ENV=development

api-testing

When & Why to Use This Skill

Use Cases