scoutqa-test

ScoutQA 测试技能

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

将 ScoutQA 视为一个智能测试伙伴，能够自主探索、发现问题并验证功能。将测试委托给多个并行的 ScoutQA 执行，以最大化覆盖率并节省时间。

何时使用此技能

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

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

主动使用示例：

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

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

运行测试

测试工作流

复制此清单并跟踪进度：

测试进度：

• [ ] 编写具体的测试提示，明确期望
• [ ] 在后台运行 scoutqa 命令
• [ ] 告知用户执行 ID 和浏览器 URL
• [ ] 提取并分析结果

步骤 1：编写具体的测试提示

请参阅下方“编写有效提示”部分获取指南。

步骤 2：运行 scoutqa 命令

重要：使用 Bash 工具的 timeout 参数（5000ms = 5 秒）来捕获执行详情：

调用 Bash 工具时，设置 timeout: 5000 作为参数：

• 这是 Claude Code 中 Bash 工具的内置超时参数（不是 Unix 的 timeout 命令）
• 5 秒后，Bash 工具返回控制权并附带任务 ID，进程继续在后台运行
• 这与 Unix 的 timeout 不同，后者会终止进程——此处进程会继续运行
• 前 5 秒从 ScoutQA 的输出中捕获执行 ID 和浏览器 URL
• 测试会在 ScoutQA 的基础设施上继续远程运行，作为后台任务

scoutqa --url "https://example.com" --prompt "您的测试指令"

在前几秒内，命令将输出：

• 执行 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——无需手动设置。

# 在开发应用时无缝测试本地运行的应用
scoutqa --url "http://localhost:3000" --prompt "测试注册表单"

何时使用每个命令

开始新测试？ → 使用 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 "
探索用户注册流程。测试表单验证边界情况，
验证错误处理，并检查可访问性合规性。
"

示例：电商结账

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

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

通过在单条消息中多次调用 Bash 工具来并行启动多个测试，每次调用都设置 Bash 工具的 timeout 参数为 5000（毫秒）：

# 测试 1：认证与安全
scoutqa --url "https://app.example.com" --prompt "
探索认证：登录/登出、会话处理、密码重置、
和安全边界情况。
"

# 测试 2：核心功能（并行运行）
scoutqa --url "https://app.example.com" --prompt "
测试仪表盘和主要用户工作流。验证数据加载、
CRUD 操作和搜索功能。
"

# 测试 3：可访问性（并行运行）
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 工具超时 ≠ Unix timeout 命令（Bash 超时让进程在后台继续运行，Unix timeout 会终止进程）

常见测试场景

部署后冒烟测试：

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

可访问性审计：

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

电商测试：

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

SaaS 应用：

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

表单验证：

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

移动端响应式：

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

验证已知问题：

# 首先，从之前的执行中查找问题 ID
scoutqa list-issues --execution-id <executionId>

# 然后验证问题（自动创建新的验证执行）
scoutqa issue-verify --issue-id <issueId>

issue-verify 命令将：

1. 为问题创建验证执行
2. 显示执行 ID 和浏览器 URL
3. 实时流式传输代理的验证进度
4. 显示包含结果链接的完成摘要

功能验证（实现后）：

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

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

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

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

这会在实现还处于上下文时立即捕获问题。

列出问题

使用 scoutqa list-issues 浏览先前执行中发现的问题。这对于查找用于 issue-verify 的问题 ID 很有用。

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

选项：

• --execution-id（必需）：执行 ID（来自 /t/<executionId> URL 或 CLI 输出）

示例输出：

显示 3 个问题：

🔴 019c-abc1
   移动端登录按钮无响应
   严重性：严重 | 类别：可用性 | 状态：开放

🟠 019c-abc2
   邮箱字段缺少表单验证
   严重性：高 | 类别：功能 | 状态：开放

🟡 019c-abc3
   页脚链接颜色对比度不足
   严重性：中 | 类别：可访问性 | 状态：已解决

呈现结果

即时呈现（启动测试后）

运行 scoutqa 命令后，立即向用户呈现执行详情：

**ScoutQA 测试已启动**

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

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

最终结果（完成后）

执行完成后，使用此格式呈现发现：

**ScoutQA 测试结果**

执行 ID：`ex_abc123`

**发现的问题：**

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

- 影响：屏幕阅读器无法描述 Logo
- 位置：页眉导航

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

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

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

- 影响：搜索功能看似损坏
- 位置：主搜索栏

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

始终包含：

• 执行 ID（例如 ex_abc123）以供参考
• 发现的问题，包括严重性、类别（可访问性、可用性、功能）、影响和位置

跟进卡住的执行

如果远程代理卡住或需要澄清，使用 send-message 继续：

# 示例：代理在登录处卡住，用户提供凭据
scoutqa send-message --execution-id ex_abc123 --prompt "
使用这些测试凭据：用户名：testuser@example.com，密码：TestPass123
"

# 示例：代理询问接下来测试哪个流程
scoutqa send-message --execution-id ex_abc123 --prompt "
接下来专注于结账流程，跳过心愿单功能
"

检查测试结果

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>