ln-522-manual-tester

パス： ファイルパス（references/、../ln-*）は、このスキルディレクトリからの相対パスです。

必ず読むこと： references/ci_tool_detection.md を読み込みます。bash/curl/Puppeteer スクリプトのコンパクトな出力フラグ、pipefail、失敗時のアーティファクトポリシーについて記載されています。

入力

入力	必須	ソース	説明
storyId	はい	args、git ブランチ、kanban、ユーザー	処理するストーリー

解決方法： ストーリー解決チェーン。 ステータスフィルター： To Review

手動テスター

タイプ： L3 ワーカー

実行中のコードでストーリーの AC を手動で検証し、品質ゲート用に構造化された結果を報告します。

目的と範囲

• 対象プロジェクトの tests/manual/ フォルダーに実行可能なテストスクリプトを作成します。
• bash/curl（API）または Puppeteer（UI）を使って、AC に基づくチェックを実行します。
• 回帰テスト用にスクリプトを恒久的に保存します（一時ファイルにはしません）。
• 設定済みのトラッカープロバイダーの addComment を使い、各 AC の合否とスクリプトパスを記載した結果を記録します。
• ステータスの変更やタスクの作成は行いません。

使用するタイミング

• 自動テスト計画の前に、ストーリーの受け入れ基準を実地で検証する必要がある場合に使用します
• ストーリーに「## Test Research:」のリサーチコメントがある場合（ln-521 によるもの）
• ストーリー内のすべての実装タスクのステータスが Done の場合

テスト設計の原則

1. フェイルファスト — 失敗を黙って見過ごさない

重要： いずれかの基準を満たさない場合、テストは直ちに 1（失敗）を返す必要があります。

使用禁止： 検証失敗時に print_status "WARN" + return 0 を使うこと、明示的なフラグなしで穏便に処理を続行すること、エラーを隠すフォールバックを黙って行うこと。

例外（WARN を使用してよい場合）： 正確性に影響しない情報提供の警告、任意機能（コメントで明確な根拠を示すこと）、インフラストラクチャの問題（例：開発環境に Nginx がない）。

2. 期待値ベースのテスト — ゴールデンスタンダード

重要： テストでは、ヒューリスティックやアルゴリズムによるチェックを適用するのではなく、実際の結果を期待値の参照ファイルと比較する必要があります。

ディレクトリ構成：

tests/manual/NN-feature/
├── samples/               # Input files
├── expected/              # Expected output files (REQUIRED!)
│   └── {base_name}_{source_lang}-{target_lang}.{ext}
└── test-*.sh

ヒューリスティックを使用できるのは次の場合のみ： 動的または非決定的なデータ（タイムスタンプ、UUID、トークン — 比較前に正規化すること）、順序が不定のキーを持つ JSON（jq --sort-keys を使用すること）。

3. 結果の保存

テスト結果は tests/manual/results/ に保存します（永続的で、.gitignore に含めます）。ファイル名は result_{ac_name}.{ext} または response_{ac_name}.json とします。デバッグのため、テスト完了後も内容を確認できるようにします。

4. 期待値ファイルの生成

期待値ファイルを作成するには：

1. 現在の実装でテストを実行します
2. results/ フォルダー内の出力を確認します
3. 正しい場合：適切な名前を付けて expected/ フォルダーにコピーします
4. 正しくない場合：まず実装を修正してからコピーします

重要： 結果をそのまま期待値ファイルにコピーしないでください。必ず最初に正しさを検証します。

ワークフロー

フェーズ 0：入力の解決

必ず読むこと： references/input_resolution_pattern.md を読み込みます

1. storyId を解決： ガイドに従ってストーリー解決チェーンを実行します（ステータスフィルター：[To Review]）。

フェーズ 1：tests/manual の構成をセットアップ

1. docs/project/infrastructure.md を読む — ポートの割り当て、サービスのエンドポイント、ベース URL を確認します。docs/project/runbook.md を読む — Docker コマンド、テストの前提条件、環境のセットアップ方法を確認します
2. プロジェクトルートに tests/manual/ フォルダーがあるか確認します
3. なければ、次の構成を作成します：
   • tests/manual/config.sh — 共通設定（BASE_URL、ヘルパー、色）
   • tests/manual/README.md — フォルダーの説明（以下の README.md テンプレートを参照）
   • tests/manual/test-all.sh — すべてのテストスイートを実行するマスタースクリプト（以下の test-all.sh テンプレートを参照）
   • tests/manual/results/ — テスト出力用フォルダー（.gitignore に追加）
4. プロジェクトの .gitignore に tests/manual/results/ がない場合は追加します
5. すでに存在する場合は、既存の config.sh を読み、設定（BASE_URL、トークン）を再利用します

フェーズ 2: Story テストスクリプトの作成

