ステップアクションリファレンス

QA プランの各ステップは、http_request または browser の 2 つのアクションタイプのいずれかを実行します。AI エージェントが MCP ツールを通じて QA プランを構築する際に、これらのアクションを選択・設定します。このページでは、両方の完全な設定スキーマを説明します。

http_request

http_request アクションは HTTP リクエストを送信し、レスポンスを検証します。

HttpRequestConfig

フィールド	型	必須	説明
method	string	はい	HTTP メソッド：GET、POST、PUT、PATCH、DELETE など。
url	string	はい	リクエスト URL です。テンプレート変数をサポートします（例：{{base_url}}/api/users）。
headers	Record<string, string>	いいえ	キーバリューペアのリクエストヘッダーです。値はテンプレート変数をサポートします。
body	any	いいえ	リクエストボディです。オブジェクトは JSON としてシリアライズされます。文字列値ではテンプレート変数をサポートします。
timeout	number	いいえ	リクエストタイムアウト（ミリ秒）です。
poll	PollConfig	いいえ	条件が満たされるまでエンドポイントをポーリングします。

PollConfig

一部の API エンドポイントではポーリングが必要です。条件が満たされるまでリクエストを繰り返します。poll を指定すると、until 条件が満たされるかタイムアウトに達するまで、一定間隔でリクエストが繰り返されます。

フィールド	型	必須	説明
until	object	はい	チェックする条件です。以下のサブフィールドのいずれかを指定する必要があります。
until.status_code	number	いいえ	レスポンスステータスコードがこの値と一致するまでポーリングします。
until.json_path	object	いいえ	レスポンスボディの JSON パスが一致するまでポーリングします。path（文字列）と expected（任意）を含みます。
interval_ms	number	はい	各ポーリングリクエスト間の待機時間（ミリ秒）です。
timeout_ms	number	はい	ポーリングが失敗とみなされるまでの最大合計時間（ミリ秒）です。

ポーリングの例 — 非同期ジョブの完了を待機:

{
  "action": "http_request",
  "config": {
    "method": "GET",
    "url": "{{api_base_url}}/jobs/{{job_id}}"
  },
  "poll": {
    "until": {
      "json_path": "$.status",
      "equals": "completed"
    },
    "interval_ms": 2000,
    "timeout_ms": 60000
  }
}

Extract

extract フィールドは HTTP レスポンスから値をキャプチャし、後続のステップで使用できるようにします。各抽出は JSONPath 式を使用してレスポンスボディ内の値を特定します。抽出された値は {{variable_name}} でアクセス可能なテンプレート変数になります。

{
  "extract": {
    "user_id": "$.data.id",
    "user_name": "$.data.name"
  }
}

このステップの実行後、{{user_id}} と {{user_name}} がすべての後続ステップで利用可能になります。

使用例

以下の例では、ユーザーを作成し、返された ID を抽出した後、ユーザーを取得して正しく作成されたことを検証します。

ステップ 1 — ユーザーの作成:

{
  "step_key": "create_user",
  "action": "http_request",
  "config": {
    "method": "POST",
    "url": "{{api_base_url}}/users",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer {{auth_token}}"
    },
    "body": "{\"name\": \"Test User\", \"email\": \"test@example.com\"}"
  },
  "assertions": [
    { "type": "status_code", "expected": 201 },
    { "type": "json_path", "expression": "$.data.name", "equals": "Test User" }
  ],
  "extract": {
    "created_user_id": "$.data.id"
  }
}

ステップ 2 — ユーザーの取得:

{
  "step_key": "get_user",
  "action": "http_request",
  "depends_on": ["create_user"],
  "config": {
    "method": "GET",
    "url": "{{api_base_url}}/users/{{created_user_id}}",
    "headers": {
      "Authorization": "Bearer {{auth_token}}"
    }
  },
  "assertions": [
    { "type": "status_code", "expected": 200 },
    { "type": "json_path", "expression": "$.data.email", "equals": "test@example.com" }
  ]
}

ステップ条件

ステップの condition フィールドは、変数の値に基づいてステップを実行するかどうかを制御します。条件が満たされない場合、ステップはスキップされます（depends_on や requires によるスキップと同じ動作です）。

条件チェックは depends_on のチェック後に評価されます。条件で参照する変数は通常、先行ステップの extract から取得します。

ConditionConfig

フィールド	型	必須	説明
type	string	はい	条件タイプ："variable_equals" または "variable_not_equals" です。
variable	string	はい	チェックする変数名です。
value	string	はい	比較する値です。

variable_equals

変数が指定された値と等しい場合のみステップを実行します。変数が未定義の場合、条件は満たされず、ステップはスキップされます。

