scoutqa-test

ScoutQA テストスキル

scoutqa CLI を使用して、Web アプリケーションに対して AI を活用した探索的テストを実行します。

ScoutQA はインテリジェントなテストパートナーであると考えてください。自律的に探索し、問題を発見し、機能を検証できます。テストを複数の ScoutQA 実行に並行して委任することで、時間を節約しながらカバレッジを最大化できます。

このスキルを使用するタイミング

このスキルは次の 2 つのシナリオで使用します。

1. ユーザーがテストを依頼したとき - ユーザーが Web サイトのテストや機能の検証を明示的に依頼した場合
2. プロアクティブな検証 - Web 機能を実装した後、実装が正しく動作することを検証するために自動的にテストを実行する場合

プロアクティブな使用例:

• ログインフォームを実装した後 → 認証フローをテストする
• フォームバリデーションを追加した後 → バリデーションルールとエラー処理を検証する
• チェックアウトフローを構築した後 → エンドツーエンドの購入プロセスをテストする
• バグを修正した後 → 修正が機能し、他の機能を壊していないことを検証する

ベストプラクティス: Web 機能の実装が完了したら、他のタスクを続けながら、動作を検証するためにバックグラウンドでプロアクティブに ScoutQA テストを開始します。

テストの実行

テストワークフロー

このチェックリストをコピーして進捗を追跡します。

テストの進捗:

• 明確な期待事項を含む具体的なテストプロンプトを作成する
• scoutqa コマンドをバックグラウンドで実行する
• 実行 ID とブラウザー URL をユーザーに通知する
• 結果を抽出して分析する

ステップ 1: 具体的なテストプロンプトを作成する

ガイドラインについては、以下の「効果的なプロンプトの作成」セクションを参照してください。

ステップ 2: scoutqa コマンドを実行する

重要: 実行の詳細を取得するには、Bash ツールの timeout パラメーター (5000ms = 5 秒) を使用します。

Bash ツールを呼び出す際は、パラメーターとして timeout: 5000 を設定します。

• これは Claude Code の Bash ツールに組み込まれた timeout パラメーターです (Unix の timeout コマンドではありません)
• 5 秒後、Bash ツールはタスク ID とともに制御を返し、プロセスはバックグラウンドで実行を続けます
• これはプロセスを強制終了する Unix の timeout とは異なります。ここではプロセスは実行を続けます
• 最初の 5 秒間で ScoutQA の出力から実行 ID とブラウザー URL を取得します
• テストは ScoutQA のインフラストラクチャ上でバックグラウンドタスクとしてリモートで実行を続けます

scoutqa --url "https://example.com" --prompt "Your test instructions"

最初の数秒間で、コマンドは以下を出力します。

