ランナーの実行方法（ローカル / GitHub Actions / オフライン）

AI 探索的テストの実行本体（ランナー）は、Testrategy のサーバーではなく あなたの環境 で動きます。実行方法は 3 つあり、どれを選んでも Testrategy の画面に結果が反映されます（オフラインを除く）。

AI の API キーは、ランナーを動かす環境の環境変数にだけ設定します。Testrategy の画面には入力せず、Testrategy に保存・送信されることもありません。利用料金はお使いの AI アカウントに課金されます。

どの方法を選ぶ？

判断の目安:

• 対象システムが 社内ネットワークからしか見えない → A（GitHub Actions のランナーからは到達できません）
• 数十分〜2 時間の長い実行 を PC を離れて回したい → B
• Testrategy のプロジェクトをまだ作っていない、動作だけ確かめたい → C

共通の準備（A / B）

1. ランナートークンを発行する: プロジェクトの「AI テスト実行」画面下部「ランナー設定」でトークン名を入力して発行します。平文は発行直後に 1 回だけ表示されるので、必ずコピーしてください。
2. AI の API キーを用意する: 実行の作成時に選んだプロバイダのキーです。Anthropic なら ANTHROPIC_API_KEY、OpenAI（ChatGPT / GPT）なら OPENAI_API_KEY という名前の環境変数に設定します。
3. 実行を作成する: 「＋ 新規テスト実行」で対象 URL・観点・実行時間・AI を指定します。作成後の詳細画面「実行方法」タブに、選んだプロバイダに合わせた実行 ID 入りのコマンドが表示されます。

ChatGPT（OpenAI の GPT モデル）を使う場合

ChatGPT と同じ OpenAI のモデルを使えます。手順は Claude の場合と同じで、違いは次の 3 点だけです。

• API キーは OpenAI Platform の API keys で発行します。ChatGPT Plus / Pro の契約では発行できません。OpenAI Platform 側で支払い方法を登録し、API の従量課金として請求されます。
• 「実行方法」タブのコマンドは、実行作成時に OpenAI を選んでいれば自動的に OPENAI_API_KEY を使う内容になります。以降の A / B / C の例で ANTHROPIC_API_KEY と書かれている箇所を OPENAI_API_KEY に読み替えてください。
• ランナー側のオプション --effort は Anthropic 専用で、OpenAI では無視されます。

A. ローカル PC で実行する

必要なもの

• Node.js 22 以上の最新パッチ版（node -v で確認。Node 20 は 2026 年 4 月でサポート終了のためセキュリティ修正が出ません。2026 年 10 月のセキュリティリリース以降は 22.23.4 / 24.22.1 / 26.12.1 以上を推奨）
• Playwright の Chromium。初回のみ次を実行します。

npx playwright install chromium

手順（macOS / Linux、bash・zsh）

「実行方法」タブの ローカル（bash / zsh） に表示されるコマンドをそのまま貼り付けます。<ランナートークン> と <ANTHROPIC_API_KEY> を自分の値に置き換えてください。

export TESTRATEGY_API_BASE="https://testrategy.app"
export TESTRATEGY_RUNNER_TOKEN="<ランナートークン>"
export ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>"
npx testrategy-explorer

npx testrategy-explorer は、トークンのプロジェクトで 「待機中」の実行を作成順に自動で選んで 動かします。実行を削除して作り直しても同じコマンドで動きます。複数の実行が待機中なら、終了後にもう一度起動すると次の実行を処理します。

特定の実行だけを動かしたいときは --run-id <実行 ID> を付けます。ただし 実行 ID はその実行だけに紐づく ので、実行を削除して作り直すと以前の ID は無効になり、「実行が見つかりません」で止まります。ID は詳細画面の「実行方法」タブに表示されています。

手順（Windows、PowerShell）

ローカル（PowerShell） タブのコマンドを使います。

$env:TESTRATEGY_API_BASE = "https://testrategy.app"
$env:TESTRATEGY_RUNNER_TOKEN = "<ランナートークン>"
$env:ANTHROPIC_API_KEY = "<ANTHROPIC_API_KEY>"
npx testrategy-explorer

ChatGPT（OpenAI）の場合の例

実行作成時に「OpenAI (ChatGPT / GPT)」を選んだ実行では、キーの環境変数が OPENAI_API_KEY になります。

export TESTRATEGY_API_BASE="https://testrategy.app"
export TESTRATEGY_RUNNER_TOKEN="<ランナートークン>"
export OPENAI_API_KEY="<OPENAI_API_KEY>"
npx testrategy-explorer --run-id <実行 ID>

