explorbot-fundamentals

Explorbot の基本

Explorbot は自律型 AI ウェブテスト用 CLI です。調査 → 計画 → テストのサイクルを通じて独自にブラウザーを操作し、エージェントは git や npm と同じように Explorbot を操作します。

コマンドやフラグに関する質問には、記憶ではなくインストール済みの CLI から回答してください。

npx explorbot --help                  # commands, and the EXPLORBOT_* variables
npx explorbot <command> --help        # flags for one command

何もインストールせずに実行する

Explorbot をプロジェクトにインストールする必要はありません。npx とプロバイダーだけで実行でき、作業ディレクトリには何も書き込まれません。ユーザーが Explorbot を試したい場合や、このリポジトリに存在しないアプリを対象に実行する場合に使用してください。

npx explorbot init --global --provider <name>          # once per machine, key in ~/.explorbot/.env
npx explorbot explore https://app.example.com/login --max-tests 3

CI 用のコマンドごとの EXPLORBOT_* 形式を含む詳細については、references/no-install.md を参照してください。

代わりにプロジェクトへインストールし、設定、ナレッジ、生成したテストをリポジトリに保存する方法については、[[explorbot-setup]] を参照してください。

実行に必要なもの

Explorbot は以下を同梱していません。新しいマシンで最初のコマンドを実行する前に確認してください。

• ブラウザー。 npx playwright install --with-deps chromium を実行してください。ブラウザーがない場合、ページを開くすべてのコマンドが失敗します。
• 環境に設定されたプロバイダーキーと、設定または EXPLORBOT_AI_PROVIDER で選択されたプロバイダー。
• 既知の出力フォルダー。 レポートを収集する必要がある場合に設定してください。EXPLORBOT_OUTPUT を設定します。プロジェクト設定がない場合、デフォルトは作業ディレクトリではなく ~/.explorbot/sites/<host>/ です。

1 回の実行に使うナレッジ

ログイン情報や一時的な情報は、実行ごとのナレッジに指定します。リポジトリには保存されません。次の 2 つの方法から 1 つを選んでください。

• --knowledge '<markdown>' — 繰り返し指定できます。プレーンテキストはすべてのページに適用されます。適用範囲を限定するには、テキストの先頭に有効なフロントマターのブロックを置きます。

  ---
  url: /users/sign_in
  ---
  Sign in as ${env.LOGIN_EMAIL} / ${env.LOGIN_PASSWORD}
  

• EXPLORBOT_KNOWLEDGE — プレーンテキストのみ指定でき、常にすべてのページに適用されます。この中のフロントマターは読み込まれません。環境変数から適用範囲を限定したナレッジを指定するには、EXPLORBOT_KNOWLEDGE_FILE を使用してください。

ルール：

• --- の囲みがない url: 行は、適用範囲ではなく本文として扱われます。
• 適用範囲のキーは、ページには url:、API ボートには endpoint: です。
• ${env.NAME} は Explorbot が解決するため、シークレットをテキストに含めずに済みます。
• 同じテキストを変数に設定し、フラグにも渡さないでください。2 回適用されます。

形式と URL パターンについては、docs/workflow/knowledge.md を参照してください。

ドキュメント

ローカルにインストールした場合は node_modules/explorbot/docs/、Explorbot 自体のリポジトリ内で作業している場合はリポジトリの docs/、それ以外の場合は https://raw.githubusercontent.com/testomatio/explorbot/main/docs/<path> にあります。docs/index.json には説明付きで全ページが記載されています。ページを選ぶ際はこれを読み、その後、そのページを開いてください。

結果の保存先

プロジェクトの explorbot.config.js を使って実行した場合、Explorbot はプロジェクトディレクトリに書き込みます。それ以外の場合は ~/.explorbot/sites/<host>/ に書き込みます。そのルートディレクトリの下には、次のものが保存されます。

パス	内容
output/reports/	セッションレポート：カバレッジ、欠陥、実行上の問題
output/plans/	生成または実行された計画
output/states/	状態ごとの HTML、ARIA スナップショット、スクリーンショット
output/research/	Researcher が作成した UI マップ
output/tests/	生成された Playwright / CodeceptJS ファイル
output/explorbot.log	実行ログ — 失敗した場合はここから確認してください
knowledge/、experience/	教えた内容と、学習した内容

レポートには @testomatio/reporter を使用します。 Explorbot は内部でこれを実行し、すべてのレポーター変数を渡します。そのため、TESTOMATIO を設定すると実行結果がその Testomat.io プロジェクトに送信され、レポーターの PR トークンによって結果がオープン中のプルリクエストまたはマージリクエストに投稿されます。追加の設定は不要です。変数については、testomatio-reporter スキルまたは docs/workflow/reporting.md を参照してください。

終了コードは成功／失敗を示すものではありません。 explore と test は、セッションが完了すれば常に 0 で終了します。シナリオの失敗は結果であり、クラッシュではありません。レポートを確認してください。例外は navigate です。到達不能の場合は 1 を返すため、事前チェックとして使用できます。

サイトの指定

ターゲットは、http:// または https:// で始まる絶対 URLか、/ で始まる相対パスのいずれかです。それ以外は曖昧なため、有効なターゲットではありません。

相対パスを解決するには、プロジェクト設定の web.url または EXPLORBOT_URL のサイトが必要です。どちらも設定されていない場合は、絶対 URL を指定してください。ターゲットを取らないコマンド（test、learn、knows、experience、compact）も、同じ2つの設定を参照します。これまでに探索したサイトは npx explorbot sites で一覧表示できます。

高コストな処理の前に、低コストな処理を実行

• npx explorbot context <url> — 見出し、一致するナレッジ、インタラクティブ要素を表示します。AI 呼び出しはありません。
• npx explorbot shell <url> '<codecept command>' — コマンドを1つ実行して終了します。
• npx explorbot knows <url> — ページに一致するナレッジを表示します。
• npx explorbot navigate <url> --session — 到達可能か確認し、セッションを保存します。

ルール

• explorbot start は対話型の TUI で、エージェントは操作できません。ユーザーに実行を依頼してください。それ以外はすべてヘッドレスで実行され、終了します。
• --help にコマンドやフラグが表示されていない場合、それは存在しません。
• Explorbot には CRUD が必要です。ランディングページ、ブログ、CMS は対象外です。

関連スキル

• [[explorbot-setup]] — プロジェクトへのインストール：設定、プロバイダー、ログインナレッジ、検証済みのナビゲーション。
• [[explorbot-plan]] — テストプランを手動で作成し、explorbot test で実行します。