• 実行 ID (例: 019b831d-xxx)
• ブラウザー URL (例: https://app.scoutqa.ai/t/019b831d-xxx)
• テストの進捗を示す最初のツール呼び出し

5 秒のタイムアウト後、Bash ツールはタスク ID を返し、コマンドはバックグラウンドで実行を続けます。テストの実行中に他のタスクを進めることができます。タイムアウトは最初の出力 (実行 ID とブラウザー URL) を取得するためだけのものです。テストはローカルではバックグラウンドタスクとして、リモートでは ScoutQA のインフラストラクチャ上で実行を続けます。

ステップ 3: 実行 ID とブラウザー URL をユーザーに通知する

Bash ツールがタスク ID を返した後 (最初の 5 秒間で実行の詳細を取得済み)、ユーザーに以下を通知します。

• ScoutQA の実行 ID とブラウザー URL。ユーザーはブラウザーで進捗を監視できます
• ローカルのコマンド出力を後で確認したい場合のバックグラウンドタスク ID

テストはバックグラウンドで実行を続け、その間も他の作業を続けることができます。

ステップ 4: 結果を抽出して分析する

完全なフォーマットについては、以下の「結果の提示」セクションを参照してください。

コマンドオプション

• --url (必須): テストする Web サイトの URL (localhost / 127.0.0.1 をサポート)
• --prompt (必須): 自然言語によるテスト手順
• --project-id (任意): 追跡用にプロジェクトに関連付ける
• -v, --verbose (任意): 内部的なものを含むすべてのツール呼び出しを表示する

ローカルテストのサポート

ScoutQA は localhost および 127.0.0.1 の URL のテストを自律的にサポートします。手動でのセットアップは不要です。

# Seamlessly test a locally running app when you're developing your app
scoutqa --url "http://localhost:3000" --prompt "Test the registration form"

各コマンドの使用場面

新しいテストを開始しますか? → scoutqa --url --prompt を使用します 既知の問題を検証しますか? → scoutqa issue-verify --issue-id <id> を使用します 実行から問題 ID を見つけますか? → scoutqa list-issues --execution-id <id> を使用します エージェントにもっとコンテキストが必要ですか? → scoutqa send-message を使用します(「スタックした実行へのフォローアップ」を参照)

効果的なプロンプトの作成

指示的な手順ではなく、何を探索し、検証するかに焦点を当ててください。ScoutQA がテスト方法を自律的に判断します。

例: ユーザー登録フロー

scoutqa --url "https://example.com" --prompt "
Explore the user registration flow. Test form validation edge cases,
verify error handling, and check accessibility compliance.
"

例: Eコマースのチェックアウト

scoutqa --url "https://shop.example.com" --prompt "
Test the checkout flow. Verify pricing calculations, cart persistence,
payment options, and mobile responsiveness.
"

例: 包括的なカバレッジのための並列テストの実行

1つのメッセージで複数の Bash ツール呼び出しを行い、それぞれの Bash ツールの timeout パラメータを 5000(ミリ秒)に設定することで、複数のテストを並列で起動します:

# Test 1: Authentication & security
scoutqa --url "https://app.example.com" --prompt "
Explore authentication: login/logout, session handling, password reset,
and security edge cases.
"

# Test 2: Core features (runs in parallel)
scoutqa --url "https://app.example.com" --prompt "
Test dashboard and main user workflows. Verify data loading,
CRUD operations, and search functionality.
"

# Test 3: Accessibility (runs in parallel)
scoutqa --url "https://app.example.com" --prompt "
Conduct accessibility audit: WCAG compliance, keyboard navigation,
screen reader support, color contrast.
"

実装: 3つの Bash ツール呼び出しを含む1つのメッセージを送信します。各 Bash ツール呼び出しで、timeout パラメータを 5000 ミリ秒に設定します。5秒後、各 Bash 呼び出しはタスク ID を返しますが、プロセスはバックグラウンドで実行され続けます。これにより、各テストの実行 ID とブラウザ URL が最初の出力で取得され、その後3つすべてが並列で(ローカルのバックグラウンドタスクとしても、ScoutQA のインフラストラクチャ上のリモートでも)実行され続けます。

重要なガイドライン:

• 何をテストするかを説明し、どのようにテストするかは説明しないでください(ScoutQA が手順を判断します)
• 目標、エッジケース、懸念事項に焦点を当ててください
• 異なるテスト領域ごとに複数の並列実行を実行してください
• ScoutQA が自律的に探索し、問題を発見することを信頼してください
• scoutqa コマンドを呼び出す際は、常に Bash ツールの timeout パラメータを 5000 ミリ秒に設定してください(これにより5秒後に制御が戻り、プロセスはバックグラウンドで継続します)
• 並列テストの場合は、1つのメッセージで複数の Bash ツール呼び出しを行ってください
• 覚えておいてください: Bash ツールのタイムアウト ≠ Unix の timeout コマンド(Bash のタイムアウトはプロセスをバックグラウンドで継続させ、Unix の timeout はそれを強制終了します)

一般的なテストシナリオ

デプロイ後のスモークテスト:

scoutqa --url "$URL" --prompt "
Smoke test: verify critical functionality works after deployment.
Check homepage, navigation, login/logout, and key user flows.
"

アクセシビリティ監査:

scoutqa --url "$URL" --prompt "
Audit accessibility: WCAG 2.1 AA compliance, keyboard navigation,
screen reader support, color contrast, and semantic HTML.
"

Eコマースのテスト:

scoutqa --url "$URL" --prompt "
Explore e-commerce functionality: product search/filtering,
cart operations, checkout flow, and pricing calculations.
"

SaaS アプリケーション:

scoutqa --url "$URL" --prompt "
Test SaaS app: authentication, dashboard, CRUD operations,
permissions, and data integrity.
"

フォームの検証:

scoutqa --url "$URL" --prompt "
Test form validation: edge cases, error handling, required fields,
format validation, and successful submission.
"

モバイルのレスポンシブ対応:

scoutqa --url "$URL" --prompt "
Check mobile experience: responsive layout, navigation,
touch interactions, and viewport behavior.
"

既知の問題の検証:

# First, find issue IDs from a previous execution
scoutqa list-issues --execution-id <executionId>

# Then verify the issue (creates a new verification execution automatically)
scoutqa issue-verify --issue-id <issueId>

issue-verify コマンドは次のことを行います:

1. 問題に対する検証実行を作成します
2. 実行 ID とブラウザ URL を表示します
3. エージェントの検証の進行状況をリアルタイムでストリーミングします
4. 結果へのリンクを含む完了サマリーを表示します

機能の検証(実装後):

scoutqa --url "$URL" --prompt "
Verify the new [feature name] works correctly. Test core functionality,
edge cases, error handling, and integration with existing features.
"

例: 機能をコーディングした後のプロアクティブなテスト

ユーザー登録フォームを実装した後、それが動作することを自動的に検証します:

scoutqa --url "http://localhost:3000/register" --prompt "
Test the newly implemented registration form. Verify:
- Form validation (email format, password strength, required fields)
- Error messages display correctly
- Successful registration flow
- Edge cases (duplicate emails, special characters, etc.)
"

これにより、実装がコンテキストに新しいうちに問題を即座に捉えることができます。

問題の一覧表示

scoutqa list-issues を使用して、以前の実行で見つかった問題を閲覧します。これは、issue-verify で使用する問題 ID を見つけるのに便利です。

scoutqa list-issues --execution-id <executionId>

オプション:

• --execution-id(必須): 実行 ID(/t/<executionId> URL または CLI 出力から取得)

出力例:

Showing 3 issues:

🔴 019c-abc1
   Login button unresponsive on mobile
   Severity: critical | Category: usability | Status: open

🟠 019c-abc2
   Missing form validation on email field
   Severity: high | Category: functional | Status: open

🟡 019c-abc3
   Color contrast insufficient on footer links
   Severity: medium | Category: accessibility | Status: resolved

結果の提示

即時の提示(テスト開始後)

scoutqa コマンドを実行した直後に、実行の詳細をユーザーに提示します:

**ScoutQA Test Started**

Execution ID: `019b831d-xxx`
View Live: https://app.scoutqa.ai/t/019b831d-xxx

The test is running remotely. You can view real-time progress in your browser at the link above while I continue with other tasks.

最終結果(完了後)

実行が完了したら、この形式を使用して調査結果を提示します:

**ScoutQA Test Results**

Execution ID: `ex_abc123`

**Issues Found:**

[High] Accessibility: Missing alt text on logo image

- Impact: Screen readers cannot describe the logo
- Location: Header navigation

[Medium] Usability: Submit button not visible on mobile viewport

- Impact: Users cannot complete form on mobile devices
- Location: Contact form, bottom of page

[Low] Functional: Search returns no results for valid queries

- Impact: Search feature appears broken
- Location: Main search bar

**Summary:** Found 3 issues across accessibility, usability, and functional categories. See full interactive report with screenshots at the URL above.

必ず含めてください:

• 参照用の実行 ID(例: ex_abc123)
• 深刻度、カテゴリ(アクセシビリティ、ユーザビリティ、機能)、影響、および場所を含む発見された問題

スタックした実行へのフォローアップ

リモートエージェントがスタックしたり、明確化が必要な場合は、send-message を使用して続行します:

# Example: Agent is stuck at login, user provides credentials
scoutqa send-message --execution-id ex_abc123 --prompt "
Use these test credentials: username: [email protected], password: TestPass123
"

# Example: Agent asks which flow to test next
scoutqa send-message --execution-id ex_abc123 --prompt "
Focus on the checkout flow next, skip the wishlist feature
"

テスト結果の確認

ScoutQA のテストは、ScoutQA のインフラストラクチャ上でリモート実行されます。実行 ID を取得するために短いタイムアウトを設定してテストを開始した後:

1. テストはリモートで実行され続けます（ローカルでバックグラウンド実行されるのではありません）
2. すぐに他の作業を続けることができます
3. 後で結果を確認するには、テスト開始時に提供されたブラウザー URL にアクセスしてください
4. あるいは、scoutqa get-execution --execution-id <id> を使用して CLI 経由で結果を取得できます

ベストプラクティス: Bash ツールの timeout パラメーターを 5000 ミリ秒に設定してテストを開始します。5 秒後、Bash ツールはタスク ID と実行の詳細（実行 ID とブラウザー URL）を返して制御を戻し、テストはバックグラウンドで実行され続けます。その後、他の作業を続け、必要に応じて ScoutQA のウェブサイトまたは CLI 経由で結果を確認できます。

トラブルシューティング

問題	解決策
command not found: scoutqa	CLI をインストール: npm i -g @scoutqa/cli@latest
認証の期限切れ / 未認証	scoutqa auth login を実行してください
テストがハングする、または入力が必要	scoutqa send-message --execution-id を使用してください
テスト結果を確認する	ブラウザー URL にアクセスするか、scoutqa get-execution --execution-id を実行してください
検証用のイシュー ID が必要	scoutqa list-issues --execution-id <id> を実行してください