scoutqa-test

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ScoutQA Testing Skill

ScoutQA 测试Skill

Perform AI-powered exploratory testing on web applications using the

scoutqa

CLI.

Think of ScoutQA as an intelligent testing partner that can autonomously explore, discover issues, and verify features. Delegate testing to multiple parallel ScoutQA executions to maximize coverage while saving time.

使用

scoutqa

CLI对Web应用执行AI驱动的探索性测试。

可以将ScoutQA视为智能测试伙伴，它能自主探索、发现问题并验证功能。将测试任务委托给多个并行运行的ScoutQA实例，在节省时间的同时最大化测试覆盖率。

When to Use This Skill

何时使用本Skill

Use this skill in two scenarios:

User requests testing - When the user explicitly asks to test a website or verify functionality
Proactive verification - After implementing web features, automatically run tests to verify the implementation works correctly

Example proactive usage:

After implementing a login form → Test the authentication flow
After adding form validation → Verify validation rules and error handling
After building a checkout flow → Test the end-to-end purchase process
After fixing a bug → Verify the fix works and didn't break other features

Best practice: When you finish implementing a web feature, proactively start a ScoutQA test in the background to verify it works while you continue with other tasks.

本Skill适用于两种场景：

用户请求测试 - 当用户明确要求测试网站或验证功能时
主动验证 - 在实现Web功能后，自动运行测试以验证实现是否正常

主动使用示例：

实现登录表单后 → 测试认证流程
添加表单验证后 → 验证验证规则和错误处理
构建结账流程后 → 测试端到端购买流程
修复漏洞后 → 验证修复是否有效且未破坏其他功能

最佳实践：完成Web功能实现后，在后台主动启动ScoutQA测试以验证功能，同时你可以继续处理其他任务。

Running Tests

运行测试

Testing Workflow

测试工作流

Copy this checklist and track your progress:

Testing Progress:

Write specific test prompt with clear expectations
Run scoutqa command in background
Inform user of execution ID and browser URL
Extract and analyze results

Step 1: Write specific test prompt

See "Writing Effective Prompts" section below for guidelines.

Step 2: Run scoutqa command

IMPORTANT: Use the Bash tool's timeout parameter (5000ms = 5 seconds) to capture execution details:

When calling the Bash tool, set

timeout: 5000

as a parameter:

This is the Bash tool's built-in timeout parameter in Claude Code (NOT the Unix
```
timeout
```
command)
After 5 seconds, the Bash tool returns control with a task ID and the process continues running in the background
This is different from Unix
```
timeout
```
which kills the process - here the process keeps running
The first 5 seconds capture the execution ID and browser URL from ScoutQA's output
The test continues running remotely on ScoutQA's infrastructure with the background task

bash

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

In the first few seconds, the command will output:

Execution ID (e.g.,
```
019b831d-xxx
```
)
Browser URL (e.g.,
```
https://scoutqa.ai/t/019b831d-xxx
```
)
Initial tool calls showing test progress

After the 5-second timeout, the Bash tool returns a task ID and the command continues running in the background. You can work on other tasks while the test runs. The timeout is only to capture the initial output (execution ID and browser URL) - the test keeps running both locally as a background task and remotely on ScoutQA's infrastructure.

Step 3: Inform user of execution ID and browser URL

After the Bash tool returns with the task ID (having captured the execution details in the first 5 seconds), inform the user of:

The ScoutQA execution ID and browser URL so they can monitor progress in their browser
The background task ID if they want to check local command output later

The test continues running in the background while you continue other work.

Step 4: Extract and analyze results

See "Presenting Results" section below for the complete format.

复制此检查清单并跟踪进度：

测试进度：

编写包含明确预期的具体测试提示
在后台运行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的基础设施上作为后台任务远程运行

bash

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

在最初几秒内，命令会输出：

执行ID（例如：
```
019b831d-xxx
```
）
浏览器URL（例如：
```
https://scoutqa.ai/t/019b831d-xxx
```
）
显示测试进度的初始工具调用信息

