Route Tester

{
  "sections": {
    "Using auth-route-tester Agent": "For comprehensive route testing after making changes:\r\n\r\n1. **Identify affected routes**\r\n2. **Gather route information**:\r\n   - Full route path (with prefix)\r\n   - Expected POST data\r\n   - Tables to verify\r\n3. **Invoke auth-route-tester agent**\r\n\r\nThe agent will:\r\n- Test the route with proper authentication\r\n- Verify database changes\r\n- Check response format\r\n- Report any issues",
    "Testing Methods": "MOCK_AUTH=true\r\nMOCK_USER_ID=test-user\r\nMOCK_USER_ROLES=admin,operations\r\n```\r\n\r\n#### Usage\r\n\r\n```bash\r\ncurl -H \"X-Mock-Auth: true\" \\\r\n     -H \"X-Mock-User: test-user\" \\\r\n     -H \"X-Mock-Roles: admin,operations\" \\\r\n     http://localhost:3002/api/protected\r\n```\r\n\r\n#### Mock Auth Requirements\r\n\r\nMock auth ONLY works when:\r\n- `NODE_ENV` is `development` or `test`\r\n- The `mockAuth` middleware is added to the route\r\n- Will NEVER work in production (security feature)",
    "Purpose": "This skill provides patterns for testing authenticated routes in the your project using cookie-based JWT authentication.",
    "Related Skills": "- Use **database-verification** to verify database changes\r\n- Use **error-tracking** to check for captured errors\r\n- Use **workflow-builder** for workflow route testing\r\n- Use **notification-sender** to verify notifications sent",
    "Testing Checklist": "Before testing a route:\r\n\r\n- [ ] Identify the service (form, email, users, etc.)\r\n- [ ] Find the correct port\r\n- [ ] Check route prefixes in `app.ts`\r\n- [ ] Construct the full URL\r\n- [ ] Prepare request body (if POST/PUT)\r\n- [ ] Determine authentication method\r\n- [ ] Run the test\r\n- [ ] Verify response status and data\r\n- [ ] Check database changes if applicable",
    "Verifying Database Changes": "mysql> SELECT * FROM WorkflowInstance WHERE id = 123;\r\nmysql> SELECT * FROM WorkflowStepInstance WHERE instanceId = 123;\r\nmysql> SELECT * FROM WorkflowNotification WHERE recipientUserId = 'user-123';\r\n```",
    "Configuration Files": "### config.ini (each service)\r\n\r\n```ini\r\n[keycloak]\r\nurl = http://localhost:8081\r\nrealm = yourRealm\r\nclientId = app-client\r\n\r\n[jwt]\r\njwtSecret = your-jwt-secret-here\r\n```\r\n\r\n### .env (each service)\r\n\r\n```bash\r\nNODE_ENV=development\r\nMOCK_AUTH=true           # Optional: Enable mock auth\r\nMOCK_USER_ID=test-user   # Optional: Default mock user\r\nMOCK_USER_ROLES=admin    # Optional: Default mock roles\r\n```",
    "When to Use This Skill": "- Testing new API endpoints\r\n- Validating route functionality after changes\r\n- Debugging authentication issues\r\n- Testing POST/PUT/DELETE operations\r\n- Verifying request/response data",
    "your project Authentication Overview": "The your project uses:\r\n- **Keycloak** for SSO (realm: yourRealm)\r\n- **Cookie-based JWT** tokens (not Bearer headers)\r\n- **Cookie name**: `refresh_token`\r\n- **JWT signing**: Using secret from `config.ini`",
    "Key Files": "- `/root/git/your project_pre/scripts/test-auth-route.js` - Main testing script\r\n- `/blog-api/src/app.ts` - Form service routes\r\n- `/notifications/src/app.ts` - Email service routes\r\n- `/auth/src/app.ts` - Users service routes\r\n- `/config.ini` - Service configuration\r\n- `/.env` - Environment variables",
    "Service Ports": "| Service | Port | Base URL |\r\n|---------|------|----------|\r\n| Users   | 3000 | http://localhost:3000 |\r\n| Projects| 3001 | http://localhost:3001 |\r\n| Form    | 3002 | http://localhost:3002 |\r\n| Email   | 3003 | http://localhost:3003 |\r\n| Uploads | 5000 | http://localhost:5000 |",
    "Common Testing Patterns": "curl -X POST http://localhost:5000/upload \\\r\n  -H \"Content-Type: multipart/form-data\" \\\r\n  -b \"refresh_token=<TOKEN>\" \\\r\n  -F \"file=@/path/to/file.pdf\" \\\r\n  -F \"metadata={\\\"description\\\":\\\"Test file\\\"}\"\r\n```",
    "Hardcoded Test Credentials": "The `test-auth-route.js` script uses these credentials:\r\n\r\n- **Username**: `testuser`\r\n- **Password**: `testpassword`\r\n- **Keycloak URL**: From `config.ini` (usually `http://localhost:8081`)\r\n- **Realm**: `yourRealm`\r\n- **Client ID**: From `config.ini`",
    "Example Test Scenarios": "```",
    "Debugging Failed Tests": "curl -H \"X-Mock-Auth: true\" \\\r\n     -H \"X-Mock-User: test-admin\" \\\r\n     -H \"X-Mock-Roles: admin\" \\\r\n     http://localhost:3002/api/protected\r\n```\r\n\r\n### 404 Not Found\r\n\r\n**Possible causes**:\r\n1. Incorrect URL\r\n2. Missing route prefix\r\n3. Route not registered\r\n\r\n**Solutions**:\r\n1. Check `app.ts` for route prefixes\r\n2. Verify route registration\r\n3. Check service is running (`pm2 list`)\r\n\r\n### 500 Internal Server Error\r\n\r\n**Possible causes**:\r\n1. Database connection issue\r\n2. Missing required fields\r\n3. Validation error\r\n4. Application error\r\n\r\n**Solutions**:\r\n1. Check service logs (`pm2 logs <service>`)\r\n2. Check Sentry for error details\r\n3. Verify request body matches expected schema\r\n4. Check database connectivity",
    "Route Prefixes": "Check `/src/app.ts` in each service for route prefixes:\r\n\r\n```typescript\r\n// Example from blog-api/src/app.ts\r\napp.use('/blog-api/api', formRoutes);          // Prefix: /blog-api/api\r\napp.use('/api/workflow', workflowRoutes);  // Prefix: /api/workflow\r\n```\r\n\r\n**Full Route** = Base URL + Prefix + Route Path\r\n\r\nExample:\r\n- Base: `http://localhost:3002`\r\n- Prefix: `/form`\r\n- Route: `/777/submit`\r\n- **Full URL**: `http://localhost:3000/blog-api/777/submit`"
  },
  "content": "### Method 1: test-auth-route.js (RECOMMENDED)\r\n\r\nThe `test-auth-route.js` script handles all authentication complexity automatically.\r\n\r\n**Location**: `/root/git/your project_pre/scripts/test-auth-route.js`\r\n\r\n#### Basic GET Request\r\n\r\n```bash\r\nnode scripts/test-auth-route.js http://localhost:3000/blog-api/api/endpoint\r\n```\r\n\r\n#### POST Request with JSON Data\r\n\r\n```bash\r\nnode scripts/test-auth-route.js \\\r\n    http://localhost:3000/blog-api/777/submit \\\r\n    POST \\\r\n    '{\"responses\":{\"4577\":\"13295\"},\"submissionID\":5,\"stepInstanceId\":\"11\"}'\r\n```\r\n\r\n#### What the Script Does\r\n\r\n1. Gets a refresh token from Keycloak\r\n   - Username: `testuser`\r\n   - Password: `testpassword`\r\n2. Signs the token with JWT secret from `config.ini`\r\n3. Creates cookie header: `refresh_token=<signed-token>`\r\n4. Makes the authenticated request\r\n5. Shows the exact curl command to reproduce manually\r\n\r\n#### Script Output\r\n\r\nThe script outputs:\r\n- The request details\r\n- The response status and body\r\n- A curl command for manual reproduction\r\n\r\n**Note**: The script is verbose - look for the actual response in the output.\r\n\r\n### Method 2: Manual curl with Token\r\n\r\nUse the curl command from the test-auth-route.js output:\r\n\r\n```bash\r\n\r\ncurl -X POST http://localhost:3000/blog-api/777/submit \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -b \"refresh_token=<COPY_TOKEN_FROM_SCRIPT_OUTPUT>\" \\\r\n  -d '{\"your\": \"data\"}'\r\n```\r\n\r\n### Method 3: Mock Authentication (Development Only - EASIEST)\r\n\r\nFor development, bypass Keycloak entirely using mock auth.\r\n\r\n#### Setup\r\n\r\n```bash\r\n\r\n### Test Form Submission\r\n\r\n```bash\r\nnode scripts/test-auth-route.js \\\r\n    http://localhost:3000/blog-api/777/submit \\\r\n    POST \\\r\n    '{\"responses\":{\"4577\":\"13295\"},\"submissionID\":5,\"stepInstanceId\":\"11\"}'\r\n```\r\n\r\n### Test Workflow Start\r\n\r\n```bash\r\nnode scripts/test-auth-route.js \\\r\n    http://localhost:3002/api/workflow/start \\\r\n    POST \\\r\n    '{\"workflowCode\":\"DHS_CLOSEOUT\",\"entityType\":\"Submission\",\"entityID\":123}'\r\n```\r\n\r\n### Test Workflow Step Completion\r\n\r\n```bash\r\nnode scripts/test-auth-route.js \\\r\n    http://localhost:3002/api/workflow/step/complete \\\r\n    POST \\\r\n    '{\"stepInstanceID\":789,\"answers\":{\"decision\":\"approved\",\"comments\":\"Looks good\"}}'\r\n```\r\n\r\n### Test GET with Query Parameters\r\n\r\n```bash\r\nnode scripts/test-auth-route.js \\\r\n    \"http://localhost:3002/api/workflows?status=active&limit=10\"\r\n```\r\n\r\n### Test File Upload\r\n\r\n```bash\r\n\r\nAfter testing routes that modify data:\r\n\r\n```bash\r\ndocker exec -it local-mysql mysql -u root -p blog_dev\r\n\r\nexport MYSQL_PWD=$(read -s -p \"Enter MySQL root password: \" && echo \"$REPLY\")\r\ndocker exec -i -e MYSQL_PWD=$MYSQL_PWD local-mysql mysql -u root blog_dev\r\nunset MYSQL_PWD\r\n\r\n\r\n### 401 Unauthorized\r\n\r\n**Possible causes**:\r\n1. Token expired (regenerate with test-auth-route.js)\r\n2. Incorrect cookie format\r\n3. JWT secret mismatch\r\n4. Keycloak not running\r\n\r\n**Solutions**:\r\n```bash\r\ndocker ps | grep keycloak\r\n\r\nnode scripts/test-auth-route.js http://localhost:3002/api/health\r\n\r\n```\r\n\r\n### 403 Forbidden\r\n\r\n**Possible causes**:\r\n1. User lacks required role\r\n2. Resource permissions incorrect\r\n3. Route requires specific permissions\r\n\r\n**Solutions**:\r\n```bash\r\n\r\n### After Creating a New Route\r\n\r\n```bash\r\nnode scripts/test-auth-route.js \\\r\n    http://localhost:3002/api/my-new-route \\\r\n    POST \\\r\n    '{\"field1\":\"value1\",\"field2\":\"value2\"}'\r\n\r\ndocker exec -i local-mysql mysql -u root -ppassword1 blog_dev \\\r\n    -e \"SELECT * FROM MyTable ORDER BY createdAt DESC LIMIT 1;\"\r\n\r\nnode scripts/test-auth-route.js \\\r\n    http://localhost:3002/api/my-new-route \\\r\n    POST \\\r\n    '{\"field1\":\"invalid\"}'\r\n\r\ncurl http://localhost:3002/api/my-new-route\r\n```\r\n\r\n### After Modifying a Route\r\n\r\n```bash\r\nnode scripts/test-auth-route.js \\\r\n    http://localhost:3002/api/existing-route \\\r\n    POST \\\r\n    '{\"existing\":\"data\"}'\r\n\r\nnode scripts/test-auth-route.js \\\r\n    http://localhost:3002/api/existing-route \\\r\n    POST \\\r\n    '{\"new\":\"field\",\"existing\":\"data\"}'",
  "id": "route-tester_diet103",
  "name": "route-tester",
  "description": "Test authenticated routes in the your project using cookie-based authentication. Use this skill when testing API endpoints, validating route functionality, or debugging authentication issues. Includes patterns for using test-auth-route.js and mock authentication."
}

