route-tester

your project Route Tester Skill

目的

このスキルでは、Cookie ベースの JWT 認証を使用して your project の認証済みルートをテストするためのパターンを紹介します。

このスキルを使用する場面

• 新しい API エンドポイントのテスト
• 変更後のルート機能の検証
• 認証に関する問題のデバッグ
• POST／PUT／DELETE 操作のテスト
• リクエスト／レスポンスデータの検証

your project の認証の概要

your project では、次を使用します。

• SSO 用の Keycloak（レルム：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 からリフレッシュトークンを取得します
   • ユーザー名：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）
• レルム：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 + プレフィックス + ルートパス

例：

• ベース：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 Unauthorized

考えられる原因：

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 Forbidden

考えられる原因：

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 Not Found

考えられる原因:

1. URL が正しくない
2. ルートプレフィックスが不足している
3. ルートが登録されていない

解決策:

1. app.ts でルートプレフィックスを確認する
2. ルートの登録を確認する
3. サービスが実行中であることを確認する（pm2 list）

500 Internal Server Error

考えられる原因:

1. データベース接続の問題
2. 必須フィールドの不足
3. バリデーションエラー
4. アプリケーションエラー

解決策:

1. サービスのログを確認する（pm2 logs <service>）
2. Sentry でエラーの詳細を確認する
3. リクエストボディが想定されたスキーマと一致していることを確認する
4. データベースの接続性を確認する

auth-route-tester エージェントの使用

変更後にルートを包括的にテストするには:

1. 影響を受けるルートを特定する
2. ルート情報を収集する:
   • 完全なルートパス（プレフィックスを含む）
   • 想定される POST データ
   • 確認するテーブル
3. auth-route-tester エージェントを呼び出す

エージェントは以下を実行します:

• 適切な認証を使用してルートをテストする
• データベースの変更を確認する
• レスポンス形式を確認する
• 問題があれば報告する

テストシナリオの例

新しいルートを作成した後

# 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 を使用して送信された通知を確認する