route-tester
The route-tester skill provides patterns and scripts for testing authenticated API endpoints in projects using cookie-based JWT authentication with Keycloak integration. Use this skill when validating new endpoints, verifying route functionality after modifications, debugging authentication issues, or testing POST/PUT/DELETE operations, with the recommended approach being the test-auth-route.js script that automatically handles token generation and request authentication.
git clone --depth 1 https://github.com/diet103/claude-code-infrastructure-showcase /tmp/route-tester && cp -r /tmp/route-tester/.claude/skills/route-tester ~/.claude/skills/route-testerSKILL.md
# your project Route Tester Skill
## Purpose
This skill provides patterns for testing authenticated routes in the your project using cookie-based JWT authentication.
## When to Use This Skill
- Testing new API endpoints
- Validating route functionality after changes
- Debugging authentication issues
- Testing POST/PUT/DELETE operations
- Verifying request/response data
## your project Authentication Overview
The your project uses:
- **Keycloak** for SSO (realm: yourRealm)
- **Cookie-based JWT** tokens (not Bearer headers)
- **Cookie name**: `refresh_token`
- **JWT signing**: Using secret from `config.ini`
## Testing Methods
### Method 1: test-auth-route.js (RECOMMENDED)
The `test-auth-route.js` script handles all authentication complexity automatically.
**Location**: `/root/git/your project_pre/scripts/test-auth-route.js`
#### Basic GET Request
```bash
node scripts/test-auth-route.js http://localhost:3000/blog-api/api/endpoint
```
#### POST Request with JSON Data
```bash
node scripts/test-auth-route.js \
http://localhost:3000/blog-api/777/submit \
POST \
'{"responses":{"4577":"13295"},"submissionID":5,"stepInstanceId":"11"}'
```
#### What the Script Does
1. Gets a refresh token from Keycloak
- Username: `testuser`
- Password: `testpassword`
2. Signs the token with JWT secret from `config.ini`
3. Creates cookie header: `refresh_token=<signed-token>`
4. Makes the authenticated request
5. Shows the exact curl command to reproduce manually
#### Script Output
The script outputs:
- The request details
- The response status and body
- A curl command for manual reproduction
**Note**: The script is verbose - look for the actual response in the output.
### Method 2: Manual curl with Token
Use the curl command from the test-auth-route.js output:
```bash
# The script outputs something like:
# 💡 To test manually with curl:
# curl -b "refresh_token=eyJhbGci..." http://localhost:3000/blog-api/api/endpoint
# Copy and modify that curl command:
curl -X POST http://localhost:3000/blog-api/777/submit \
-H "Content-Type: application/json" \
-b "refresh_token=<COPY_TOKEN_FROM_SCRIPT_OUTPUT>" \
-d '{"your": "data"}'
```
### Method 3: Mock Authentication (Development Only - EASIEST)
For development, bypass Keycloak entirely using mock auth.
#### Setup
```bash
# Add to service .env file (e.g., blog-api/.env)
MOCK_AUTH=true
MOCK_USER_ID=test-user
MOCK_USER_ROLES=admin,operations
```
#### Usage
```bash
curl -H "X-Mock-Auth: true" \
-H "X-Mock-User: test-user" \
-H "X-Mock-Roles: admin,operations" \
http://localhost:3002/api/protected
```
#### Mock Auth Requirements
Mock auth ONLY works when:
- `NODE_ENV` is `development` or `test`
- The `mockAuth` middleware is added to the route
- Will NEVER work in production (security feature)
## Common Testing Patterns
### Test Form Submission
```bash
node scripts/test-auth-route.js \
http://localhost:3000/blog-api/777/submit \
POST \
'{"responses":{"4577":"13295"},"submissionID":5,"stepInstanceId":"11"}'
```
### Test Workflow Start
```bash
node scripts/test-auth-route.js \
http://localhost:3002/api/workflow/start \
POST \
'{"workflowCode":"DHS_CLOSEOUT","entityType":"Submission","entityID":123}'
```
### Test Workflow Step Completion
```bash
node scripts/test-auth-route.js \
http://localhost:3002/api/workflow/step/complete \
POST \
'{"stepInstanceID":789,"answers":{"decision":"approved","comments":"Looks good"}}'
```
### Test GET with Query Parameters
```bash
node scripts/test-auth-route.js \
"http://localhost:3002/api/workflows?status=active&limit=10"
```
### Test File Upload
```bash
# Get token from test-auth-route.js first, then:
curl -X POST http://localhost:5000/upload \
-H "Content-Type: multipart/form-data" \
-b "refresh_token=<TOKEN>" \
-F "file=@/path/to/file.pdf" \
-F "metadata={\"description\":\"Test file\"}"
```
## Hardcoded Test Credentials
The `test-auth-route.js` script uses these credentials:
- **Username**: `testuser`
- **Password**: `testpassword`
- **Keycloak URL**: From `config.ini` (usually `http://localhost:8081`)
- **Realm**: `yourRealm`
- **Client ID**: From `config.ini`
## Service Ports
| Service | Port | Base URL |
|---------|------|----------|
| Users | 3000 | http://localhost:3000 |
| Projects| 3001 | http://localhost:3001 |
| Form | 3002 | http://localhost:3002 |
| Email | 3003 | http://localhost:3003 |
| Uploads | 5000 | http://localhost:5000 |
## Route Prefixes
Check `/src/app.ts` in each service for route prefixes:
```typescript
// Example from blog-api/src/app.ts
app.use('/blog-api/api', formRoutes); // Prefix: /blog-api/api
app.use('/api/workflow', workflowRoutes); // Prefix: /api/workflow
```
**Full Route** = Base URL + Prefix + Route Path
Example:
- Base: `http://localhost:3002`
- Prefix: `/form`
- Route: `/777/submit`
- **Full URL**: `http://localhost:3000/blog-api/777/submit`
## Testing Checklist
Before testing a route:
- [ ] Identify the service (form, email, users, etc.)
- [ ] Find the correct port
- [ ] Check route prefixes in `app.ts`
- [ ] Construct the full URL
- [ ] Prepare request body (if POST/PUT)
- [ ] Determine authentication method
- [ ] Run the test
- [ ] Verify response status and data
- [ ] Check database changes if applicable
## Verifying Database Changes
After testing routes that modify data:
```bash
# Connect to MySQL
docker exec -i local-mysql mysql -u root -ppassword1 blog_dev
# Check specific table
mysql> SELECT * FROM WorkflowInstance WHERE id = 123;
mysql> SELECT * FROM WorkflowStepInstance WHERE instanceId = 123;
mysql> SELECT * FROM WorkflowNotification WHERE recipientUserId = 'user-123';
```
## Debugging Failed Tests
### 401 Unauthorized
**Possible causes**:
1. Token expired (regenerate with test-auth-route.js)
2. Incorrect cookie format
3. JWT secret mismatch
4. Keycloak not running
**Solutions**:
```bash
# Check Keycloak is running
docker ps | greUse this agent when you need to debug authentication-related issues with API routes, including 401/403 errors, cookie problems, JWT token issues, route registration problems, or when routes are returning 'not found' despite being defined. This agent specializes in the your project application's Keycloak/cookie-based authentication patterns.\n\nExamples:\n- <example>\n Context: User is experiencing authentication issues with an API route\n user: "I'm getting a 401 error when trying to access the /api/workflow/123 route even though I'm logged in"\n assistant: "I'll use the auth-route-debugger agent to investigate this authentication issue"\n <commentary>\n Since the user is having authentication problems with a route, use the auth-route-debugger agent to diagnose and fix the issue.\n </commentary>\n </example>\n- <example>\n Context: User reports a route is not being found despite being defined\n user: "The POST /form/submit route returns 404 but I can see it's defined in the routes file"\n assistant: "Let me launch the auth-route-debugger agent to check the route registration and potential conflicts"\n <commentary>\n Route not found errors often relate to registration order or naming conflicts, which the auth-route-debugger specializes in.\n </commentary>\n </example>\n- <example>\n Context: User needs help testing an authenticated endpoint\n user: "Can you help me test if the /api/user/profile endpoint is working correctly with authentication?"\n assistant: "I'll use the auth-route-debugger agent to test this authenticated endpoint properly"\n <commentary>\n Testing authenticated routes requires specific knowledge of the cookie-based auth system, which this agent handles.\n </commentary>\n </example>
Use this agent when you need to test routes after implementing or modifying them. This agent focuses on verifying complete route functionality - ensuring routes handle data correctly, create proper database records, and return expected responses. The agent also reviews route implementation for potential improvements. Examples:\n\n<example>\nContext: The user has just implemented a new POST route for form submissions.\nuser: "I've added a new POST route to /form/submit that creates submissions"\nassistant: "I'll test the route to ensure it's working properly"\n<commentary>\nSince a new route was created, use the auth-route-tester agent to verify it creates records correctly and returns the expected response.\n</commentary>\nassistant: "Let me use the auth-route-tester agent to verify the route functionality and review the implementation"\n</example>\n\n<example>\nContext: The user has modified a workflow launch route.\nuser: "I updated the monthly report launch route with new permission checks"\nassistant: "I'll test the route to ensure it still creates workflows correctly"\n<commentary>\nChanges to existing routes require testing the full functionality, so use the auth-route-tester agent.\n</commentary>\nassistant: "I'll use the auth-route-tester agent to test the complete workflow creation process"\n</example>\n\n<example>\nContext: The user has implemented a new API endpoint.\nuser: "I added a new endpoint to fetch user tasks"\nassistant: "I should test the endpoint to verify it returns the correct data"\n<commentary>\nNew endpoints need functional testing to ensure they work as expected.\n</commentary>\nassistant: "Let me launch the auth-route-tester agent to verify the endpoint returns tasks properly"\n</example>
Automatically fix TypeScript compilation errors
Comprehensive backend development guide for Node.js/Express/TypeScript microservices. Use when creating routes, controllers, services, repositories, middleware, or working with Express APIs, Prisma database access, Sentry error tracking, Zod validation, unifiedConfig, dependency injection, or async patterns. Covers layered architecture (routes → controllers → services → repositories), BaseController pattern, error handling, performance monitoring, testing strategies, and migration from legacy patterns.
Use this agent when you need to review recently written code for adherence to best practices, architectural consistency, and system integration. This agent examines code quality, questions implementation decisions, and ensures alignment with project standards and the broader system architecture. Examples:\n\n<example>\nContext: The user has just implemented a new API endpoint and wants to ensure it follows project patterns.\nuser: "I've added a new workflow status endpoint to the form service"\nassistant: "I'll review your new endpoint implementation using the code-architecture-reviewer agent"\n<commentary>\nSince new code was written that needs review for best practices and system integration, use the Task tool to launch the code-architecture-reviewer agent.\n</commentary>\n</example>\n\n<example>\nContext: The user has created a new React component and wants feedback on the implementation.\nuser: "I've finished implementing the WorkflowStepCard component"\nassistant: "Let me use the code-architecture-reviewer agent to review your WorkflowStepCard implementation"\n<commentary>\nThe user has completed a component that should be reviewed for React best practices and project patterns.\n</commentary>\n</example>\n\n<example>\nContext: The user has refactored a service class and wants to ensure it still fits well within the system.\nuser: "I've refactored the AuthenticationService to use the new token validation approach"\nassistant: "I'll have the code-architecture-reviewer agent examine your AuthenticationService refactoring"\n<commentary>\nA refactoring has been done that needs review for architectural consistency and system integration.\n</commentary>\n</example>
Use this agent when you need to refactor code for better organization, cleaner architecture, or improved maintainability. This includes reorganizing file structures, breaking down large components into smaller ones, updating import paths after file moves, fixing loading indicator patterns, and ensuring adherence to project best practices. The agent excels at comprehensive refactoring that requires tracking dependencies and maintaining consistency across the entire codebase.\n\n<example>\nContext: The user wants to reorganize a messy component structure with large files and poor organization.\nuser: "This components folder is a mess with huge files. Can you help refactor it?"\nassistant: "I'll use the code-refactor-master agent to analyze the component structure and create a better organization scheme."\n<commentary>\nSince the user needs help with refactoring and reorganizing components, use the code-refactor-master agent to analyze the current structure and propose improvements.\n</commentary>\n</example>\n\n<example>\nContext: The user has identified multiple components using early returns with loading indicators instead of proper loading components.\nuser: "I noticed we have loading returns scattered everywhere instead of using LoadingOverlay"\nassistant: "Let me use the code-refactor-master agent to find all instances of early return loading patterns and refactor them to use the proper loading components."\n<commentary>\nThe user has identified a pattern that violates best practices, so use the code-refactor-master agent to systematically find and fix all occurrences.\n</commentary>\n</example>\n\n<example>\nContext: The user wants to break down a large component file into smaller, more manageable pieces.\nuser: "The Dashboard.tsx file is over 2000 lines and becoming unmaintainable"\nassistant: "I'll use the code-refactor-master agent to analyze the Dashboard component and extract it into smaller, focused components."\n<commentary>\nThe user needs help breaking down a large component, which requires careful analysis of dependencies and proper extraction - perfect for the code-refactor-master agent.\n</commentary>\n</example>
Create a comprehensive strategic plan with structured task breakdown
Update dev documentation before context compaction