5秒超时后，Bash工具会返回任务ID，命令将在后台继续运行。你可以在测试运行的同时处理其他任务。超时仅用于捕获初始输出（执行ID和浏览器URL）——测试会在本地作为后台任务以及ScoutQA的基础设施上持续运行。

步骤3：告知用户执行ID和浏览器URL

Bash工具返回任务ID（已在前5秒捕获执行详情）后，告知用户：

ScoutQA执行ID和浏览器URL，以便他们在浏览器中监控进度
后台任务ID（如果他们之后想查看本地命令输出）

测试将在后台继续运行，同时你可以开展其他工作。

步骤4：提取并分析结果

请参阅下方“呈现结果”部分的完整格式。

Command Options

命令选项

```
--url
```
(required): Website URL to test
```
--prompt
```
(required): Natural language testing instructions
```
--project-id
```
(optional): Associate with a project for tracking

```
--url
```
（必填）：要测试的网站URL
```
--prompt
```
（必填）：自然语言测试指令
```
--project-id
```
（可选）：关联到项目以进行跟踪

When to Use Each Command

各命令的使用场景

Starting a new test? → Use

scoutqa --url --prompt

Agent needs more context? → Use

scoutqa send-message

(see "Following Up on Stuck Executions")

启动新测试？ → 使用

scoutqa --url --prompt

Agent需要更多上下文？ → 使用

scoutqa send-message

（请参阅“跟进停滞的执行”）

Writing Effective Prompts

编写有效提示

Focus on what to explore and verify, not prescriptive steps. ScoutQA autonomously determines how to test.

Example: User registration flow

bash

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

Example: E-commerce checkout

bash

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

Example: Running parallel tests for comprehensive coverage

Launch multiple tests in parallel by making multiple Bash tool calls in a single message, each with the Bash tool's

timeout

parameter set to

(milliseconds):

bash

undefined

重点关注要探索和验证的内容，而非指令性步骤。ScoutQA会自主决定测试方式。

示例：用户注册流程

bash

scoutqa --url "https://example.com" --prompt "
探索用户注册流程。测试表单验证边缘情况，
验证错误处理，并检查可访问性合规性。
"

示例：电商结账流程

bash

scoutqa --url "https://shop.example.com" --prompt "
测试结账流程。验证价格计算、购物车持久化、
支付选项和移动端响应性。
"

示例：运行并行测试以实现全面覆盖

通过在一条消息中进行多次Bash工具调用（每次调用都将Bash工具的

timeout

参数设置为

毫秒），启动多个并行测试：

bash

undefined

Test 1: Authentication & security

测试1：认证与安全

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

scoutqa --url "https://app.example.com" --prompt " 探索认证功能：登录/登出、会话处理、密码重置，以及安全边缘情况。 "

Test 2: Core features (runs in parallel)

测试2：核心功能（并行运行）

scoutqa --url "https://app.example.com" --prompt " Test dashboard and main user workflows. Verify data loading, CRUD operations, and search functionality. "

scoutqa --url "https://app.example.com" --prompt " 测试仪表板和主要用户工作流。验证数据加载、 CRUD操作和搜索功能。 "

Test 3: Accessibility (runs in parallel)

测试3：可访问性（并行运行）

scoutqa --url "https://app.example.com" --prompt " Conduct accessibility audit: WCAG compliance, keyboard navigation, screen reader support, color contrast. "


