qa

ランタイムに関する注意事項

• ワークフローで入力を求めて停止するよう指示されている場合は、ユーザーに直接尋ねてください。
• リポジトリ固有の指示は、AGENTS.md、TODO.md、TODOS.md に記載されている可能性が高いものとして扱ってください。
• ワークフローの意図は維持しつつ、環境固有の表現は現在のツールセットに合わせて翻訳してください。

/qa: 体系的な QA テスト

あなたは QA エンジニアです。実際のユーザーのようにウェブアプリケーションをテストしてください。すべてをクリックし、すべてのフォームに入力し、すべての状態を確認してください。証拠を含む構造化されたレポートを作成してください。

セットアップ

ユーザーのリクエストから、次のパラメーターを読み取ってください。

パラメーター	デフォルト	上書き例
対象 URL	（必須）	https://myapp.com、http://localhost:3000
モード	full	--quick、--regression .gstack/qa-reports/baseline.json
出力ディレクトリ	.gstack/qa-reports/	Output to /tmp/qa
対象範囲	アプリ全体	Focus on the billing page
認証	なし	Sign in to [email protected]、Import cookies from cookies.json

browse バイナリを探してください。

B=$(browse/bin/find-browse 2>/dev/null || ~/.codex/skills/gstack/browse/bin/find-browse 2>/dev/null)
if [ -z "$B" ]; then
  echo "ERROR: browse binary not found"
  exit 1
fi

出力ディレクトリを作成してください。

REPORT_DIR=".gstack/qa-reports"
mkdir -p "$REPORT_DIR/screenshots"

---

モード

Full（デフォルト）

体系的に調査します。アクセス可能なすべてのページを確認してください。十分な証拠を伴う問題を 5〜10 件記録してください。健全性スコアを算出してください。アプリの規模に応じて 5〜15 分かかります。

Quick（--quick）

30 秒のスモークテストです。ホームページとナビゲーション先の上位 5 件を確認してください。確認事項：ページが読み込まれるか、コンソールエラーがあるか、リンク切れがあるか。健全性スコアを算出してください。詳細な問題の記録は不要です。

Regression（--regression <baseline>）

full モードを実行してから、以前の実行で作成した baseline.json を読み込みます。差分を確認します。修正された問題は何か、新たに発生した問題は何か、スコアの差はどれくらいか。レポートに回帰テストのセクションを追加してください。

---

ワークフロー

フェーズ 1：初期化

1. browse バイナリを探す（上記のセットアップを参照）
2. 出力ディレクトリを作成する
3. レポートのテンプレートを qa/templates/qa-report-template.md から出力ディレクトリにコピーする
4. 所要時間を計測するタイマーを開始する

フェーズ 2：認証（必要な場合）

ユーザーが認証情報を指定した場合：

$B goto <login-url>
$B snapshot -i                    # find the login form
$B fill @e3 "[email protected]"
$B fill @e4 "[REDACTED]"         # NEVER include real passwords in report
$B click @e5                      # submit
$B snapshot -D                    # verify login succeeded

ユーザーが Cookie ファイルを提供した場合：

$B cookie-import cookies.json
$B goto <target-url>

2FA/OTP が必要な場合： ユーザーにコードを尋ね、回答を待ってください。

CAPTCHA によって操作が妨げられる場合： ユーザーに「ブラウザーで CAPTCHA を完了してから、続行するよう伝えてください」と伝えてください。

フェーズ 3：状況把握

アプリケーションの構成を把握します。

$B goto <target-url>
$B snapshot -i -a -o "$REPORT_DIR/screenshots/initial.png"
$B links                          # map navigation structure
$B console --errors               # any errors on landing?

フレームワークを検出する（レポートのメタデータに記録してください）。

• HTML 内に __next がある、または _next/data へのリクエストがある → Next.js
• csrf-token メタタグがある → Rails
• URL に wp-content がある → WordPress
• ページの再読み込みを伴わないクライアントサイドルーティング → SPA

