API Testing Skill for nextjs-mcp-finance

Comprehensive guide for testing API endpoints in the MCP Finance Next.js application.

Quick Start

1. Start Dev Server

cd nextjs-mcp-finance
npm run dev

Wait for the server to start (usually at http://localhost:3000).

2. Test Health Endpoint

curl http://localhost:3000/api/health

Expected Response:

{
  "status": "ok",
  "timestamp": "2024-01-18T..."
}

API Endpoint Categories

Authentication Endpoints

• POST /api/auth/sign-up

  - User registration

• POST /api/auth/sign-in

  - User login

• POST /api/auth/sign-out

  - User logout

• GET /api/auth/me

  - Current user info

Stock Endpoints

• GET /api/stocks

  - List all stocks

• GET /api/stocks/[symbol]

  - Get specific stock

• POST /api/stocks/favorite

  - Add favorite stock

• DELETE /api/stocks/favorite/[id]

  - Remove favorite

Transaction Endpoints

• GET /api/transactions

  - List transactions

• POST /api/transactions

  - Create transaction

• GET /api/transactions/[id]

  - Get transaction details

Webhook Endpoints

• POST /api/webhooks/clerk

  - Clerk webhooks

• POST /api/webhooks/stripe

  - Stripe webhooks

Testing Protected Endpoints

Test without authentication (should fail)

curl -X GET http://localhost:3000/api/transactions \
  -H "Content-Type: application/json"

Expected:

Unauthorized (401)

Test with authentication

First sign in via the browser, then get your session cookie:

curl -X GET http://localhost:3000/api/transactions \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=YOUR_SESSION_COOKIE"

Testing POST Endpoints

Create Transaction Example

curl -X POST http://localhost:3000/api/transactions \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=YOUR_SESSION_COOKIE" \
  -d '{
    "symbol": "AAPL",
    "quantity": 10,
    "price": 150.00,
    "type": "buy"
  }'

Expected Response:

{
  "success": true,
  "data": {
    "id": "...",
    "symbol": "AAPL",
    "quantity": 10,
    "price": "150.00",
    "type": "buy",
    "createdAt": "..."
  }
}

Error Handling Tests

Invalid Data

curl -X POST http://localhost:3000/api/transactions \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=YOUR_SESSION_COOKIE" \
  -d '{
    "symbol": "INVALID",
    "quantity": -10
  }'

Expected:

{ "success": false, "error": "Invalid transaction data" }

Missing Required Fields

curl -X POST http://localhost:3000/api/transactions \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=YOUR_SESSION_COOKIE" \
  -d '{}'

Expected:

400

Bad Request with validation errors

Rate Limiting Tests

Send Multiple Rapid Requests

for i in {1..20}; do
  curl -X GET http://localhost:3000/api/stocks
done

Look for

429 (Too Many Requests)

responses if rate limiting is implemented.

Automated Testing Script

Create

test-api.js

in the nextjs-mcp-finance directory:

const BASE_URL = "http://localhost:3000";

async function testEndpoint(method, path, data = null, headers = {}) {
  const options = {
    method,
    headers: {
      "Content-Type": "application/json",
      ...headers,
    },
  };

  if (data) {
    options.body = JSON.stringify(data);
  }

  try {
    const response = await fetch(`${BASE_URL}${path}`, options);
    const json = await response.json();

    console.log(`✓ ${method} ${path}: ${response.status}`);
    console.log("  Response:", JSON.stringify(json, null, 2));

    return { status: response.status, data: json };
  } catch (error) {
    console.error(`✗ Error testing ${path}:`, error.message);
    return { status: 0, error: error.message };
  }
}

async function runTests() {
  console.log("🧪 Starting API Tests\n");

  // Test health endpoint
  await testEndpoint("GET", "/api/health");

  // Test unauthenticated request (should fail)
  console.log("\n📋 Testing authentication...");
  await testEndpoint("GET", "/api/transactions");

  // Add more tests here based on your endpoints
  console.log("\n✅ Tests complete");
}

runTests();

Run it:

node test-api.js

Response Format Validation Checklist

For each endpoint, verify:

• Correct Status Codes

  • 200 for successful GET
  • 201 for successful POST (created)
  • 400 for bad request
  • 401 for unauthorized
  • 404 for not found
  • 500 for server error

• Consistent Response Format

  {
    "success": boolean,
    "data": object | array (if success: true),
    "error": string (if success: false)
  }
  

• Authentication Enforced

  • Protected endpoints check auth
  • Returns 401 if not authenticated

• Input Validation

  • Invalid data is rejected
  • Clear error messages provided
  • SQL injection prevention in place

• Error Handling

  • No stack traces exposed to users
  • User-friendly error messages
  • Proper logging in server

• Performance

  • Simple queries < 500ms
  • Complex queries < 2s

Troubleshooting Common Issues

CORS Errors

Access-Control-Allow-Origin error

Solution: Check your API route headers:

export async function GET(request: Request) {
  return Response.json(data, {
    headers: {
      "Access-Control-Allow-Origin": "*",
    },
  });
}

500 Internal Server Error

Debug Steps:

1. Check Next.js dev server console for error messages
2. Verify environment variables are set
3. Check database connectivity
4. Review recent code changes

cd nextjs-mcp-finance
npm run dev
# Watch for errors in console output

Slow Response Times

Profile with curl:

curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3000/api/stocks

curl-format.txt:

time_namelookup:  %{time_namelookup}\n
time_connect:  %{time_connect}\n
time_appconnect:  %{time_appconnect}\n
time_starttransfer:  %{time_starttransfer}\n
time_total:  %{time_total}\n

401 Unauthorized on Protected Endpoints

1. Ensure Clerk is configured in .env
2. Verify session cookie is being set correctly
3. Check auth middleware in API route
4. Look at browser dev tools Network tab to see cookies

Integration with Other Tests

• E2E Tests (

  npm run test:e2e

  ): Test complete user flows through UI
• API Tests (this skill): Test endpoints directly with curl/fetch
• Unit Tests (

  npm run test

  ): Test individual functions

All should pass before deployment.

Quick Command Reference

# Health check
curl http://localhost:3000/api/health

# List stocks (public endpoint)
curl http://localhost:3000/api/stocks | jq

# Get specific stock
curl http://localhost:3000/api/stocks/AAPL | jq

# Test with verbose output
curl -v http://localhost:3000/api/health

# Save response to file
curl http://localhost:3000/api/stocks > response.json

# Test with custom headers
curl -H "Authorization: Bearer TOKEN" http://localhost:3000/api/stocks

# Test with POST data
curl -X POST http://localhost:3000/api/endpoint \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Pro Tips

• Use

  jq

  to format JSON responses:

  curl ... | jq

• Use Postman or Insomnia for interactive testing with saved requests
• Keep curl commands in a test file for repeatability
• Log API responses when debugging issues
• Test both success and error cases for each endpoint
• Verify error messages are helpful but don't expose sensitive info

Next Steps After API Testing

1. If all APIs pass, run full test suite:

   npm run test

2. Run E2E tests:

   npm run test:e2e

3. Check code quality:

   npm run lint

4. Build for production:

   npm run build

5. Use deployment-checklist skill before deploying

---

For more information about the project structure and setup, see the codebase-navigator skill.