Qa Use

qa-use

用于浏览器测试和 E2E 测试管理的 QA 自动化 CLI。

快速开始

# Install globally
npm install -g @desplega.ai/qa-use

# Or use with npx
npx @desplega.ai/qa-use setup

开始使用

1. 设置

qa-use setup                    # Configure your API key
qa-use test init                # Initialize test directory with example

2. 创建第一个测试

创建 qa-tests/login.yaml：

name: Login Test
app_config: your-app-config-id
steps:
  - action: goto
    url: /login
  - action: fill
    target: email input
    value: [email protected]
  - action: click
    target: login button
  - action: to_be_visible
    target: dashboard

3. 运行测试

qa-use test run login           # Run single test
qa-use test run --all           # Run all tests

CLI 参考

测试命令

命令	描述
qa-use test init	使用示例初始化测试目录
qa-use test run <name>	按名称运行测试
qa-use test run --all	运行 qa-tests/ 中的所有测试
qa-use test list	列出本地测试
qa-use test list --cloud	列出云端测试
qa-use test validate <name>	验证测试语法
qa-use test sync --push	将本地测试推送到云端
qa-use test sync --pull	将云端测试拉取到本地
qa-use test export <id>	将云端测试导出到本地文件

运行 qa-use test --help 查看所有选项。

文件名后缀（≥ 2.17）。 pull 会为每个云端测试写入一个文件，文件名格式为 ${safe-name}-${short-id}.yaml，其中 ${short-id} 是测试 UUID 的前 8 个十六进制字符。测试名称在组织内可能会按设计发生冲突，因此该后缀可确保云端每一行记录都对应一个本地文件。如果你从较早版本升级，下次 pull 会将带后缀的新文件写入已有的旧版无后缀文件旁边——qa-use 会为每个孤立文件打印一行 Legacy file: … 提示，且绝不会自动删除。检查旧文件的 id: 字段；确认其不再承载重要数据后，手动将其删除。

浏览器命令

用于测试开发和调试的交互式浏览器控制：

qa-use browser create                  # Start browser session
qa-use browser goto https://example.com
qa-use browser snapshot                # Get element refs like [ref=e3]
qa-use browser click e3                # Click by element ref
qa-use browser fill e5 "hello"         # Fill input field
qa-use browser run                     # Interactive REPL mode

命令	描述
qa-use browser create	启动浏览器会话
qa-use browser goto <url>	导航到 URL
qa-use browser snapshot	获取页面元素引用
qa-use browser click <ref>	按引用点击元素
qa-use browser fill <ref> <value>	填写输入字段
qa-use browser screenshot <path>	保存屏幕截图
qa-use browser run	交互式 REPL 模式
qa-use browser close	关闭浏览器会话
qa-use browser status --list	列出所有进程中的活动会话

运行 qa-use browser --help 查看完整的 29 个浏览器命令列表。

隧道和维护命令

当目标为 localhost 且 API 位于远程时，browser create 会自动建立隧道。对于独立隧道（或跨进程注册表检查），请使用 qa-use tunnel：

qa-use tunnel start http://localhost:3000 --hold   # Hold a public tunnel
qa-use tunnel ls                                   # List active tunnels
qa-use tunnel status <target|hash>                 # Detail for one entry
qa-use tunnel close <target|hash>                  # Force-release a tunnel
qa-use doctor                                      # Reap stale sessions/tunnels
qa-use doctor --dry-run                            # Preview what would be reaped

命令	描述
qa-use tunnel ls	列出注册表中的活动隧道
qa-use tunnel status <target>	显示单个隧道的详情
qa-use tunnel close <target>	强制释放隧道（终止脱离终端运行的持有进程）
qa-use doctor	清理过期会话／隧道（已退出的 PID）

注意： qa-use tunnel * 是 CLI 端的跨进程隧道注册表，不同于 qa-use mcp tunnel，后者是 MCP 模式下的持久隧道封装器（见下文）。

API 命令

通过实时 OpenAPI（/api/v1/openapi.json）提供动态 API 访问，并在无法获取时回退到本地缓存。

qa-use api ls                             # List endpoints from live/cached OpenAPI
qa-use api /api/v1/tests                  # Call endpoint (method inferred)
qa-use api -X POST /api/v1/tests-actions/run --input body.json
qa-use api ls --refresh                   # Force refresh OpenAPI cache
qa-use api ls --offline                   # Use cached OpenAPI only

命令	描述
qa-use api ls	列出 OpenAPI 中的 /api/v1/* 端点
qa-use api <path>	向端点发送 API 请求
qa-use api ... --refresh	强制刷新 OpenAPI 规范
qa-use api ... --offline	不联网，使用缓存的规范

如果无法获取实时规范，qa-use 会回退到上次缓存的规范，并打印缓存过期警告。

检查和检查计划

远程 API 检查和计划是 CLI 的一等资源。它们直接调用 desplega.ai API；计划运行完全在远程执行，不会创建浏览器会话。

qa-use check list --app-config <app-config-id> --q login
qa-use check info <check-id>

qa-use check create \
  --name "Auth token" \
  --app-config <app-config-id> \
  --config auth-check.json \
  --alias auth \
  --capture token=$.access_token

qa-use check-schedule create \
  --name "Claims chain" \
  --app-config <app-config-id> \
  --cron "*/15 * * * *" \
  --check <auth-check-id> \
  --check <claim-check-id>