---
name: route-tester
description: Test authenticated routes in the your project using cookie-based authentication. Use this skill when testing API endpoints, validating route functionality, or debugging authentication issues. Includes patterns for using test-auth-route.js and mock authentication.
---

# 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
# SECURITY WARNING: Never pass passwords directly in command line
# Use secure prompting instead:
# Option 1: Use password prompt (recommended)
docker exec -it local-mysql mysql -u root -p blog_dev

# Option 2: Use environment variable from secure source
export MYSQL_PWD=$(read -s -p "Enter MySQL root password: " && echo "$REPLY")
docker exec -i -e MYSQL_PWD=$MYSQL_PWD local-mysql mysql -u root blog_dev
unset MYSQL_PWD

# After connecting, 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 | grep keycloak

# Regenerate token
node scripts/test-auth-route.js http://localhost:3002/api/health

# Verify config.ini has correct jwtSecret
```

### 403 Forbidden

**Possible causes**:
1. User lacks required role
2. Resource permissions incorrect
3. Route requires specific permissions

**Solutions**:
```bash
# Use mock auth with admin role
curl -H "X-Mock-Auth: true" \
     -H "X-Mock-User: test-admin" \
     -H "X-Mock-Roles: admin" \
     http://localhost:3002/api/protected
```

### 404 Not Found

**Possible causes**:
1. Incorrect URL
2. Missing route prefix
3. Route not registered

**Solutions**:
1. Check `app.ts` for route prefixes
2. Verify route registration
3. Check service is running (`pm2 list`)

### 500 Internal Server Error

**Possible causes**:
1. Database connection issue
2. Missing required fields
3. Validation error
4. Application error

**Solutions**:
1. Check service logs (`pm2 logs <service>`)
2. Check Sentry for error details
3. Verify request body matches expected schema
4. Check database connectivity

## Using auth-route-tester Agent

For comprehensive route testing after making changes:

1. **Identify affected routes**
2. **Gather route information**:
   - Full route path (with prefix)
   - Expected POST data
   - Tables to verify
3. **Invoke auth-route-tester agent**

The agent will:
- Test the route with proper authentication
- Verify database changes
- Check response format
- Report any issues

## Example Test Scenarios

### After Creating a New Route

```bash
# 1. Test with valid data
node scripts/test-auth-route.js \
    http://localhost:3002/api/my-new-route \
    POST \
    '{"field1":"value1","field2":"value2"}'

