QAプラン

QAプランは aqua の中心的なオブジェクトです。テストシナリオとステップを構造化されたバージョン管理ドキュメントとして整理し、任意の環境に対して実行できます。

データモデルの階層構造

QAプランのデータモデルは4階層の構造に従います。

QAPlan
 └─ QAPlanVersion
     └─ Scenario
         └─ Step

各階層にはそれぞれ固有の役割があります。

• QAPlan — テストプラン全体を表すトップレベルのコンテナです。
• QAPlanVersion — ある時点のプランの不変スナップショットです。
• Scenario — 関連するテストステップをまとめた名前付きグループです。
• Step — 個々のテストアクション（HTTPリクエストまたはブラウザ操作）です。

QAPlan

QAPlan はテストプラン全体のメタデータを保持します。

フィールド	説明
name	プランの人間が読みやすい名前です。
description	プランが何をテストするかの説明です。
git_branch	（任意） このプランに関連付けられた Git ブランチです。
pull_request_url	（任意） 関連するプルリクエストへのリンクです。
status	現在のライフサイクルステータス: draft、active、archived のいずれかです。

QAPlanVersion

プランの内容を更新するたびに、新しい QAPlanVersion が作成されます。バージョンは不変のスナップショットであり、一度作成されると変更できません。各バージョンには自動採番されたバージョン番号が付与されます。

バージョンには以下が含まれます。

• variables — シナリオとステップ全体で使用されるデフォルトの変数値です。
• scenarios — シナリオとそのステップの順序付きリストです。

不変性により、実行結果は常にテストされた正確なプラン内容を参照することが保証されます。

Scenario

シナリオは、特定の動作やワークフローを検証するステップの名前付きグループです。

フィールド	説明
name	シナリオの説明的な名前です。
requires	（任意） 必要な変数名のリストです。必須変数のいずれかが環境に存在しない場合、そのシナリオはスキップされます。
steps	実行するステップの順序付きリストです。

requires フィールドを使用すると条件付き実行が可能になります。例えば、管理者機能をテストするシナリオで requires: ["admin_token"] と宣言すると、その変数を提供しない環境に対して実行する際に自動的にスキップされます。

Step

ステップはテストの最小単位であり、オプションのアサーションと値の抽出を伴う単一のアクションです。

フィールド	説明
step_key	ユーザー定義の一意な識別子です。依存関係の参照に使用されます。
action	アクションの種類: "http_request" または "browser" です。
depends_on	（任意） このステップの実行前に完了している必要がある step_key 参照のリストです。依存関係はシナリオの境界を越えることができます。
assertions	（任意） ステップの結果に対して実行するバリデーションチェックです。
extract	（任意） 結果から値を抽出し、後続のステップでテンプレート変数（{{variable}}）として使用できるようにします。
condition	（任意） ステップを実行するための条件です。条件が満たされない場合、ステップはスキップされます。詳細は条件付きステップ実行を参照してください。

ステップの依存関係

depends_on フィールドを使用すると、ステップ間の実行順序の制約を表現できます。依存関係は同じシナリオ内のステップキーだけでなく、異なるシナリオのステップキーも参照できるため、複雑なテストフローを柔軟にモデル化できます。

依存先のステップが失敗またはスキップされた場合、依存するステップもスキップされます。

値の抽出

extract フィールドを使用すると、ステップのレスポンスから値をキャプチャし、テンプレート変数として利用可能にできます。抽出された変数はグローバルであり、任意のシナリオの後続のステップから参照できます。

例えば、APIコールでリソースを作成した後、返された id を抽出し、以降のステップで {{resource_id}} として使用できます。

条件付きステップ実行

condition フィールドを使用すると、変数の値に基づいてステップの実行を制御できます。条件は depends_on のチェック後に評価されます。以下の2つの条件タイプがサポートされています。

• variable_equals — 変数が特定の値と等しい場合のみステップを実行します。
• variable_not_equals — 変数が特定の値と等しくない場合のみステップを実行します。

変数が未定義の場合、variable_equals 条件は満たされず（ステップはスキップ）、variable_not_equals 条件は満たされます（ステップは実行）。

条件付きステップは通常、depends_on で後続のステップに接続されない独立した準備ステップとして使用されます。条件で使用する変数は、先行ステップの extract から取得します。

例 — ユーザーのロールに基づいて異なるセットアップステップを実行:

{
  "step_key": "check_role",
  "action": "http_request",
  "config": {
    "method": "GET",
    "url": "{{api_base_url}}/users/me",
    "headers": { "Authorization": "Bearer {{auth_token}}" }
  },
  "extract": {
    "user_role": "$.data.role"
  }
}

{
  "step_key": "admin_setup",
  "action": "http_request",
  "condition": {
    "type": "variable_equals",
    "variable": "user_role",
    "value": "admin"
  },
  "config": {
    "method": "POST",
    "url": "{{api_base_url}}/admin/prepare-test-data",
    "headers": { "Authorization": "Bearer {{auth_token}}" }
  }
}

この例では、admin_setup ステップは抽出された user_role 変数が "admin" と等しい場合のみ実行されます。それ以外の場合、ステップはスキップされます。

ステータスライフサイクル

QAプランは3つのステータスを遷移します。

draft  ◀──▶  active  ──▶  archived

ステータス	意味
draft	プランは開発中、または更新されたばかりです。編集と実行が可能です。
active	すべてのテストが成功すると自動的に昇格されます。検証済みで成功しているプランを表します。
archived	プランは使用されなくなりました。

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

自動降格: active なプランに新しいバージョンが追加されると、ステータスは自動的に draft に戻ります。テスト内容が変更されたため、新しいバージョンを実行して再検証する必要があります。

シナリオ間の状態共有

aqua にはシナリオ間で状態を共有する2つのメカニズムがあります。

1. Extract 変数 — 任意のステップで抽出された値はグローバルに利用可能です。シナリオ A で抽出された変数は、{{variable}} テンプレートを使用してシナリオ B から参照できます。
2. ブラウザの storageState — ブラウザドライバーを使用する場合、Cookie と localStorage はブラウザの storageState を通じてシナリオ間で保持されます。これにより、あるシナリオで行ったログインが、認証ステップを繰り返すことなく後続のシナリオに引き継がれます。