環境設定

環境設定は、QAプランの実行に必要なターゲットURL、認証情報、その他の設定を定義します。環境ファイルはローカルに保存され、サーバーに送信されることはないため、機密データはお使いのマシン上に保持されます。

ファイルの保存場所

環境ファイルは以下の場所に保存されます。

.aqua/environments/<name>.json

各ファイルは名前付きの環境を表します（例: local.json、staging.json、production.json）。.aqua/ ディレクトリはリポジトリにコミットして、チーム全体で環境設定を共有することを推奨します。外部ソースを参照するシークレットタイプ（env、op、aws_sm など）を使用すれば、ファイルには参照のみが保存され実際の機密値は含まれないため、安全にコミットできます。

ファイルスキーマ

完全な環境ファイルは以下の構造を持ちます。

{
  "notes": "環境に関する Markdown メモ",
  "variables": {
    "api_base_url": "http://localhost:8000",
    "web_base_url": "http://localhost:3000",
    ...
  },
  "secrets": {
    "api_key": { "type": "literal", "value": "dev-key-123" },
    "auth_token": { "type": "env", "value": "STAGING_AUTH_TOKEN" },
    "db_password": { "type": "op", "value": "op://Development/staging-db/password" },
    ...
  },
  "secret_providers": {
    "aws_sm": { "region": "ap-northeast-1", "profile": "staging" },
    "gcp_sm": { "project": "my-project-123" },
    "hcv": { "address": "https://vault.example.com:8200" }
  },
  "proxy": {
    "server": "http://proxy.corp.com:3128",
    "bypass": "localhost,.internal.com",
    "username": { "type": "literal", "value": "user" },
    "password": { "type": "env", "value": "PROXY_PASSWORD" },
    "ca_cert_path": "/path/to/ca.pem",
    "reject_unauthorized": false
  }
}

variables 以外のすべてのセクションは任意です。

変数

variables オブジェクトにはプレーンなキーバリューペアが含まれます。キー名は QA プランで参照される名前に合わせて自由に定義できます。変数は {{variable_name}} 構文を使用してプランテンプレートに代入されます。

たとえば、QA プランのステップに URL {{api_base_url}}/users がある場合、環境ファイルで api_base_url を定義して値を提供します。

慣例として以下の2つの変数名が使用されます。

変数	用途
`api_base_url`	HTTP APIリクエストのベースURLです。
`web_base_url`	ブラウザベースのテストのベースURLです。

変数の優先順位

同じ変数が複数の場所で定義されている場合、以下の優先順位が適用されます（上位が優先）。

実行時のオーバーライド — 実行時に渡される値です。
環境ファイル — .aqua/environments/<name>.json の値です。
プランのデフォルト — QAPlanVersion で定義されたデフォルト値です。

シークレット

シークレットは変数と同様に機能しますが、APIキー、認証トークン、パスワードなどの機密値を保持します。変数と同じく、キー名は QA プランで参照される名前に合わせて自由に定義できます。違いは、各シークレットが値の解決方法を決定する type を持つことと、解決された値がサーバーに送信される前に必ずマスクされることです。

解決されたシークレットはプレーンな変数と同じ名前空間にマージされ、プランテンプレートで同じ {{secret_name}} 構文で参照できます。

シークレットの種類

種類	説明	例
`literal`	値はそのまま使用されます。	`{ "type": "literal", "value": "dev-key-123" }`
`env`	値はOSの環境変数から読み取られます。	`{ "type": "env", "value": "STAGING_AUTH_TOKEN" }`
`op`	1Password CLI から値を取得します。	`{ "type": "op", "value": "op://vault/item/field" }`
`aws_sm`	AWS Secrets Manager から値を取得します。	`{ "type": "aws_sm", "value": "staging/db-creds" }`
`gcp_sm`	GCP Secret Manager から値を取得します。	`{ "type": "gcp_sm", "value": "api-key" }`
`hcv`	HashiCorp Vault から値を取得します。	`{ "type": "hcv", "value": "myapp/keys" }`