$env:TESTRATEGY_API_BASE = "https://testrategy.app"
$env:TESTRATEGY_RUNNER_TOKEN = "<ランナートークン>"
$env:OPENAI_API_KEY = "<OPENAI_API_KEY>"
npx testrategy-explorer --run-id <実行 ID>

実行中に起きること

• ターミナルに「#1 設計: …」「step 1: click(e12) → OK」「#1 判定: pass」のように進行が表示されます。
• Testrategy の詳細画面は 5 秒ごとに自動更新され、テストが 1 件終わるごとに一覧・発見事項・分布が増えます。
• 設定時間に達するか、画面の「中止」を押すと停止します。終了時にターミナルへ結果の要約と、exploratory-report/ フォルダへのレポート出力先が表示されます。
• 設定時間は上限です。AI が「各観点を検証し終え、新しい仮説が立たない」と判断した場合は、時間が残っていても終了します。その場合は詳細画面のヘッダーに「設定時間より前に終了しました: 理由」と表示されます。

よく使うオプション

B. GitHub Actions（自分のリポジトリ）で実行する

Testrategy のリポジトリは不要です。あなたのリポジトリ に workflow を 1 つ置き、Secrets を登録するだけです。

手順

1. 「実行方法」タブの GitHub Actions（自分のリポジトリ） に表示される workflow 雛形をコピーし、リポジトリの .github/workflows/testrategy-exploratory.yml として保存します。
2. リポジトリの Settings → Secrets and variables → Actions で次を登録します。
   • TESTRATEGY_RUNNER_TOKEN: 発行したランナートークン
   • ANTHROPIC_API_KEY（Claude の場合）または OPENAI_API_KEY（ChatGPT / OpenAI の場合）: 実行で選んだプロバイダのキー。「実行方法」タブの workflow 雛形は、選んだプロバイダに合わせてどちらか一方だけを参照する内容になっています
3. GitHub の Actions タブで「Testrategy exploratory test」を開き、Run workflow を押して起動します。run_id を空のままにすると待機中の実行を自動選択し、特定の実行だけを動かす場合は実行 ID を入力します。

確認

• 進行状況は Testrategy の詳細画面に反映されます。詳細画面のランナー情報には Actions の実行ログへのリンクも表示されます。
• レポートは Actions の artifact（exploratory-report）にも保存されます。

注意

• Actions の実行時間はあなたのリポジトリに課金されます（GitHub の無料枠を含む）。長い実行を繰り返す場合はご注意ください。
• GitHub のランナーはインターネットから到達できる URL しか操作できません。社内ネットワーク上の環境は方法 A を使ってください。
• 同じ実行 ID を二重に起動しても、2 つ目は開始されません（実行は 1 回しか動かせません）。

C. オフラインで試す（Testrategy に接続しない）

トークンなしで、ランナー単体で探索を試せます。結果は Testrategy には送られず、exploratory-report/ にファイルとして出力されます。

export ANTHROPIC_API_KEY="<ANTHROPIC_API_KEY>"
npx testrategy-explorer --url https://staging.example.com --minutes 5 --perspectives-file perspectives.txt

• perspectives.txt は 1 行 1 観点のテキスト（# で始まる行はコメント）、または JSON 配列です。省略すると汎用的な 4 観点（主要機能の正常系、入力値の境界値、ナビゲーション、エラー表示）で探索します。
• --minutes の代わりに --level 1〜10（画面のスライダーと同じ段階）も使えます。
• ChatGPT（OpenAI）で試す場合は --provider openai（必要なら --model gpt-5 のようにモデルも指定）と OPENAI_API_KEY を使います。

export OPENAI_API_KEY="<OPENAI_API_KEY>"
npx testrategy-explorer --url https://staging.example.com --minutes 5 --provider openai

Claude Pro / Max や ChatGPT Plus / Pro のプランは使えますか？

使えません。テストに使う AI は API キー で呼び出します。

利用料は API の従量課金としてお使いのアカウントに請求されます。Claude Pro / Max、ChatGPT Plus / Pro などのチャット向けサブスクリプションはこの機能の対象外です（API キーとは別の契約です）。

ログインが必要なシステムをテストする

そのまま実行すると、AI はログイン前のページしか操作できません（パスワードは推測しないよう指示しているため、ログインが必要なテストは「ブロック」になります）。方法は 3 つあります。迷ったら方法 0 を使ってください。

方法 0: 実行の最初に自分でログインする（いちばん簡単、ローカル向け）

--manual-login を付けると、ブラウザが表示された状態で起点 URL を開き、AI は動かずに待ちます。いつもどおりログインしてターミナルで Enter を押すと、そのブラウザのまま AI の探索が始まります。SSO や二要素認証でもそのまま使えます。

npx testrategy-explorer --run-id <実行 ID> --manual-login

