eve-verification-plans

Eve 検証プラン

Eve 互換アプリが正しく動作し、Eve プラットフォームの規約にも準拠していることを検証する手順をすべて指定した、エージェント型検証プランを Markdown ドキュメントとして作成します。プランは人間にもエージェントにも実行可能です。

使用するタイミング

• 新しい Eve 互換アプリの検証を構築するとき
• 既存アプリの Eve プラットフォームへの準拠を監査するとき
• 構造化された検証が必要となる大規模な機能開発の後
• 引き継ぎの前 — アプリが Eve の方法に沿ってエンドツーエンドで動作することを証明するとき
• 新しいチームが「Eve 上で正しく構築されている」とはどういう状態かを理解するためのオンボーディング時

クイックスタート

# 1. Create the verification directory in your project
mkdir -p e2e-verification/00-smoke

# 2. Copy the smoke template
cp templates/00-smoke-test-plan.md e2e-verification/00-smoke/

# 3. Customize for your app (endpoints, services, agents)
# 4. Run it

6 つの検証項目

すべての Eve アプリには、検証対象となる項目が最大 6 つあります。該当するものをすべて確認してください。

項目	ツール	タイミング	準拠チェック
プラットフォーム準拠	Eve CLI ＋マニフェストの検査	常に	CLI の同等性、マニフェストの規約、シークレット管理モデル
サービスレイヤー	Eve CLI ＋ REST API	常に	すべてのエンドポイントに CLI からアクセスできること。kubectl が不要であること
入力／取り込み	リポジトリのフィクスチャ＋アップロードコマンド	アプリがファイルを受け付ける場合	決定論的なフィクスチャ、実際の解析フロー
データレイヤー	Eve CLI ＋ DB マイグレーション	アプリに DB がある場合	手動 SQL ではなく、Eve パイプラインを使ったマイグレーション
UI／ビジュアル	agent-browser または Playwright	フロントエンドがある場合	SSO ログイン、ダーク／ライトモード、エージェントによるテストが可能であること
エージェントの動作	eve job follow ＋最適化	アプリにエージェントがある場合	効率的に完了すること、行き詰まる経路がないこと

検証プランの形式

各シナリオは、単独で完結する Markdown ドキュメントです。

# Scenario NN: <Name>

**Time:** ~Nm
**Environment:** staging | local | both
**Parallel Safe:** Yes/No
**Requires:** LLM | Browser | None

<one-paragraph description>

## Prerequisites

- What must be true before running
- Required secrets, auth, prior scenarios

## Fixtures

- File paths used by this scenario
- Provenance or generation command for each
- Why these files are representative

## Setup