クラウドシークレットマネージャーのオプション

aws_sm、gcp_sm、hcv タイプは、詳細な制御のための追加フィールドをサポートしています。

AWS Secrets Manager (aws_sm)

フィールド	説明
`value`	シークレット名または ARN。
`region`	（任意） AWS リージョン。プロバイダーレベルの設定をオーバーライドします。
`json_key`	（任意） JSON 形式のシークレットから特定のキーを抽出します。

GCP Secret Manager (gcp_sm)

フィールド	説明
`value`	シークレット名。
`project`	（任意） GCP プロジェクト ID。プロバイダーレベルの設定をオーバーライドします。
`version`	（任意）シークレットのバージョン。デフォルトは `latest`。
`json_key`	（任意） JSON 形式のシークレットから特定のキーを抽出します。

HashiCorp Vault (hcv)

フィールド	説明
`value`	シークレットのパス。
`field`	（任意）シークレットから特定のフィールドを抽出します。
`mount`	（任意） KV マウントポイント。デフォルトは `secret`。

シークレットプロバイダー

secret_providers セクションでは、各外部シークレットタイプのデフォルト設定を定義します。個々のシークレットエントリのフィールドがプロバイダーレベルの設定をオーバーライドします。

{
  "secret_providers": {
    "aws_sm": {
      "region": "ap-northeast-1",
      "profile": "staging"
    },
    "gcp_sm": {
      "project": "my-project-123"
    },
    "hcv": {
      "address": "https://vault.example.com:8200",
      "namespace": "staging"
    }
  }
}

これにより、すべてのシークレットエントリで同じリージョンやプロジェクトを繰り返す必要がなくなります。たとえば、すべての AWS シークレットが ap-northeast-1 にある場合、secret_providers.aws_sm で一度設定すれば、個々のエントリでは省略できます。

遅延解決

実際に現在のプランで参照されているシークレットのみが解決されます。環境ファイルに10個のシークレットが定義されていても、プランが使用するのが2個だけであれば、その2個のみが参照されます。これにより、外部のシークレットマネージャーへの不要な呼び出しが回避され、設定されていない未使用のシークレットによるエラーが防止されます。

シークレットのマスキング

aqua サーバーにデータを送信する前に、すべての解決済みシークレット値は *** に置き換えられます。これにより、実行結果がサーバーに記録される場合でも、機密情報がお使いのマシンから外に出ることはありません。マスキングは環境の値、HTTP リクエスト・レスポンスヘッダー、DOM スナップショットなど複数のレイヤーにわたって適用されます。

プロキシ

任意の proxy セクションは、テスト実行中のアウトバウンドリクエストに対するHTTPプロキシを構成します。

フィールド	説明
`server`	プロキシサーバーのURL（例: `http://proxy.corp.com:3128`）です。
`bypass`	プロキシをバイパスするホストのカンマ区切りリストです。
`username`	（任意）プロキシ認証のユーザー名です。シークレットと同じ type 形式を使用します。
`password`	（任意）プロキシ認証のパスワードです。シークレットと同じ type 形式を使用します。
`ca_cert_path`	（任意）接続先サーバーの TLS 検証に使用する CA 証明書ファイルのパスです（自己署名証明書や SSL インターセプトプロキシ環境向け）。
`proxy_ca_cert_path`	（任意）プロキシサーバー自体の CA 証明書ファイルのパスです（HTTPS プロキシが独自 CA を使用する場合）。
`reject_unauthorized`	（任意） `false` に設定すると、プロキシと接続先の両方で TLS 証明書検証をスキップします。

ノート

notes フィールドは Markdown テキストを受け付け、以下のような環境固有の情報を記録することを目的としています。

テスト実行前に満たす必要がある前提条件。
環境の既知の制約や制限事項。
テストアカウントの認証情報やセットアップ手順。
環境固有のドキュメントへのリンク。

ノートは環境ファイルとともにローカルに保存され、QAセッション中にターゲット環境に関するコンテキストを提供するためにAIエージェントが利用できます。