{
  "condition": {
    "type": "variable_equals",
    "variable": "user_role",
    "value": "admin"
  }
}

variable_not_equals

変数が指定された値と等しくない場合のみステップを実行します。変数が未定義の場合、条件は満たされ、ステップは実行されます。

{
  "condition": {
    "type": "variable_not_equals",
    "variable": "payment_method",
    "value": "free"
  }
}

browser

browser アクションは、Playwright を使用してヘッドレスブラウザを操作します。

BrowserConfig

フィールド	型	必須	説明
steps	BrowserStep[]	はい	実行するブラウザアクションの順序付き配列です。
timeout_ms	number	いいえ	ブラウザアクションシーケンス全体の最大時間（ミリ秒）です。

ブラウザステップタイプ

steps 配列の各エントリは、type フィールドとタイプ固有のパラメータを持つオブジェクトです。

ナビゲーション

タイプ	パラメータ	説明
goto	string（URL）	URL に遷移します。テンプレート変数をサポートします。

ノート

goto アクションが失敗した場合（例: ページがエラーを返した場合）、現在のシナリオの残りのアクションはすべて中止されます。

マウスアクション

タイプ	パラメータ	説明
click	string（CSS セレクタ）	要素をクリックします。
double_click	string（CSS セレクタ）	要素をダブルクリックします。
hover	string（CSS セレクタ）	要素にホバーします。

フォーム入力

タイプ	パラメータ	説明
type	{ selector: string, text: string }	入力フィールドにテキストを入力します。両方のフィールドでテンプレート変数をサポートします。
select_option	{ selector: string, value: string }	<select> 要素で値を指定してオプションを選択します。
check	string（CSS セレクタ）	チェックボックスをチェックします。
uncheck	string（CSS セレクタ）	チェックボックスのチェックを外します。
press	{ selector: string, key: string }	要素にフォーカスした状態でキーボードキーを押します（例：Enter、Tab）。
focus	string（CSS セレクタ）	要素にフォーカスします。
upload_file	{ selector: string, path: string }	ファイル入力要素にファイルをアップロードします。

待機

タイプ	パラメータ	説明
wait_for_selector	string（CSS セレクタ）	セレクタに一致する要素が DOM に表示されるまで待機します。
wait_for_url	string（URL 部分文字列）	ページの URL が指定した部分文字列を含むまで待機します。

キャプチャ

タイプ	パラメータ	説明
screenshot	string（名前）	スクリーンショットを撮影し、指定した名前で保存します。

ヘッダー

タイプ	パラメータ	説明
set_header	Record<string, string>	後続のブラウザリクエストにカスタム HTTP ヘッダーを設定します。

フレーム

タイプ	パラメータ	説明
switch_to_frame	string（CSS セレクタ）	セレクタで指定された iframe に実行コンテキストを切り替えます。
switch_to_main_frame	true	メインフレームに戻ります。

ブラウザコンテキストと状態

シナリオ内

ブラウザコンテキストは単一のシナリオ内のすべてのステップで共有されます。これは以下を意味します。

• ログインセッションはステップ間で維持されます。
• Cookie と localStorage は保持されます。
• ナビゲーション履歴は維持されます。

シナリオ間

ブラウザの storageState（Cookie と localStorage）は、あるシナリオから次のシナリオに引き継がれます。これにより、初期のシナリオでログインを行い、認証フローを繰り返すことなく、以降のすべてのシナリオでそのセッションを利用できます。

使用例

以下の例では、ログインフローをテストし、ユーザーがダッシュボードに到達することを検証します。

ステップ 1 — ログイン:

{
  "step_key": "login",
  "action": "browser",
  "config": {
    "steps": [
      { "type": "goto", "url": "{{web_base_url}}/login" },
      { "type": "type", "selector": "#email", "text": "{{test_email}}" },
      { "type": "type", "selector": "#password", "text": "{{test_password}}" },
      { "type": "click", "selector": "button[type='submit']" },
      { "type": "wait_for_url", "url": "/dashboard" }
    ],
    "timeout_ms": 15000
  },
  "assertions": [
    { "type": "url_contains", "expected": "/dashboard" },
    { "type": "element_visible", "selector": "[data-testid='welcome-message']" }
  ]
}

ステップ 2 — ダッシュボードの内容を検証:

{
  "step_key": "verify_dashboard",
  "action": "browser",
  "depends_on": ["login"],
  "config": {
    "steps": [
      { "action": "wait_for_selector", "selector": "[data-testid='user-name']" }
    ]
  },
  "assertions": [
    { "type": "element_text", "selector": "[data-testid='user-name']", "expected": "Test User" },
    { "type": "element_visible", "selector": "[data-testid='recent-activity']" }
  ]
}