ui-check-framework

UI チェックフレームワーク

概要

data-qa タグを使って UI ブロックを検出し、動作および視覚的な契約（テーマ、アニメーション、読み込み、レイアウトの安定性、モーダルの使いやすさ、エラーの可視性）を適用する、自動化された UI セルフチェックシステムを作成または改良します。新しいカード、モーダル、トースト、アクションが追加されるたびにテストケースを書かなくても拡張できるフレームワークにしてください。

ワークフロー（順番に実施）

1. 既存の足場を確認する

   • プロジェクトに ui-tests/ フォルダーがある場合は、再利用を優先します。
   • ui-tests/docs/UI_TESTING.md と ui-tests/docs/QA_TAGGING.md が存在する場合は読みます。
   • ルートの package.json にあるスクリプト（ui:test、ui:update-baseline、 ui:report、ui:check、ui:watch）が Playwright のフローを参照していることを確認します。

2. 検出を適用する

   • qa: で始まるすべての data-qa または data-testid 要素を自動収集します。
   • 小・中・大の各サイズで、コンポーネントのスクリーンショット（カード、モーダル、メニュー、ツールバー、トースト）を撮影します。
   • モーダルについては、内部スクロール、閉じるボタンが1つだけであること、小さいウィンドウ高でのヘッダーの表示を確認します。

3. 契約を適用する（ハードコードではなく汎用的に）

   • ダーク／ライト／システムのテーマにおけるコントラストと読みやすさ（参考資料を参照）。
   • スピナー、トランジション、トーストのアニメーション／モーションのチェック。
   • 非同期アクションの読み込み状態マシン：アイドル -> 読み込み中 -> 成功／エラー -> アイドル。
   • レイアウトの安定性（一時的なステータス／トーストによるレイアウトシフトがないこと）。
   • アクションボタンとモーダルのヘッダー／フッターの重なりを検出します。
   • エラーの可視性と空白ページの検出。

4. 自動化用に UI フックを組み込む

   • 契約をセレクターのハードコードなしでテストできるよう、最小限の window.__ui_check__ ヘルパー（ログの追加、トーストのトリガーなど）を追加します。
   • 新しいカード／モーダル／アクションが追加されたら、必要な data-qa タグを追加します。

5. 成果物とレポート

   • 成果物（スナップショット、フレーム、動画、report.html）を artifacts/ui-check/ に保存します。
   • ui:check が対話的に動作することを確認します（モーダルの開閉、ホバー／押下、テーマの切り替え、スクロール）。

プロジェクト固有の基準

• 主な UI テストは ui-tests/ にあり、Playwright を使用します。
• 対話的な検証のエントリーポイントとして、ui-tests/scripts/ui-check.mjs と ui-tests/scripts/ui-watch.mjs を使用します。
• ユーザー向けドキュメントは ui-tests/docs/UI_TESTING.md と ui-tests/docs/QA_TAGGING.md に記載します。

参考資料

• references/workflow.md - 拡張ワークフローと検証チェックリスト。
• references/qa-tagging.md - 必須の QA トークンと命名規則。
• references/contracts.md - 必須の汎用契約と確認方法。