route-tester

What this skill does

# 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"