\```bash
# Environment detection + auth
# Project/org setup
# Fixture validation or generation
\```

## Phases

### Phase 1: <Name>

\```bash
# Commands to execute
\```

**Expected:**
- Bullet list of assertions
- Each assertion is pass/fail verifiable

### Phase 2: ...

## Success Criteria

- [ ] Checkboxes for every pass/fail assertion
- [ ] Grouped by phase

## Debugging

| Symptom | Diagnostic | Fix |
|---------|-----------|-----|
| ... | ... | ... |

## Cleanup

\```bash
# Teardown commands
\```

形式のルール

• 環境を考慮：すべてのプランは環境の検出から始めます。EVE_API_URL によってクラウド環境かローカル環境かを判定します
• 自己完結：文書化された前提条件以外の状態を想定しません
• フィクスチャを明示：アップロード／インポートするすべての成果物は、リポジトリにチェックインするか、文書化されたコマンドで生成します
• フェーズ分け：独立して実行できるフェーズに分割します（安全な場合は並列実行します）
• アサーション駆動：すべての手順に、合格／不合格の基準を示す明確な Expected: を記載します
• デバッグ可能：症状 → 診断 → 修正を記載したトラブルシューティングセクションを設けます

プラットフォーム準拠の検証

機能をテストする前に、アプリが Eve の方法に沿って構築されていることを確認します。すべての検証スイートは、次のチェックリストから始めます。

• .eve/manifest.yaml が存在し、eve project sync --dry-run に合格する
• マニフェストが現在の規約に従っている（旧式の project より name を優先）
• すべてのサービスに、Eve イングレス経由でアクセスできるヘルスエンドポイントがある
• すべての API エンドポイントを CLI から操作できる（「UI 専用」の機能がない）
• シークレットはハードコードしたり環境ファイルで管理したりせず、eve secrets で管理されている
• DB マイグレーションは手動スクリプトではなく、パイプラインのステップとして実行される
• エージェントがある場合は、ハーネスプロファイルとともに agents.yaml で定義されている
• パイプラインがある場合は、マニフェストで定義され、eve pipeline run で実行できる
• フロントエンドがある場合は、独自の認証ではなく Eve SSO で認証する
• アップロード／インポートフローがある場合は、決定論的なフィクスチャがチェックインされているか、ローカルで生成できる

理由を含む完全なチェックリストについては、references/eve-conformance-checks.md を参照してください。

サービスレイヤーの検証

すべての API サーフェスを CLI 優先でテストします。

TOKEN=$(eve auth token --raw)

# Health check (always first)
curl -sf "${APP_SCHEME}://api.${APP_DOMAIN}/health" | jq '.'

# App API via auth token
curl -sf -H "Authorization: Bearer $TOKEN" \
  "${APP_SCHEME}://api.${APP_DOMAIN}/endpoint" | jq '.field'

CLI 同等性のアサーション：テストプラン内のすべての curl 呼び出しについて、「これも CLI コマンドで実行できますか？」と確認します。できない場合は、そのまま受け入れず、課題を登録してください。

パターン：

1. 該当する Eve CLI コマンド（deploy、env、job、secrets）
2. アプリが eve-app-cli のパターンに従っている場合はアプリ CLI
3. カスタムエンドポイントには、認証トークンを指定して curl から REST API を呼び出す
4. 認証：eve auth mint または eve auth token --raw でトークンを生成する

入力／取り込みの検証

アプリがアップロード、インポート、またはドキュメント一式を受け付ける場合、検証にはフィクスチャの計画を含める必要があります。

フィクスチャの選択順

1. 対応するファイル形式に一致し、決定性がある場合は、既存のリポジトリ内のフィクスチャを再利用します
2. スクリプトをコミットしたうえで、ローカルで合成フィクスチャを作成します
3. ローカルで作成するとリアリティが損なわれる場合に限り、小さなパブリックドメインのフィクスチャを入手します

フィクスチャの一覧

• 最小限の有効なフィクスチャ — 正常系を検証できる最小の受け入れ可能なファイル
• 一般的な実世界のフィクスチャ — 代表的なドキュメント／メディア／インポートファイル
• 境界値／無効なフィクスチャ — 誤った形式、不正な構造、またはサイズの境界値
• 複数形式 — アプリが複数の形式（PDF + Markdown + CSV）を受け入れる場合は、それぞれを検証します

確認事項

• 実際のアプリの操作面（CLI、REST エンドポイント、またはブラウザーからのアップロード）を通じてファイルが受け入れられること
• MIME／形式の検出とメタデータが正しいこと
• ストレージ／永続化のパスが正しいこと
• 後続の処理で期待される結果が得られること
• 拒否されたフィクスチャや不正なフィクスチャに対するエラー処理が明示されていること

ルール：計画に「サンプル PDF をアップロードする」と記載する場合は、実際のファイルパスまたは生成手順を含める必要があります。「オンラインで PDF を探す」では不十分です。

詳細なガイダンスについては、references/fixture-patterns.md を参照してください。

UI の検証

アプリにフロントエンドがある場合は、視覚的な品質と操作フローを検証します。

SSO トークンの挿入

# Mint an SSO token via CLI
SSO_TOKEN=$(eve auth mint --email [email protected] --org $ORG_ID --format sso-jwt)

# Use agent-browser with the token
agent-browser --session verify open "${APP_URL}/auth/callback?token=${SSO_TOKEN}"
agent-browser --session verify wait --url "**/dashboard"
agent-browser --session verify screenshot ./e2e-verification/artifacts/dashboard.png

確認事項

• コンソールエラーなしでページが表示されること
• ダークモードとライトモードの両方が機能すること（両方のスクリーンショットを撮影）
• 主要なユーザーフローが完了すること（ログイン → ダッシュボード → アクション → 結果）
• 標準的なブレークポイントでレスポンシブレイアウトが機能すること
• フォームが正しく送信され、バリデーションが実行されること

ツールの選択に関するガイダンスとパターンについては、references/ui-verification-patterns.md を参照してください。

エージェントの検証

アプリに Eve エージェントが含まれる場合は、動作の品質も検証します。

1. エージェントの主要なワークフローを実行するジョブを作成します
2. 実行状況を確認します：eve job follow <job-id>
3. レシートを確認します：eve job receipt <job-id>（トークン数、コスト、所要時間）
4. eve-agent-optimisation 診断ワークフローを適用します
5. リグレッション検出のため、テスト計画にベースライン指標を記録します

確認事項

• エージェントがタスクを完了すること（正しい出力）
• トークン使用量が許容範囲内であること
• 不必要なツール呼び出しや無駄な試行がないこと
• エラーケース（不正な入力、シークレットの欠落）を適切に処理すること
• 複数エージェントの連携が機能すること（ジョブが依存関係の順序どおりに完了する）

最適化との連携については、references/agent-verification-patterns.md を参照してください。

デプロイサイクルのパターン

検証によって問題が見つかることはよくあります。修正／デプロイのループは次のとおりです。

クラウド（ステージング）— デフォルト

discover bug → fix code → commit → tag release-v* → push tag →
  wait for CI (publish-images → infra dispatch → deploy) →
  re-run failed scenario

ローカル（k3d）

discover bug → fix code → pnpm build →
  ./bin/eh k8s-image push → ./bin/eh k8s deploy →
  re-run failed scenario

環境の検出と待機パターンについては、references/deploy-cycle-patterns.md を参照してください。

シナリオの洗い出し

対象アプリで作成すべきシナリオを特定する方法：

1. マニフェストを読む — すべてのサービスが検証対象です
2. エージェント設定を読む — すべてのエージェントに動作テストが必要です
3. API 仕様を読む — すべてのエンドポイントグループがシナリオの候補です
4. アップロード／インポートの操作面を確認する — 受け入れるすべてのファイル種別にフィクスチャが必要です
5. パイプラインを確認する — ビルド／デプロイ／ワークフローのパイプラインにはエンドツーエンドの検証が必要です
6. UI を確認する — すべてのページ／ルートに視覚的な検証が必要です
7. インテグレーションを確認する — Webhook、チャットゲートウェイ、外部 API

最小シナリオセット

シナリオ	必須	対象範囲
00-smoke	常に	ヘルスチェック、認証、接続性、および Eve 適合性チェックリスト
01-deploy	常に	パイプライン経由でのビルド、リリース、デプロイ、およびエンドポイントの検証
02-core-flow	常に	主要なユーザージャーニーのエンドツーエンド検証（CLI + API）
03-ui-visual	フロントエンドがある場合	スクリーンショットによる検証、SSO ログイン、ダークモード／ライトモード
04-input-ingestion	アップロード／インポートがある場合	フィクスチャのアップロード、解析、保存、エラー処理
05-data-layer	データベースがある場合	パイプライン経由のマイグレーション、スキーマの正確性、データの整合性
06-agent-execution	エージェントがある場合	エージェントが主要タスクを正しく完了すること
07-agent-optimization	エージェントがある場合	ベースライン指標と最適化の実施
08-pipeline-flows	パイプラインがある場合	各パイプラインのエンドツーエンド実行と、各ステップが順番どおりに成功すること

検証計画の実行

順次実行

# Run scenarios in order
for plan in e2e-verification/*/; do
  echo "=== Running: $plan ==="
  # Agent reads and executes the plan document
done

並列実行

Parallel Safe: Yes と記されたシナリオは並行して実行できます。通常は次のように実行します。

• 00-smoke を最初に実行します（前提条件を検証します）
• 01-deploy から 03-ui-visual までは並列実行できます
• エージェントのシナリオ（06-07）はデプロイの完了後に実行します

CI への統合

# In CI, set environment and run
export EVE_API_URL=https://api.eve.example.com
eve auth login --email $CI_EMAIL --ssh-key $CI_SSH_KEY

# Run all scenarios, collect artifacts
mkdir -p e2e-verification/artifacts
# Agent executes each plan, screenshots/logs go to artifacts/

ファイル構成

<project-root>/
  e2e-verification/
    README.md                    # Index of all scenarios
    00-smoke/
      00-smoke-test-plan.md
    01-deploy/
      01-deploy-test-plan.md
    02-core-flow/
      02-core-flow-test-plan.md
      fixtures/
        README.md
        test-data.json
    03-ui-visual/
      03-ui-visual-test-plan.md
    04-input-ingestion/
      04-input-ingestion-test-plan.md
      fixtures/
        README.md
        sample-document.pdf
        sample-import.csv
        scripts/
          make-fixtures.sh
    artifacts/                   # Generated during runs (gitignored)

番号付け：NN-kebab-name/ ディレクトリには、対応する NN-kebab-name-test-plan.md を配置します。番号は実行順を示します。番号に抜けがあっても問題ありません。名前を変更せずにシナリオを挿入できます。

フィクスチャ：アップロードまたはインポートされた入力に依存する各シナリオには、同じ階層に fixtures/ ディレクトリを用意します。fixtures/README.md には、出所、生成手順、機密性に関する注記を記録します。

参考資料

• references/test-plan-format.md — 注釈付きの例を含む、完全なフォーマット仕様
• references/eve-conformance-checks.md — Eve の手法：検証対象とその理由
• references/fixture-patterns.md — フィクスチャの入手、作成、記録
• references/deploy-cycle-patterns.md — クラウドおよびローカル環境での修正／デプロイのサイクル
• references/ui-verification-patterns.md — ブラウザー自動化と SSO 認証のパターン
• references/agent-verification-patterns.md — エージェントのテストと最適化の統合

テンプレート

• templates/00-smoke-test-plan.md — スモークテストと適合性チェックのスターターテンプレート
• templates/scenario-test-plan.md — 汎用シナリオのひな形
• templates/upload-ingest-test-plan.md — フィクスチャのマトリックスを含む、入力が多いシナリオ

関連スキル

スキル	関連性
eve-agent-optimisation	エージェント検証シナリオから呼び出されます
eve-web-ui-testing-agent-browser	UI 検証ツール
eve-deploy-debugging	デプロイサイクルのトラブルシューティング
eve-cli-primitives	サービスレイヤーのテストで使用する CLI コマンド
eve-manifest-authoring	適合性チェックで検証するマニフェストの規約
eve-app-cli	アプリ CLI のパターン — 検証では CLI の同等性を確認します
eve-pipelines-workflows	パイプラインのシナリオでテストするパイプラインの規約
eve-auth-and-secrets	適合性チェックで検証する認証とシークレットのモデル
eve-troubleshooting	検証に失敗した場合の一般的なデバッグ
eve-read-eve-docs	現在の CLI／マニフェスト／認証の動作を確認するための参考資料
eve-agent-native-design	適合性チェックに反映されている設計原則