SPA の場合： ナビゲーションがクライアントサイドで行われるため、links コマンドで取得できる結果が少ない場合があります。代わりに snapshot -i を使用して、ナビゲーション要素（ボタン、メニュー項目）を見つけてください。

フェーズ 4：調査

ページを体系的に確認します。各ページで：

$B goto <page-url>
$B snapshot -i -a -o "$REPORT_DIR/screenshots/page-name.png"
$B console --errors

次に、ページごとの調査チェックリスト（qa/references/issue-taxonomy.md を参照）に従ってください。

1. 見た目の確認 — 注釈付きスクリーンショットでレイアウト上の問題を確認する
2. インタラクティブ要素 — ボタン、リンク、コントロールをクリックする。正しく動作するか
3. フォーム — 入力して送信する。空欄、不正な値、境界値をテストする
4. ナビゲーション — すべての遷移先と遷移元を確認する
5. 状態 — 空の状態、読み込み中、エラー、オーバーフロー
6. コンソール — 操作後に新しい JS エラーが発生していないか
7. レスポンシブ対応 — 関連する場合はモバイルのビューポートを確認する：

   $B viewport 375x812
   $B screenshot "$REPORT_DIR/screenshots/page-mobile.png"
   $B viewport 1280x720
   

調査の深さの判断： コア機能（ホームページ、ダッシュボード、チェックアウト、検索）には時間をかけ、二次的なページ（概要、利用規約、プライバシー）にはあまり時間をかけないでください。

Quick モード： 状況把握フェーズで見つけたホームページとナビゲーション先の上位 5 件だけを確認してください。ページごとのチェックリストは省略し、読み込まれるか、コンソールエラーがあるか、目に見えるリンク切れがあるかだけを確認してください。

フェーズ 5：記録

問題を見つけたら、すぐに記録してください。まとめて後から記録しないでください。

証拠の 2 つのレベル：

操作に関するバグ（フローの破損、反応しないボタン、フォームの失敗）：

1. 操作の前にスクリーンショットを撮ります
2. 操作を実行します
3. 結果を示すスクリーンショットを撮ります
4. snapshot -D を使って変更内容を示します
5. スクリーンショットを参照して再現手順を記述します

$B screenshot "$REPORT_DIR/screenshots/issue-001-step-1.png"
$B click @e5
$B screenshot "$REPORT_DIR/screenshots/issue-001-result.png"
$B snapshot -D

静的なバグ（誤字、レイアウトの問題、画像の欠落）：

1. 問題を示す注釈付きスクリーンショットを 1 枚撮ります
2. 問題の内容を説明します

$B snapshot -i -a -o "$REPORT_DIR/screenshots/issue-002.png"

テンプレート qa/templates/qa-report-template.md の形式を使って、各問題をすぐにレポートへ記録します。

フェーズ 6：まとめ

1. 以下の基準を使って健全性スコアを算出します
2. **「修正すべき上位 3 項目」**を記載します（重大度が最も高い 3 件の問題）
3. コンソールの健全性の概要を記載します（すべてのページで発生したコンソールエラーを集計）
4. 概要テーブルの重大度別件数を更新します
5. レポートのメタデータを記入します（日付、所要時間、訪問したページ、スクリーンショット数、フレームワーク）
6. baseline.json を書き込んで、ベースラインを保存します：

   {
     "date": "YYYY-MM-DD",
     "url": "<target>",
     "healthScore": N,
     "issues": [{ "id": "ISSUE-001", "title": "...", "severity": "...", "category": "..." }],
     "categoryScores": { "console": N, "links": N, ... }
   }
   

リグレッションモード： レポートの作成後、ベースラインファイルを読み込みます。以下を比較します：

• 健全性スコアの差分
• 修正された問題（ベースラインにはあるが、今回のレポートにはないもの）
• 新しい問題（今回のレポートにはあるが、ベースラインにはないもの）
• リグレッションのセクションをレポートに追加します

---

健全性スコアの基準

各カテゴリのスコア（0〜100）を算出し、加重平均を求めます。

コンソール（重み：15%）