qa-use check-schedule run <schedule-id> --var env=staging --var claim_id=123
qa-use check-schedule delete <schedule-id> --force
qa-use check delete <check-id> --force

目前还没有独立的 qa-use check run <check-id> 命令，因为公共 API 目前提供的是计划运行，而非单个检查运行操作。完整工作流请使用 qa-use docs checks，当前检查负载约定请使用 qa-use api info /api/v1/checks -X POST。

设置命令

命令	描述
qa-use setup	交互式配置（API 密钥、基础 URL 等）
qa-use info	显示当前配置
qa-use install-deps	安装 Playwright 浏览器

测试定义格式

测试是包含描述用户交互步骤的 YAML 文件：

name: Checkout Flow
app_config: your-app-id
variables:
  email: [email protected]
depends_on: login-test          # Optional dependency
steps:
  - action: goto
    url: /cart
  - action: click
    target: checkout button
  - action: fill
    target: email input
    value: $email
  - action: to_be_visible
    target: order confirmation

支持的操作：

类别	操作
导航	goto、go_back、go_forward、reload
输入	fill、type、click、hover、press、check、uncheck、select_option
等待	wait_for_selector、wait_for_timeout、wait_for_load_state
断言	to_be_visible、to_have_text、to_have_url、to_contain_text、to_be_checked
高级	ai_action、ai_assertion、extract_structured_data

完整的测试定义指南请参阅 SETUP.md。

配置

环境变量

QA_USE_API_KEY=xxx              # Required: Your desplega.ai API key
QA_USE_REGION=us                # Optional: "us" or "auto" (default)

配置文件

也可以在项目根目录创建 .qa-use.json，或在主目录创建 ~/.qa-use.json：

{
  "$schema": "https://qa-use.dev/cli-schema.json",
  "api_key": "your-api-key-here",
  "region": "us"
}

优先级（优先使用排在前面的项）：

1. 环境变量
2. 当前目录中的 .qa-use.json
3. 主目录中的 ~/.qa-use.json

变量	描述	默认值
QA_USE_API_KEY	用于身份验证的 API 密钥	（必需）
QA_USE_API_URL	API 端点	https://api.desplega.ai
QA_USE_APP_URL	应用 URL	https://app.desplega.ai
QA_USE_REGION	区域（us 或 auto）	auto
QA_USE_DEFAULT_APP_CONFIG_ID	默认应用配置	（取自 API 密钥）
QA_USE_FORCE_HEADLESS	值为真（1/true/yes/on）时，会强制每次启动浏览器都设置 headless=true，并对任何明确请求有头模式（--no-headless、--headful、defaults.headless: false）报错。	（未设置）

CI/CD 集成

基础 GitHub Actions

# .github/workflows/e2e.yml
name: E2E Tests

on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run E2E Tests
        env:
          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}
        run: |
          npm install -g @desplega.ai/qa-use
          qa-use test run --all --download

      - name: Upload Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: e2e-results
          path: /tmp/qa-use/downloads/

使用 Claude Code 验证 PR

将 qa-use 插件与 Claude Code 搭配使用，自动验证 PR：

# Add from the marketplace
claude plugin marketplace add desplega-ai/qa-use

# Then install the plugin
claude plugin install [email protected]

# Verify a feature works
/qa-use:verify "the login form accepts valid credentials"

# Verify PR changes
/qa-use:verify-pr

包括 AI 辅助测试生成在内的高级 CI 工作流，请参阅 SETUP.md。

Claude Code 插件

qa-use 包含一个 Claude Code 插件，用于 AI 辅助测试工作流：

# Add from the marketplace
claude plugin marketplace add desplega-ai/qa-use

# Then install the plugin
claude plugin install [email protected]

# Install the skill
npx skills add https://github.com/desplega-ai/qa-use --skill qa-use

可用技能：

技能	描述
/qa-use:verify <description>	通过浏览器自动化验证功能是否正常运行
/qa-use:verify-pr	使用自动化浏览器测试验证 PR 变更
/qa-use:explore	交互式浏览网页
/qa-use:record	将浏览器操作录制为测试定义
/qa-use:test-run	运行 E2E 测试
/qa-use:test-validate	验证测试语法

MCP 服务

为集成 AI 助手（Claude Desktop、VS Code Copilot、Cursor 等），qa-use 提供了具备完整浏览器自动化能力的 MCP 服务。

qa-use mcp                      # Start stdio server (default)
qa-use mcp --http               # Start HTTP/SSE server
qa-use mcp tunnel               # Start persistent tunnel mode

完整的 MCP 服务文档请参阅 MCP.md，其中包括：

• 主流 AI 助手的客户端配置
• 用于 Web 集成的 HTTP 传输模式
• 用于后端发起测试的隧道模式
• 完整的 MCP 工具参考

开发

git clone https://github.com/desplega-ai/qa-use.git
cd qa-use
bun install
bun run build
bun run dev

注意： 本项目使用 bun 作为包管理器。

开发指南请参阅 CONTRIBUTING.md。

文档

• SETUP.md - 完整的 E2E 测试设置指南
• MCP.md - MCP 服务文档
• CONTRIBUTING.md - 开发指南
• CLAUDE.md - AI 助手入门指南

许可证

MIT