# 2. Verify database
docker exec -i local-mysql mysql -u root -ppassword1 blog_dev \
    -e "SELECT * FROM MyTable ORDER BY createdAt DESC LIMIT 1;"

# 3. Test with invalid data
node scripts/test-auth-route.js \
    http://localhost:3002/api/my-new-route \
    POST \
    '{"field1":"invalid"}'

# 4. Test without authentication
curl http://localhost:3002/api/my-new-route
# Should return 401
```

### After Modifying a Route

```bash
# 1. Test existing functionality still works
node scripts/test-auth-route.js \
    http://localhost:3002/api/existing-route \
    POST \
    '{"existing":"data"}'

# 2. Test new functionality
node scripts/test-auth-route.js \
    http://localhost:3002/api/existing-route \
    POST \
    '{"new":"field","existing":"data"}'

# 3. Verify backward compatibility
# Test with old request format (if applicable)
```

## Configuration Files

### config.ini (each service)

```ini
[keycloak]
url = http://localhost:8081
realm = yourRealm
clientId = app-client

[jwt]
jwtSecret = your-jwt-secret-here
```

### .env (each service)

```bash
NODE_ENV=development
MOCK_AUTH=true           # Optional: Enable mock auth
MOCK_USER_ID=test-user   # Optional: Default mock user
MOCK_USER_ROLES=admin    # Optional: Default mock roles
```

## Key Files

- `/root/git/your project_pre/scripts/test-auth-route.js` - Main testing script
- `/blog-api/src/app.ts` - Form service routes
- `/notifications/src/app.ts` - Email service routes
- `/auth/src/app.ts` - Users service routes
- `/config.ini` - Service configuration
- `/.env` - Environment variables

## Related Skills

- Use **database-verification** to verify database changes
- Use **error-tracking** to check for captured errors
- Use **workflow-builder** for workflow route testing
- Use **notification-sender** to verify notifications sent