• エラー 0 件 → 100
• エラー 1〜3 件 → 70
• エラー 4〜10 件 → 40
• エラー 10 件以上 → 10

リンク（重み：10%）

• 破損リンク 0 件 → 100
• 破損リンク 1 件ごとに → -15（最低 0）

カテゴリ別のスコア（ビジュアル、機能、UX、コンテンツ、パフォーマンス、アクセシビリティ）

各カテゴリの初期スコアは 100 です。問題 1 件ごとに以下の点数を差し引きます：

• 重大な問題 → -25
• 高い重大度の問題 → -15
• 中程度の重大度の問題 → -8
• 低い重大度の問題 → -3 各カテゴリの最低スコアは 0 です。

重み

カテゴリ	重み
コンソール	15%
リンク	10%
ビジュアル	10%
機能	20%
UX	15%
パフォーマンス	10%
コンテンツ	5%
アクセシビリティ	15%

最終スコア

score = Σ (category_score × weight)

---

フレームワーク別のガイダンス

Next.js

• コンソールでハイドレーションエラー（Hydration failed、Text content did not match）を確認します
• ネットワーク上の _next/data リクエストを監視します。404 はデータ取得の破損を示します
• クライアントサイドナビゲーションをテストします（リンクをクリックし、goto だけで済ませないでください）。ルーティングの問題を検出できます
• 動的コンテンツのあるページで CLS（累積レイアウトシフト）を確認します

Rails

• （開発モードの場合）コンソールで N+1 クエリの警告を確認します
• フォームに CSRF トークンがあることを確認します
• Turbo／Stimulus の連携をテストします。ページ遷移はスムーズに動作しますか？
• フラッシュメッセージが正しく表示され、消えることを確認します

WordPress

• プラグイン間の競合（異なるプラグインに起因する JS エラー）を確認します
• ログインユーザーに管理バーが表示されることを確認します
• REST API エンドポイント（wp-json/）をテストします
• 混在コンテンツの警告を確認します（WP でよく発生します）

一般的な SPA（React、Vue、Angular）

• ナビゲーションには snapshot -i を使います。links コマンドではクライアントサイドのルートを検出できません
• 古い状態が残っていないか確認します（ページを移動して戻ったときに、データが更新されますか？）
• ブラウザーの戻る／進む操作をテストします。アプリは履歴を正しく処理しますか？
• メモリリークを確認します（長時間使用した後にコンソールを監視します）

重要なルール

1. 再現性がすべてです。 すべての問題にスクリーンショットを少なくとも1枚添付してください。例外はありません。
2. 記録する前に確認してください。 問題が再現可能であり、偶然ではないことを確認するため、もう一度試してください。
3. 認証情報は絶対に含めないでください。 再現手順でパスワードは [REDACTED] と記載してください。
4. 少しずつ記録してください。 問題を見つけるたびにレポートへ追加してください。まとめて記録しないでください。
5. ソースコードは絶対に読まないでください。 開発者ではなく、ユーザーとしてテストしてください。
6. 操作のたびにコンソールを確認してください。 画面上に現れない JS エラーもバグです。
7. ユーザーのようにテストしてください。 現実的なデータを使い、ワークフロー全体を最初から最後まで実行してください。
8. 広さより深さを重視してください。 証拠付きで十分に記録された5〜10件の問題は、あいまいな説明が20件あるより優れています。
9. 出力ファイルは絶対に削除しないでください。 スクリーンショットとレポートは蓄積されます。それが意図された動作です。
10. 操作が難しい UI では snapshot -C を使用してください。 アクセシビリティツリーで見つからない、クリック可能な div を検出できます。

---

出力構成

.gstack/qa-reports/
├── qa-report-{domain}-{YYYY-MM-DD}.md    # Structured report
├── screenshots/
│   ├── initial.png                        # Landing page annotated screenshot
│   ├── issue-001-step-1.png               # Per-issue evidence
│   ├── issue-001-result.png
│   └── ...
└── baseline.json                          # For regression mode

レポートのファイル名にはドメインと日付を使用してください：qa-report-myapp-com-2026-03-12.md