1. Story を取得し、AC を Given/When/Then リストに解析する（3〜5 件を想定）
   • 調査コメントを確認する（ln-521-test-researcher より）— 調査結果をテストケースに反映する
2. API か UI かを判定する（API → curl、UI → puppeteer）。IF UI: MANDATORY READ: references/puppeteer_patterns.md を読み込む
3. テストフォルダ構造を作成する:
   • tests/manual/{NN}-{story-slug}/samples/ — 入力ファイル（必要な場合）
   • tests/manual/{NN}-{story-slug}/expected/ — 期待される出力ファイル（決定論的テストでは必須）
4. テストスクリプトを生成する: tests/manual/{NN}-{story-slug}/test-{story-slug}.sh
   • 適切なテンプレートを使用する: TEMPLATE-api-endpoint.sh（直接呼び出し）または TEMPLATE-document-format.sh（非同期ジョブ）
   • ヘッダー: Story ID、AC リスト、前提条件
   • AC ごとのテスト関数 + エッジケース/エラーケース
   • 期待ファイルに対する diff ベースの検証（PRIMARY）
   • 結果は tests/manual/results/ に保存される
   • タイミング付きのサマリーテーブル
5. スクリプトを実行可能にする（chmod +x）

フェーズ 3: ドキュメントの更新

1. tests/manual/README.md を更新する:
   • 「Available Test Suites」テーブルに新しいテストを追加する
   • Story ID、カバーされる AC、実行コマンドを含める
2. tests/manual/test-all.sh を更新する:
   • SUITES 配列に新しいスクリプトの呼び出しを追加する
   • 実行順序を維持する（最初に 00-setup、続いて番号付きスイート）

フェーズ 4: 実行とレポート

MANDATORY READ: references/test_result_format_v1.md を読み込む

1. Docker コンテナを再ビルドする（キャッシュなし）。ヘルスチェックを確認する
2. 生成したスクリプトを実行し、出力をキャプチャする
3. 結果を解析する（成功/失敗の件数）
4. トラッカーにコメントを投稿する（addComment、test_result_format_v1.md に従う）。以下を含める:
   • AC マトリクス（AC ごとの成功/失敗）
   • スクリプトパス: tests/manual/{NN}-{story-slug}/test-{story-slug}.sh
   • 再実行コマンド: cd tests/manual && ./{NN}-{story-slug}/test-{story-slug}.sh

重要なルール

• スクリプトはプロジェクトの tests/manual/ に保存し、一時ファイルには保存しない。
• テスト前に Docker を再ビルドする。再ビルド/実行が unhealthy の場合は失敗とする。
• スクリプトのコメントとトラッカーコメントでは Story の言語（EN/RU）を維持する。
• 修正やステータス変更は行わない。証拠と判定のみとする。
• スクリプトは冪等でなければならない（いつでも再実行可能）。

ランタイムサマリー成果物

MANDATORY READ: references/test_planning_summary_contract.md、references/test_planning_worker_runtime_contract.md を読み込む

ランタイムプロファイル:

• family: test-planning-worker
• worker: ln-522
• summary kind: test-planning-worker
• コーディネーターが使用する payload フィールド: worker、status、warnings、manual_result_path

呼び出しルール:

• standalone: runId と summaryArtifactPath を省略する
• managed: runId と正確な summaryArtifactPath の両方を渡す
• 終了結果の前に、必ず検証済みのサマリーを書き込む

テストスクリプトは常に tests/manual/ に置き、プロジェクトルートには置かない。

Monitor 統合（Claude Code 2.1.98+）

MANDATORY READ: references/monitor_integration_pattern.md を読み込む

実行に 30 秒以上かかると予想されるテストスクリプトを実行する場合: Monitor(command="bash tests/manual/{suite}/test-{slug}.sh 2>&1", timeout_ms=300000, description="manual test: {slug}")

フォールバック: Monitor が利用できない場合（Bedrock/Vertex）、Bash(run_in_background=true) を使用する。

完了の定義

• tests/manual/ 構造が存在する（config.sh、README.md、test-all.sh、results/ がなければ作成されている）。
• tests/manual/results/ がプロジェクトの .gitignore に追加されている。
• テストスクリプトが tests/manual/{NN}-{story-slug}/test-{story-slug}.sh に作成されている。
• expected/ フォルダが、決定論的な AC ごとに少なくとも 1 つの期待ファイルとともに作成されている。
• スクリプトが期待ファイルに対する diff ベースの検証 を使用している（ヒューリスティックではない）。
• スクリプトがデバッグ用に結果を tests/manual/results/ に保存する。
• スクリプトが実行可能かつ冪等である。
• README.md が更新され、「Available Test Suites」テーブルに新しいテストスイートが追加されている。
• test-all.sh が更新され、SUITES 配列に新しいスクリプトの呼び出しが追加されている。
• アプリが再ビルドされ実行中である。テストが実行されている。
• 判定とトラッカーコメントが、スクリプトパスと再実行コマンドとともに投稿されている。

