route-tester

your project 路由测试技能

用途

此技能提供使用基于 Cookie 的 JWT 身份验证来测试 your project 中受保护路由的方法。

何时使用此技能

• 测试新的 API 端点
• 在更改后验证路由功能
• 调试身份验证问题
• 测试 POST/PUT/DELETE 操作
• 验证请求/响应数据

your project 身份验证概览

your project 使用：

• Keycloak 进行 SSO（realm：yourRealm）
• 基于 Cookie 的 JWT 令牌（而非 Bearer 请求头）
• Cookie 名称：refresh_token
• JWT 签名：使用 config.ini 中的密钥

测试方法

方法 1：test-auth-route.js（推荐）

test-auth-route.js 脚本会自动处理所有身份验证相关的复杂操作。

位置：/root/git/your project_pre/scripts/test-auth-route.js

基本 GET 请求

node scripts/test-auth-route.js http://localhost:3000/blog-api/api/endpoint

携带 JSON 数据的 POST 请求

node scripts/test-auth-route.js \
    http://localhost:3000/blog-api/777/submit \
    POST \
    '{"responses":{"4577":"13295"},"submissionID":5,"stepInstanceId":"11"}'

脚本的工作内容

1. 从 Keycloak 获取 refresh token
   • 用户名：testuser
   • 密码：testpassword
2. 使用 config.ini 中的 JWT 密钥为令牌签名
3. 创建 Cookie 请求头：refresh_token=<signed-token>
4. 发起经过身份验证的请求
5. 显示可用于手动重现的完整 curl 命令

脚本输出

脚本会输出：

• 请求详情
• 响应状态和正文
• 用于手动重现的 curl 命令

注意：此脚本会输出大量信息，请在输出中查找实际响应。

方法 2：使用令牌手动运行 curl

使用 test-auth-route.js 输出的 curl 命令：

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

方法 3：模拟身份验证（仅限开发环境——最简单）

在开发环境中，可完全绕过 Keycloak，使用模拟身份验证。

设置

# Add to service .env file (e.g., blog-api/.env)
MOCK_AUTH=true
MOCK_USER_ID=test-user
MOCK_USER_ROLES=admin,operations

用法

curl -H "X-Mock-Auth: true" \
     -H "X-Mock-User: test-user" \
     -H "X-Mock-Roles: admin,operations" \
     http://localhost:3002/api/protected

模拟身份验证的要求

模拟身份验证仅在以下条件下有效：

• NODE_ENV 为 development 或 test
• 路由中添加了 mockAuth 中间件
• 在生产环境中绝不会生效（安全特性）

常见测试模式

测试表单提交

node scripts/test-auth-route.js \
    http://localhost:3000/blog-api/777/submit \
    POST \
    '{"responses":{"4577":"13295"},"submissionID":5,"stepInstanceId":"11"}'

测试工作流启动

node scripts/test-auth-route.js \
    http://localhost:3002/api/workflow/start \
    POST \
    '{"workflowCode":"DHS_CLOSEOUT","entityType":"Submission","entityID":123}'

测试工作流步骤完成

node scripts/test-auth-route.js \
    http://localhost:3002/api/workflow/step/complete \
    POST \
    '{"stepInstanceID":789,"answers":{"decision":"approved","comments":"Looks good"}}'

测试带查询参数的 GET 请求

node scripts/test-auth-route.js \
    "http://localhost:3002/api/workflows?status=active&limit=10"

测试文件上传

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

硬编码的测试凭据

test-auth-route.js 脚本使用以下凭据：

• 用户名：testuser
• 密码：testpassword
• Keycloak URL：来自 config.ini（通常为 http://localhost:8081）
• Realm：yourRealm
• 客户端 ID：来自 config.ini

服务端口

服务	端口	基础 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

路由前缀

检查各服务中的 /src/app.ts，查看路由前缀：

// 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

完整路由 = 基础 URL + 前缀 + 路由路径

示例：

• 基础 URL：http://localhost:3002
• 前缀：/form
• 路由：/777/submit
• 完整 URL：http://localhost:3000/blog-api/777/submit

测试清单

测试路由前：

• 确定服务（form、email、users 等）
• 找到正确的端口
• 检查 app.ts 中的路由前缀
• 构建完整 URL
• 准备请求正文（如果是 POST/PUT）
• 确定身份验证方法
• 运行测试
• 验证响应状态和数据
• 如适用，检查数据库更改

验证数据库更改

测试会修改数据的路由后：

# 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';

调试失败的测试

401 未授权

可能原因：

1. 令牌已过期（使用 test-auth-route.js 重新生成）
2. Cookie 格式不正确
3. JWT 密钥不匹配
4. Keycloak 未运行

解决方案：

# 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 禁止访问

可能原因：

1. 用户缺少所需角色
2. 资源权限不正确
3. 路由要求特定权限

解决方案：

# 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 未找到

可能原因：

1. URL 不正确
2. 缺少路由前缀
3. 路由未注册

解决方案：

1. 检查 app.ts 中的路由前缀
2. 确认路由已注册
3. 检查服务是否正在运行（pm2 list）

500 内部服务器错误

可能原因：

1. 数据库连接问题
2. 缺少必填字段
3. 验证错误
4. 应用程序错误

解决方案：

1. 检查服务日志（pm2 logs <service>）
2. 在 Sentry 中查看错误详情
3. 确认请求正文符合预期的架构
4. 检查数据库连接

使用 auth-route-tester Agent

进行更改后，可使用以下步骤全面测试路由：

1. 确定受影响的路由
2. 收集路由信息：
   • 完整路由路径（含前缀）
   • 预期的 POST 数据
   • 要验证的表
3. 调用 auth-route-tester agent

该 Agent 将：

• 使用正确的身份验证测试路由
• 验证数据库更改
• 检查响应格式
• 报告任何问题

测试场景示例

创建新路由后

# 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

修改路由后

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

配置文件

config.ini（每个服务）

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

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

.env（每个服务）

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

关键文件

• /root/git/your project_pre/scripts/test-auth-route.js - 主要测试脚本
• /blog-api/src/app.ts - 表单服务路由
• /notifications/src/app.ts - 电子邮件服务路由
• /auth/src/app.ts - 用户服务路由
• /config.ini - 服务配置
• /.env - 环境变量

相关技能

• 使用 database-verification 验证数据库更改
• 使用 error-tracking 检查已捕获的错误
• 使用 workflow-builder 测试工作流路由
• 使用 notification-sender 验证通知是否已发送