--save-login auth.json を併せて付けると、ログイン後の状態をファイルに保存し、次回は --storage-state auth.json でログイン操作を省略できます。PC の前で操作できる場合はこれで十分です。GitHub Actions のように人が操作できない環境では方法 1 か 2 を使います。

方法 1: 手動でログインして状態を保存する（SSO / 二要素認証でも使える）

ランナーの login サブコマンドでブラウザが開くので、いつもどおりログインし、終わったらターミナルで Enter を押します。ログイン状態（Cookie など）がファイルに保存されます。

npx testrategy-explorer login --url https://staging.example.com/login --out auth.json

以降の実行で保存したファイルを指定すると、ログイン済みの状態から探索が始まります。

npx testrategy-explorer --run-id <実行 ID> --storage-state auth.json

• Microsoft / Google のシングルサインオンや Magic Link のように、ID とパスワードの入力だけでは済まない方式はこちらを使ってください。
• auth.json にはログインセッションが含まれます。リポジトリにコミットせず、不要になったら削除してください。セッションの有効期限が切れたら login をやり直します。
• GitHub Actions で使う場合は、ファイルの中身を Secret に入れて実行前にファイルへ書き出します（例: echo "$STORAGE_STATE" > auth.json）。

方法 2: ID とパスワードを環境変数で渡す（フォームログインのみ）

ID とパスワードでログインできる画面なら、環境変数に設定するだけで AI が自分でログインします。

export TESTRATEGY_LOGIN_USER="demo@example.com"
export TESTRATEGY_LOGIN_PASSWORD="<テストアカウントのパスワード>"
npx testrategy-explorer --run-id <実行 ID>

• AI には {{LOGIN_USER}} / {{LOGIN_PASSWORD}} というプレースホルダだけを見せ、ランナーが入力の瞬間に実際の値へ置き換えます。実際の値は AI にも Testrategy のレポートにも渡りません。
• 必ずテスト用アカウントを使ってください。二要素認証や SSO がある場合は方法 1 を使います。
• 補足メモに「ログインページは /login、テストアカウントでログインしてから操作すること」のように書いておくと、AI がログインを最初に行いやすくなります（パスワードは補足メモに書かないでください）。

テスト中にログアウトしてしまったら

AI が誤ってログアウトすると、以降のテストがすべて「ブロック」になってしまいます。ランナーは次の 3 段階で対処します。

1. そもそもログアウトさせない: 「ログアウト」「サインアウト」「Log out」などと表示されたボタンやリンクは、AI が押そうとしてもランナーが止めます。ログアウト機能そのものを検証したいときだけ --allow-logout を付けてください。
2. それでもログイン画面に戻されたら通知する: セッションの有効期限切れなどでログイン画面に戻された場合、ターミナルのベルを鳴らし、目立つ警告行を出し、ブラウザを前面に出します。別の作業をしていても気付けます。
3. 自動で再ログインを試す: 設定されている手段を順に試します。方法 1 の保存ファイル → 方法 2 の環境変数（定型フォームなら自動入力、複雑なら AI にログインだけを任せる）→ 方法 0 の対話実行なら「もう一度ログインして Enter を押してください」と案内して待ちます。復帰できればそのテストの記録に「ログアウトを検知 → 再ログイン済み」と残して続行し、どの手段も使えなければそのテストを「ブロック」にして実行を終了します。

ログイン画面の判定は URL で行います（/login /signin /auth/login などの一般的なパス、方法 0 で最初にリダイレクトされた先、方法 2 でパスワードを入力した画面）。独自のパスを使うシステムでは --login-url-pattern "^/account/enter" のように正規表現で指定してください。

実行が遅いと感じたら

所要時間のほとんどは AI の応答待ちです（ブラウザ操作は一瞬）。ランナーは Tab の連続押下のように結果を見なくても続けられる操作を 1 回の判断にまとめ、途中の操作判断には軽い思考量を使うようにしていますが、さらに調整したいときは次を試してください。

• --effort low を付ける（テスト設計と最終判定の思考量も軽くする。既定は medium）
• 速いモデルを選ぶ（実行作成時に指定。例: Anthropic は claude-sonnet-5、OpenAI は gpt-5-mini）
• 観点の「詳細」に確認したい点を具体的に書く（AI が迷わず、無駄な探索が減ります）

環境変数一覧

うまくいかないとき

安全に使うために

• 必ず テスト環境 に対して実行してください。AI には破壊的な操作を避けるよう指示していますが、保証はできません。
• 対象システムの画面情報は、選んだ AI プロバイダに送られます。機微な情報を含む環境では、プロバイダのデータ取り扱い方針を確認してください。
• ランナートークンは CI Secrets やパスワードマネージャーに保管し、リポジトリにコミットしないでください。