スクリプトテンプレート

README.md（プロジェクトごとに一度作成）

# Manual Testing Scripts

> **SCOPE:** Bash scripts for manual API testing. Complements automated tests with CLI-based workflows.

## Quick Start

```bash
cd tests/manual
./00-setup/create-account.sh  # (if auth required)
./test-all.sh                 # Run ALL test suites

前提条件

• Docker コンテナが稼働している（docker compose ps）
• jq がインストールされている（apt-get install jq または brew install jq）

フォルダー構成

tests/manual/
├── config.sh          # Shared configuration (BASE_URL, helpers, colors)
├── README.md          # This file
├── test-all.sh        # Run all test suites
├── 00-setup/          # Account & token setup (if auth required)
│   ├── create-account.sh
│   └── get-token.sh
└── {NN}-{topic}/      # Test suites by Story
    └── test-{slug}.sh

利用可能なテストスイート

テストスイート	ストーリー	対象AC	実行コマンド
—	—	—	—

テストの追加

1. {NN}-{topic}/test-{slug}.sh にスクリプトを作成します
2. この README を更新します（利用可能なテストスイートの表）
3. test-all.sh を更新します（SUITES 配列に追加）

### test-all.sh (created once per project)

```bash
#!/bin/bash
# =============================================================================
# Run all manual test suites
# =============================================================================
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/config.sh"

echo "=========================================="
echo "Running ALL Manual Test Suites"
echo "=========================================="

check_jq
check_api

# Setup (if exists)
[ -f "$SCRIPT_DIR/00-setup/create-account.sh" ] && "$SCRIPT_DIR/00-setup/create-account.sh"
[ -f "$SCRIPT_DIR/00-setup/get-token.sh" ] && "$SCRIPT_DIR/00-setup/get-token.sh"

# Test suites (add new suites here)
SUITES=(
    # "01-auth/test-auth-flow.sh"
    # "02-translation/test-translation.sh"
)

PASSED=0; FAILED=0
for suite in "${SUITES[@]}"; do
    echo ""
    echo "=========================================="
    echo "Running: $suite"
    echo "=========================================="
    if "$SCRIPT_DIR/$suite"; then
        ((++PASSED))
        print_status "PASS" "$suite"
    else
        ((++FAILED))
        print_status "FAIL" "$suite"
    fi
done

echo ""
echo "=========================================="
echo "TOTAL: $PASSED suites passed, $FAILED failed"
echo "=========================================="
[ $FAILED -eq 0 ] && exit 0 || exit 1

config.sh（プロジェクトごとに一度作成）

#!/bin/bash
# Shared configuration for manual testing scripts
export BASE_URL="${BASE_URL:-http://localhost:8080}"
export RED='\033[0;31m'
export GREEN='\033[0;32m'
export YELLOW='\033[1;33m'
export NC='\033[0m'

print_status() {
    local status=$1; local message=$2
    case $status in
        "PASS") echo -e "${GREEN}[PASS]${NC} $message" ;;
        "FAIL") echo -e "${RED}[FAIL]${NC} $message" ;;
        "WARN") echo -e "${YELLOW}[WARN]${NC} $message" ;;
        "INFO") echo -e "[INFO] $message" ;;
    esac
}

check_jq() {
    command -v jq &> /dev/null || { echo "Error: jq required"; exit 1; }
}

check_api() {
    local response=$(curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/health" 2>/dev/null)
    if [ "$response" != "200" ]; then
        echo "Error: API not reachable at $BASE_URL"
        exit 1
    fi
    print_status "INFO" "API reachable at $BASE_URL"
}

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
export SCRIPT_DIR

テストスクリプトテンプレート

参照先： references/templates/

テンプレート	用途	場所
template-api-endpoint.sh	API エンドポイントのテスト（非同期ジョブなし）	template-api-endpoint.sh
template-document-format.sh	ドキュメント／ファイル処理（非同期ジョブあり）	template-document-format.sh

クイックスタート：

cp references/templates/template-api-endpoint.sh {NN}-feature/test-{feature}.sh      # Endpoint tests
cp references/templates/template-document-format.sh {NN}-feature/test-{format}.sh    # Document tests

参照ファイル

• スクリプト形式の参照先：prompsit-api tests/manual/（本番環境の例）
• AC 形式：references/templates/test_task_template.md（または対象プロジェクト内の docs/templates/）
• リスクベースのコンテキスト：references/risk_based_testing_guide.md
• 調査結果：ln-521-test-researcher がストーリーに「## Test Research」コメントを作成します
• Puppeteer のパターン：references/puppeteer_patterns.md
• テスト結果の形式：references/test_result_format_v1.md

---

バージョン： 1.0.0 最終更新日： 2026-01-15