scoutqa-test

ScoutQA 测试技能

使用 scoutqa 命令行对 Web 应用执行 AI 驱动的探索性测试。

把 ScoutQA 看作一个智能测试伙伴，它可以自主探索、发现问题并验证功能。将测试工作委派给多个并行运行的 ScoutQA 执行实例，以最大化覆盖范围，同时节省时间。

何时使用此技能

在两种场景下使用此技能：

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

主动使用的示例：

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

最佳实践：当你完成某个 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（必填）：要测试的网站 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> Agent 需要更多上下文？ → 使用 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.
"

示例：电商结账

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

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

通过在单条消息中发起多个 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.
"

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

关键准则：

• 描述要测试什么，而不是如何测试（ScoutQA 会自行推断步骤）
• 聚焦目标、边界情况和关注点
• 针对不同测试领域运行多个并行执行
• 信任 ScoutQA 自主探索并发现问题
• 调用 scoutqa 命令时始终将 Bash 工具的 timeout 参数设为 5000 毫秒（这会在 5 秒后返回控制权，同时进程继续在后台运行）
• 对于并行测试，在单条消息中发起多个 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.
"

电商测试：

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. 实时流式展示 Agent 的验证进度
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）以便参考
• 发现的问题，包括严重程度、类别（无障碍、可用性、功能性）、影响和位置

跟进卡住的执行

如果远程 Agent 卡住或需要澄清，使用 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> 通过命令行获取结果

最佳实践：将 Bash 工具的 timeout 参数设置为 5000 毫秒来启动测试。5 秒后，Bash 工具会返回控制权，并提供任务 ID 和执行详情（执行 ID 和浏览器 URL），同时测试会在后台继续运行。之后你可以继续其他工作，并在需要时前往 ScoutQA 网站或通过命令行查看结果。

故障排除

问题	解决方案
command not found: scoutqa	安装命令行工具：npm i -g @scoutqa/cli@latest
认证过期 / 未授权	运行 scoutqa auth login
测试挂起或需要输入	使用 scoutqa send-message --execution-id
查看测试结果	访问浏览器 URL 或 scoutqa get-execution --execution-id
需要 issue ID 用于验证	运行 scoutqa list-issues --execution-id <id>