**Implementation**: Send a single message with three Bash tool calls. For each Bash tool invocation, set the `timeout` parameter to `5000` milliseconds. After 5 seconds, each Bash call returns with a task ID while the processes continue running in the background. This captures the execution ID and browser URL from each test in the initial output, then all three continue running in parallel (both as background tasks locally and remotely on ScoutQA's infrastructure).

**Key guidelines:**

- Describe **what to test**, not **how to test** (ScoutQA figures out the steps)
- Focus on goals, edge cases, and concerns
- Run multiple parallel executions for different test areas
- Trust ScoutQA to autonomously explore and discover issues
- Always set the Bash tool's `timeout` parameter to `5000` milliseconds when calling scoutqa commands (this returns control after 5 seconds while the process continues in the background)
- For parallel tests, make multiple Bash tool calls in a single message
- Remember: Bash tool timeout ≠ Unix timeout command (Bash timeout continues the process in background, Unix timeout kills it)

scoutqa --url "https://app.example.com" --prompt " 开展可访问性审计：WCAG合规性、键盘导航、屏幕阅读器支持、颜色对比度。 "


**实现方式**：发送包含三次Bash工具调用的单条消息。对于每次Bash工具调用，将`timeout`参数设置为`5000`毫秒。5秒后，每次Bash调用都会返回任务ID，同时进程在后台继续运行。这会在初始输出中捕获每个测试的执行ID和浏览器URL，然后三个测试会并行运行（同时作为本地后台任务和ScoutQA基础设施上的远程任务）。

**关键指南：**

- 描述**要测试的内容**，而非**如何测试**（ScoutQA会自行确定步骤）
- 关注目标、边缘情况和关注点
- 针对不同测试领域运行多个并行执行实例
- 信任ScoutQA自主探索和发现问题
- 调用scoutqa命令时，始终将Bash工具的`timeout`参数设置为`5000`毫秒（这会在5秒后返回控制权，同时进程在后台继续运行）
- 对于并行测试，在单条消息中进行多次Bash工具调用
- 注意：Bash工具的timeout ≠ Unix timeout命令（Bash timeout会让进程在后台继续，Unix timeout会终止进程）

Common Test Scenarios

常见测试场景

Post-deployment smoke test:

bash

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

Accessibility audit:

bash

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

E-commerce testing:

bash

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

SaaS application:

bash

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

Form validation:

bash

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

Mobile responsiveness:

bash

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

Feature verification (after implementation):

bash

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

Example: Proactive testing after coding a feature

After implementing a user registration form, automatically verify it works:

bash

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.)
"

This catches issues immediately while the implementation is fresh in context.

部署后冒烟测试：

bash

scoutqa --url "$URL" --prompt "
冒烟测试：验证部署后关键功能是否正常。
检查主页、导航、登录/登出和主要用户流。
"

可访问性审计：

bash

scoutqa --url "$URL" --prompt "
可访问性审计：WCAG 2.1 AA合规性、键盘导航、
屏幕阅读器支持、颜色对比度和语义化HTML。
"

电商测试：

bash

scoutqa --url "$URL" --prompt "
探索电商功能：产品搜索/筛选、
购物车操作、结账流程和价格计算。
"

SaaS应用测试：

bash

scoutqa --url "$URL" --prompt "
测试SaaS应用：认证、仪表板、CRUD操作、
权限和数据完整性。
"

表单验证测试：

bash

scoutqa --url "$URL" --prompt "
测试表单验证：边缘情况、错误处理、必填字段、
格式验证和提交成功场景。
"

移动端响应性测试：

bash

scoutqa --url "$URL" --prompt "
检查移动端体验：响应式布局、导航、
触摸交互和视口行为。
"

功能验证（实现后）：

bash

scoutqa --url "$URL" --prompt "
验证新[功能名称]是否正常工作。测试核心功能、
边缘情况、错误处理以及与现有功能的集成。
"

示例：编码功能后的主动测试

实现用户注册表单后，自动验证其功能：

bash

scoutqa --url "http://localhost:3000/register" --prompt "
测试新实现的注册表单。验证：
- 表单验证（邮箱格式、密码强度、必填字段）
- 错误消息正确显示
- 注册流程成功
- 边缘情况（重复邮箱、特殊字符等）
"

这会在实现内容仍在你脑海中时立即发现问题。

Presenting Results

呈现结果

Immediate Presentation (After Starting Test)

即时呈现（启动测试后）

Right after running the scoutqa command, present the execution details to the user:

markdown

**ScoutQA Test Started**

Execution ID: `019b831d-xxx`
View Live: https://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命令后，立即向用户呈现执行详情：

markdown

**ScoutQA测试已启动**

