実行

QAプランの準備ができたら、2つの方法で実行できます。コーディングエージェントに実行を依頼する方法と、CLIから直接実行する方法です。どちらの方法でもシークレットはローカルで解決され、生の認証情報が aqua サーバーに送信されることはありません。

コーディングエージェント経由での実行

最も一般的な実行方法は、コーディングエージェントを通じて行う方法です。エージェントに対し、特定の環境に対してプランを実行するよう依頼します。

プロンプト例：

local 環境に対して QA プランを実行して。

エージェントが execute_qa_plan MCP ツールを呼び出し、以下の処理が行われます。

環境ファイルを読み込み、変数とシークレットをローカルで解決します。
各シナリオとステップを順番に実行し、依存関係を尊重します。
結果を aqua サーバーに記録します。
各ステップの成功/失敗ステータスを含むマークダウン形式のサマリーを返します。

実行後、エージェントが結果の解釈、失敗の特定、プランの調整を支援します。

非同期実行

長時間実行されるプランの場合、非同期実行を使ってプランをバックグラウンドで開始し、後から進捗を確認できます。

staging 環境に対して QA プランを非同期で実行して。

エージェントが execute_qa_plan の async パラメータを true に設定して呼び出します。すべてのシナリオの完了を待つ代わりに、実行 ID と URL を即座に返します。

進捗を確認するには：

その実行の進捗を確認して。

エージェントが実行 ID を指定して get_execution_progress を呼び出し、以下の情報が返されます。

現在のステータス（pending、running、completed、failed）
進捗数（完了済みステップ数 / 総ステップ数）
現在実行中のステップ（ある場合）
完了したステップごとの結果

多数のシナリオや実行に時間がかかるステップを持つプランの場合に便利です。実行中にエージェントが他のタスクに取り組めるようになります。

CLI からの実行

aqua-cli execute コマンドを使用して、コマンドラインから直接プランを実行することもできます。

npx @aquaqa/cli execute <qa_plan_id> --env <name>

オプション

オプション	説明
`<qa_plan_id>`	（必須）実行するQAプランのIDです。
`--env <name>`	`.aqua/environments/<name>.json` から環境変数を読み込みます。
`--plan-version <n>`	特定のプランバージョンを実行します。デフォルトは最新バージョンです。
`--var key=value`	変数の値をオーバーライドします。複数回指定できます。

CI/CD での活用

CLI での実行にはコーディングエージェントや MCP サーバーが不要なため、自動化パイプラインに適しています。CI/CD ワークフローに aqua を組み込むことで、デプロイやプルリクエストのたびに QA プランを実行できます。

例：GitHub Actions

- name: Run QA plan
  run: npx @aquaqa/cli execute ${{ vars.QA_PLAN_ID }} --env ci

CI 環境用の環境ファイル（.aqua/environments/ci.json）を作成し、適切なターゲット URL と認証情報を設定します。機密値には env シークレットタイプを使用して、CI の環境変数から読み取ることができます。

実行フロー

プランが実行されると、aqua は以下の順序で処理を行います。

変数の解決 — 変数は3つのソースから優先順位に従ってマージされます。実行時のオーバーライド（最高優先）、環境ファイル、プランのデフォルト（最低優先）の順です。詳細はテンプレート変数を参照してください。
シークレットの解決 — プランで実際に参照されているシークレットのみが解決されます。シークレット値はサーバーにデータが送信される前に *** でマスクされます。
シナリオの実行 — シナリオは順番に実行されます。シナリオに requires フィールドが宣言されていて、必要な変数が存在しない場合、そのシナリオはスキップされます。
ステップの実行 — 各シナリオ内のステップは depends_on 制約を尊重しながら順番に実行されます。依存先のステップが失敗またはスキップされた場合、依存するステップもスキップされます。
条件の評価 — ステップに condition フィールドがある場合、依存関係の解決後に条件がチェックされます。条件が満たされない場合（例：変数が期待値と等しくない場合）、ステップはスキップされます。詳細は条件付きステップ実行を参照してください。
アサーション — 各ステップの完了後、アサーションが評価されます。すべてのアサーションが成功するとステップは合格です。
値の抽出 — ステップのレスポンスから抽出された値は、後続のステップのテンプレート変数として利用可能になります。

シナリオ間の状態共有

シナリオ間で状態が共有される仕組みが2つあります。

抽出された変数はグローバルです — あるシナリオで抽出された値は、後続の任意のシナリオから参照できます。
ブラウザの状態（Cookie と localStorage）はシナリオ間で保持されるため、あるシナリオで行ったログインが次のシナリオに引き継がれます。

結果の確認

エージェントセッション内

実行後、エージェントは以下を含むサマリーを表示します。

全体の成功/失敗ステータス
シナリオ別・ステップ別の結果
失敗したステップのエラー詳細
aqua Web UI での完全な結果へのリンク

特定の失敗について、エージェントにより詳しく確認を依頼できます。

「期限切れカードでのチェックアウト」シナリオで何が問題だった？

Web UI

aqua Web UI では、各実行の詳細なビューを確認できます。

HTTP ステップの完全なリクエスト・レスポンスデータ
ブラウザステップのスクリーンショットとブラウザログ
期待値と実測値を含むアサーション結果
実行タイムライン

Web UI は以下のコマンドで開けます。

npx @aquaqa/cli web

MCP ツール経由

エージェントは get_execution や list_executions MCP ツールを使用して、過去の実行結果をプログラム的に取得することもできます。実行間の結果比較やリグレッションの追跡に便利です。

結果の共有

実行結果をチームメンバー、ステークホルダー、その他の人と共有できます。aqua のアカウントを持っていない人にも共有可能です。共有リンクを使うと、シナリオ、ステップ、アサーション、アーティファクトを含む実行結果の全体を読み取り専用で閲覧できます。

共有リンクの作成

Web UI で実行詳細ページを開きます。
右上の Share ボタンをクリックします。
有効期限（3日間または30日間）を選択します。
Create share link をクリックします。
リンクをコピーして共有します。

共有リンクはログイン不要で実行結果にフルアクセスできます。各 Execution につき一度に1つの有効な共有リンクを持てます。

共有リンクの取り消し

共有 Execution へのアクセスを取り消す必要がある場合：

実行詳細ページを開き、Share をクリックします。
ダイアログ下部の Revoke share link をクリックします。

リンクの作成者または Organization の Admin 以上の権限を持つユーザーが共有リンクを取り消せます。取り消すと、リンクは即座に無効になります。

共有される内容

共有ビューには以下が含まれます：

実行ステータスと時間情報
すべてのシナリオとステップの結果
アサーション結果（期待値と実測値を含む成功/失敗）
アーティファクト（HTTP リクエスト/レスポンスデータ、スクリーンショット）
環境変数（シークレットは記録前に *** でマスク済み）

プランの再実行

プランやアプリケーションの問題を修正した後、すぐにプランを再実行できます。

もう一度 local 環境に対してプランを実行して。

特定のバージョンのプランを実行することもできます。

npx @aquaqa/cli execute <qa_plan_id> --env local --plan-version 3

また、一回限りの実行のために特定の変数をオーバーライドすることもできます。

npx @aquaqa/cli execute <qa_plan_id> --env local --var api_base_url=http://localhost:4000

ステータスの自動遷移

すべてのステップが成功した状態で実行が完了すると、プランのステータスは自動的に draft から active に昇格されます。これにより、検証済みで完全に合格したプランのみが active ステータスを持つことが保証されます。

逆に、active なプランに新しいバージョンが追加されると、ステータスは自動的に draft に戻り、再検証が必要になります。

ステータスライフサイクルの詳細は QA プランを参照してください。