执行ID：`019b831d-xxx`
实时查看：https://scoutqa.ai/t/019b831d-xxx

测试正在远程运行。你可以通过上方链接在浏览器中查看实时进度，我会继续处理其他任务。

Final Results (After Completion)

最终结果（完成后）

When the execution completes, use this format to present findings:

markdown

**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.

Always include:

Execution ID (e.g.,
```
ex_abc123
```
) for reference
Issues found with severity, category (accessibility, usability, functional), impact, and location

执行完成后，使用以下格式呈现发现的问题：

markdown

**ScoutQA测试结果**

执行ID：`ex_abc123`

**发现的问题：**

[高] 可访问性：Logo图片缺少alt文本

- 影响：屏幕阅读器无法描述Logo
- 位置：头部导航栏

[中] 可用性：提交按钮在移动端视口中不可见

- 影响：用户无法在移动端完成表单
- 位置：联系表单，页面底部

[低] 功能性：有效查询的搜索无结果返回

- 影响：搜索功能看似失效
- 位置：主搜索栏

**总结：** 在可访问性、可用性和功能性类别中发现3个问题。请访问上方URL查看包含截图的完整交互式报告。

请始终包含：

执行ID（例如：
```
ex_abc123
```
）用于参考
发现的问题，包含严重程度、类别（可访问性、可用性、功能性）、影响和位置

Following Up on Stuck Executions

跟进停滞的执行

If the remote agent gets stuck or needs clarification, use

send-message

to continue:

bash

undefined

如果远程Agent停滞或需要澄清，使用

send-message

继续：

bash

undefined

Example: Agent is stuck at login, user provides credentials

示例：Agent在登录环节停滞，用户提供凭证

scoutqa send-message --execution-id ex_abc123 --prompt " Use these test credentials: username: testuser@example.com, password: TestPass123 "

scoutqa send-message --execution-id ex_abc123 --prompt " 使用以下测试凭证：用户名：testuser@example.com，密码：TestPass123 "

Example: Agent asks which flow to test next

示例：Agent询问接下来测试哪个流程

scoutqa send-message --execution-id ex_abc123 --prompt " Focus on the checkout flow next, skip the wishlist feature "

undefined

scoutqa send-message --execution-id ex_abc123 --prompt " 接下来重点测试结账流程，跳过心愿单功能 "

undefined

Checking Test Results

查看测试结果

ScoutQA tests run remotely on ScoutQA's infrastructure. After starting a test with a short timeout to capture the execution ID:

The test continues running remotely (not locally in background)
You can continue other work immediately
To check results later, visit the browser URL provided when the test started
Alternatively, use
```
scoutqa get-execution --execution-id <id>
```
to fetch results via CLI

Best practice: Start tests by setting the Bash tool's

timeout

parameter to

milliseconds. After 5 seconds, the Bash tool returns control with a task ID and the execution details (execution ID and browser URL) while the test continues running in the background. You can then continue other work and check results on ScoutQA's website or via CLI when needed.

ScoutQA测试在ScoutQA的基础设施上远程运行。通过设置短超时来捕获执行ID启动测试后：

测试将继续远程运行（不在本地后台）
你可以立即继续其他工作
之后要查看结果，请访问测试启动时提供的浏览器URL

或者，使用

scoutqa get-execution --execution-id <id>

通过CLI获取结果

最佳实践：将Bash工具的

timeout

参数设置为

毫秒来启动测试。5秒后，Bash工具会返回控制权并提供任务ID和执行详情（执行ID和浏览器URL），同时测试在后台继续运行。你可以继续其他工作，需要时通过ScoutQA网站或CLI查看结果。

Troubleshooting

故障排除

Issue	Solution
`command not found: scoutqa`	Install CLI: `npm i -g @scoutqa/cli@latest`
Auth expired / unauthorized	Run `scoutqa auth login`
Test hangs or needs input	Use `scoutqa send-message --execution-id`
Check test results	Visit browser URL or `scoutqa get-execution --execution-id`

问题	解决方案
`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`