qa-use

qa-use

面向 AI 驱动开发工作流的端到端测试和浏览器自动化。

关键见解：插件命令是快捷方式

适用于 AI Harness（codex、opencode 等）：

插件命令（如 /qa-use:verify 这样的斜杠命令）是用于封装 CLI 工作流的便捷快捷方式。仅有 Bash 工具的 Harness 也可以通过下方记录的 CLI 命令使用所有功能。

本文档中的统一模式：

• CLI 工作流：分步 CLI 命令（适用于所有 Harness）
• 插件快捷方式：可选的斜杠命令（便捷方式）

设置与配置

使用任何 qa-use 命令之前，请确认配置已就绪：

# Check current configuration (no-op if already configured)
qa-use setup

# Configure with API key (validates against server)
qa-use setup --api-key <key>

# View full configuration details
qa-use info

环境变量（配置文件的替代方式）：

变量	说明
QA_USE_API_KEY	用于身份验证的 API 密钥
QA_USE_REGION	区域：us（默认值）或 auto
QA_USE_API_URL	覆盖 API 基础 URL

**配置文件：**项目目录中的 .qa-use.json 或主目录中的 ~/.qa-use.json。优先级：环境变量 > 项目 .qa-use.json > ~/.qa-use.json。

**如果遇到“API key not configured”、401 或身份验证错误：**运行 qa-use setup 检查配置状态。切勿捏造或猜测 API 密钥。

核心工作流

1. 浏览器控制与会话生命周期

CLI 工作流：

# Create browser session (returns immediately — runs detached in the background)
qa-use browser create --viewport desktop

# For localhost testing — auto-tunnels when base URL is localhost and API is remote.
# No flag needed for the common case:
qa-use browser create --no-headless http://localhost:3000

# Force a tunnel even in dev mode:
qa-use browser create --tunnel on --no-headless

# Opt out of auto-tunnel (e.g. backend is also local):
qa-use browser create --no-tunnel

# Navigate
qa-use browser goto https://example.com

# Snapshot to get element refs (ALWAYS do this before interacting)
qa-use browser snapshot

# Interact by ref
qa-use browser click e3
qa-use browser fill e5 "text"

# Close
qa-use browser close

后台会话管理：

qa-use browser create 会立即返回——实际的浏览器和隧道在分离的子进程中运行，因此终端可以继续使用。使用以下命令管理会话：

qa-use browser status --list   # Show all active sessions across processes
qa-use browser status           # Details for the auto-resolved session
qa-use browser close <id>       # Close a specific session
qa-use doctor                   # Reap stale sessions/tunnels (dead PIDs)
qa-use doctor --dry-run         # Preview what would be cleaned

隧道命令：

跨进程隧道注册表——针对同一目标的多个命令共用一个隧道：

qa-use tunnel start <url>         # Acquire a tunnel (released immediately unless --hold)
qa-use tunnel start <url> --hold  # Keep the tunnel up until Ctrl+C
qa-use tunnel ls                  # List active tunnels (target, public URL, refcount)
qa-use tunnel status <target>     # Detail for a single tunnel
qa-use tunnel close <target>      # Force-release a tunnel (kills detached holders)

插件快捷方式：

/qa-use:explore https://example.com

（封装 create + goto + snapshot，并支持自主探索）

重要：在页面上进行首次交互之前，务必先运行 snapshot。切勿猜测元素引用。

快照差异功能（使用它来避免不必要的快照）： 每次操作（goto、click、fill 等）后，浏览器都会自动显示 DOM 变化：

• 摘要：“添加了 5 个元素，修改了 1 个元素”
• 新增元素：+ [e54] generic "Thanks for agreeing!"（绿色）
• 修改的元素：~ [e18] checkbox "I agree..."，并显示 +attrs: checked, active（黄色）
• 移除的元素：- [e99] button "Submit"（红色）

**可以跳过完整 snapshot 的情况：**如果上次操作的差异输出已显示接下来需要交互的元素引用，可直接使用，无需中间再运行 snapshot。例如，如果点击按钮后，差异中显示 + [e54] button "Submit"，你可以立即运行 click e54。

**仍需完整 snapshot 的情况：**如果需要查找差异中未出现的元素（例如，尚未交互过的现有元素），或差异已被截断（显示“... and N more changes”），请运行 snapshot。

2. 了解区块

什么是区块？

区块是浏览器会话中记录的原子交互。它们：

• 在任何浏览器交互（click、fill、goto、scroll 等）期间自动捕获
• 在服务端与会话一起存储
• 通过 qa-use browser get-blocks 获取
• 是生成测试的基础

区块的重要性：

• 记录一次，反复重放：交互式记录可以转化为自动化测试
• 适合 AI 使用：Agent 可以分析区块以了解用户意图
• 版本控制：与会话一起存储的区块可用于迭代测试
• 连接 CLI 与测试：从探索到自动化的自然工作流

区块的工作方式：

# 1. Create session and interact (auto-tunnels localhost)
qa-use browser create --no-headless
qa-use browser goto https://example.com
qa-use browser snapshot        # Returns: [ref=e1] button
qa-use browser click e1        # Records as block
qa-use browser fill e5 "text"  # Records as block

# 2. Retrieve blocks (JSON array)
qa-use browser get-blocks
# Returns:
# [
#   {"type": "goto", "url": "...", "timestamp": "..."},
#   {"type": "click", "ref": "e1", "timestamp": "..."},
#   {"type": "fill", "ref": "e5", "value": "text", "timestamp": "..."}
# ]

# 3. Generate test YAML from blocks
qa-use browser generate-test -n "my_test" -o qa-tests/my_test.yaml

# 4. Run generated test
qa-use test run my_test

插件快捷方式：

/qa-use:record start my_test
# ... perform interactions ...
/qa-use:record stop

（封装交互式工作流，并使用 AI 生成测试）

3. 测试管理

CLI 工作流：

# Run test by name
qa-use test run login

# Run and save the (non-synced) local test to cloud
qa-use test run login --persist

# Validate syntax
qa-use test validate login

# Show test details
qa-use test info login

# List test runs
qa-use test runs --status failed

插件快捷方式：

/qa-use:test-run login

（常用测试执行的便捷快捷方式）

4. 测试变量（命令式编辑）

快速对单个测试的类型化 variables: 块执行 set/unset — 适用于不想往返编辑完整 YAML 的情况。

CLI 工作流：

# Local YAML file — Document API preserves comments + key order
qa-use test vars list  qa-tests/login.yaml
qa-use test vars list  qa-tests/login.yaml --json
qa-use test vars set   qa-tests/login.yaml --key user --value alice
qa-use test vars set   qa-tests/login.yaml --key url --value https://x \
                                          --type url --lifetime all
qa-use test vars set   qa-tests/login.yaml --key password --value hunter2 --sensitive
qa-use test vars set   qa-tests/login.yaml --key password --sensitive  # preserves stored value
qa-use test vars unset qa-tests/login.yaml --key user

# Remote --id fallback — exports YAML, mutates, re-imports (best-effort RMW)
qa-use test vars list  --id <uuid>
qa-use test vars set   --id <uuid> --key user --value alice
qa-use test vars unset --id <uuid> --key user

规则：

• 互斥：传入 <file> 或 --id，不能同时传入。两者都不传 → 退出码为 1。
• --id 需要完整 UUID（使用 qa-use test list --query <name> 查找）。
• 表单升级：只传入 --key/--value 时会写入简单表单（key: value）。 使用 --type/--lifetime/--context/--sensitive 中任一选项时，会升级为完整表单 （{ value, type, lifetime, context, is_sensitive }）。
• 保留敏感值：对于现有的敏感变量，不带 --value 使用 --sensitive 会保留已存储的值。对于新键，这种组合会报错。
• --json 脱敏：敏感条目会完全省略 value 键；is_sensitive: true 标记表示已脱敏。
• 远程往返注意事项：注释/键顺序仅在本地文件路径下保留。导入时，服务端会规范化格式。

无插件快捷方式 - 直接使用 CLI 命令。

5. 测试同步生命周期

CLI 工作流：

# Pull tests from cloud
qa-use test sync pull

# Push all local tests to cloud
qa-use test sync push --all

# Push specific test
qa-use test sync push --id <uuid>

# Force push (overwrite conflicts)
qa-use test sync push --force

# Compare local vs cloud
qa-use test diff login.yaml

持久化与同步：

当本地测试的 YAML 同时包含 id: 和 version_hash: 时，该测试即为已同步（这两个字段会由 test sync push/pull 写回）。test run 中的 --persist 与 qa-use test sync 相关，但两者并不相同：

本地文件状态	persist	运行时的行为
未同步	false（默认）	在本地运行；不会保存到云端。使用 --persist 重新运行，或使用 test sync push 进行持久化。
未同步	true	运行后，测试会作为云端新条目上传。这样重复运行会产生重复项 — 文件关联到云端 id 后，建议改用 test sync push。
已同步	false	使用云端跟踪的定义运行；不会额外写入。
已同步	true	云端定义会被插入或更新（可能覆盖较新的云端编辑）。请使用 test sync push/pull 进行显式版本控制。

经验法则：test sync push/pull 是有意进行同步的方式。仅将 --persist （或 .qa-use.json 中的 defaults.persist: true）用于一次性上传全新的本地测试。

无插件快捷方式 - 直接使用 CLI 命令

必备命令

浏览器会话管理

命令	描述
qa-use browser create	创建远程浏览器会话
qa-use browser create <url>	创建会话并导航到 URL
qa-use browser create --tunnel [auto|on|off]	隧道模式 — 默认值为 auto（localhost + 远程 API）。--no-tunnel 是 off 的简写。
qa-use browser create --no-headless	显示浏览器窗口（与本地/隧道浏览器配合使用）
qa-use browser create --viewport <size>	设置视口：desktop、tablet、mobile
qa-use browser create --ws-url <url>	连接到现有 WebSocket 浏览器
qa-use browser create --after-test-id <uuid>	先运行测试，然后进入交互模式
qa-use browser create --var <key=value>	覆盖应用配置变量（可重复使用）
qa-use browser list	列出活动会话
qa-use browser status	显示当前会话详情（app_url、recording_url 等）
qa-use browser status --list	显示所有进程中的活动会话
qa-use browser close	关闭活动会话
qa-use browser close <id>	按 id 关闭指定会话
qa-use doctor	清理过期会话/隧道（已结束的 PID）
qa-use tunnel ls	列出注册表中的活动隧道
qa-use tunnel start <url> --hold	保持公共隧道可用，供外部使用者访问

会话会自动持久化到 ~/.qa-use.json。一个活动会话 = 无需 -s 标志。browser create 会立即返回 — 浏览器和隧道在分离的子进程中运行。如果过期状态不断累积，请使用 qa-use doctor。

导航

命令	描述
qa-use browser goto <url>	导航到 URL
qa-use browser back	返回
qa-use browser forward	前进
qa-use browser reload	重新加载页面

元素交互

命令	描述
qa-use browser click <ref>	按 ref 点击元素
qa-use browser click --text "Button"	根据语义描述点击
qa-use browser fill <ref> "value"	填写输入字段
qa-use browser type <ref> "text"	带延迟输入（用于自动补全）
qa-use browser press <key>	按下按键（例如 Enter、Tab）
qa-use browser check <ref>	勾选复选框
qa-use browser uncheck <ref>	取消勾选复选框
qa-use browser select <ref> "option"	选择下拉选项
qa-use browser hover <ref>	将鼠标悬停在元素上
qa-use browser scroll down 500	滚动指定像素
qa-use browser scroll-into-view <ref>	将元素滚动到可见区域
qa-use browser drag <ref> --target <ref>	将元素拖动到目标位置
qa-use browser mfa-totp [ref] <secret>	生成 TOTP 代码（可选填入）
qa-use browser upload <ref> <file>...	将文件上传到输入框（采用 base64 编码，适用于远程和隧道）

检查与快照差异

命令	描述
qa-use browser snapshot	获取包含元素 ref 的完整 ARIA 树（仅在差异输出不足时使用）
qa-use browser url	获取当前 URL
qa-use browser screenshot	保存 screenshot.png
qa-use browser screenshot file.png	保存到自定义路径
qa-use browser screenshot --base64	将 base64 输出到 stdout
qa-use browser evaluate <expression>	在浏览器上下文中执行 JavaScript

快照差异功能会在每次浏览器操作后自动显示 DOM 变更：

• 新增元素：以 + 前缀和绿色显示，这些 ref 可立即使用
• 已修改元素：以 ~ 前缀和黄色显示，包括属性变更（+attrs: checked）
• 已移除元素：以 - 前缀和红色显示——请勿使用这些 ref

**下载：**当某项操作触发文件下载时（例如点击下载链接），响应会包含下载信息：文件名、大小和预签名 URL。使用 qa-use browser downloads 列出所有下载，或使用 --save <dir> 将其保存到本地。

使用差异输出直接与新出现的元素交互，无需先运行完整的 snapshot。

测试操作

命令	描述
qa-use test run <name>	按名称运行测试
qa-use test run --all	运行所有测试
qa-use test run <name> --tunnel [mode]	覆盖隧道模式（auto、on、off）。--no-tunnel 等同于 off。单独使用 --tunnel 等同于 on。
qa-use test run <name> --download	将资源下载到 /tmp/qa-use/downloads/
qa-use test run <name> --var key=value	覆盖变量
qa-use test validate <name>	验证测试语法
qa-use test list	列出可用测试
qa-use test info <name>	显示测试详情（步骤、标签、描述）
qa-use test info --id <uuid>	按 ID 显示云端测试详情
qa-use test runs [name]	列出测试运行历史
qa-use test runs --id <uuid>	按测试 ID 筛选运行记录
qa-use test runs --status failed	按状态筛选运行记录
qa-use test init	初始化测试目录
qa-use test sync pull	从云端拉取测试
qa-use test sync push --all	将所有本地测试推送到云端
qa-use test sync push --id <uuid>	推送指定测试
qa-use test sync push --force	推送测试并覆盖冲突
qa-use test diff <file>	比较本地测试与云端测试
qa-use test schema [path]	查看测试定义架构

API 操作（动态 OpenAPI）

qa-use api 会从 /api/v1/openapi.json 动态发现操作，并在本地缓存元数据，以便离线时备用。

命令	说明
qa-use api	显示帮助和可用的子命令
qa-use api ls	列出 OpenAPI 中可用的 /api/v1/* 路由
qa-use api ls --refresh	强制刷新 OpenAPI 缓存
qa-use api ls --offline	仅使用缓存的 OpenAPI 元数据
qa-use api info /api/v1/<route>	显示路由详情：参数、请求正文、响应
qa-use api info /api/v1/<route> -X POST	显示指定 HTTP 方法的信息
qa-use api info /api/v1/<route> --json	以 JSON 格式显示路由信息
qa-use api examples	显示用法示例
qa-use api openapi	输出 OpenAPI 规范 URL
qa-use api openapi --raw	输出完整的 OpenAPI 规范 JSON
qa-use api /api/v1/tests	调用端点（尽可能推断方法）
qa-use api -X GET /api/v1/test-runs -f limit=5	使用查询字段执行 GET 请求
qa-use api -X POST /api/v1/tests-actions/run --input body.json	使用 JSON 正文文件执行 POST 请求
qa-use api -X GET /api/v1/test-runs/<id>	按 ID 获取详情端点

无插件快捷方式——直接使用 CLI 命令。

API 检查与检查计划

远程 API 检查通过一等命令进行管理。这些命令会直接调用 desplega.ai API；它们不会在本地运行检查，也不会创建浏览器会话。

命令	说明
qa-use check list --app-config <id>	列出远程 API 检查
qa-use check info <check-id>	查看一项检查，包括依赖项和捕获内容
qa-use check create --name <name> --app-config <id> --config check.json	创建检查
qa-use check update <check-id> --depends-on <id> --alias <name>	更新依赖链元数据
qa-use check delete <check-id> --force	删除检查
qa-use check-schedule list --app-config <id>	列出远程检查计划
qa-use check-schedule create --name <name> --app-config <id> --cron "*/15 * * * *" --check <id>	创建有序计划
qa-use check-schedule run <schedule-id> --var env=staging	以远程变量传递链的形式运行计划

常见流程：

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 update <claim-check-id> \
  --depends-on <auth-check-id> \
  --alias claim

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 run <check-id> 命令，因为 公开 API 当前记录的是计划运行，而非单项检查运行操作。 使用 qa-use api info /api/v1/checks -X POST 查看当前检查负载 约定，并参阅 references/checks.md 获取示例。

无插件快捷方式——直接使用 CLI 命令。

日志与调试

命令	说明
qa-use browser logs console	查看会话的控制台日志
qa-use browser logs console -s <id>	查看指定会话或已关闭会话的日志
qa-use browser logs network	查看网络请求日志
qa-use browser logs network -s <id>	查看指定会话的网络日志
qa-use browser downloads	列出会话下载的文件
qa-use browser downloads --save <dir>	将下载的文件保存到本地目录
qa-use browser downloads --json	以 JSON 格式输出下载信息

测试生成

命令	说明
qa-use browser generate-test	根据录制的会话生成测试 YAML
qa-use browser generate-test -s <id>	根据指定会话生成
qa-use browser generate-test -n <name>	指定测试名称
qa-use browser generate-test -o <path>	指定输出路径
qa-use browser get-blocks	获取录制的交互块（JSON）

等待

命令	说明
qa-use browser wait <ms>	固定等待
qa-use browser wait-for-selector ".class"	等待选择器
qa-use browser wait-for-load	等待页面加载

变量覆盖

使用 --var 在运行时覆盖应用配置变量。常见变量：

变量	说明
base_url	应用的基础 URL（例如，预览部署 URL）
login_url	登录页面 URL
login_username	用于身份验证的用户名/邮箱
login_password	用于身份验证的密码

使用临时预览 URL 的示例：

qa-use browser create --after-test-id <login-test-uuid> \
  --var base_url=https://preview-123.example.com \
  --var login_url=https://preview-123.example.com/auth/login

常见模式

模式 1：功能验证

CLI 工作流：

# 1. Search for existing test
qa-use test list | grep "login"

# 2. Run test
qa-use test run login

# 3. Debug failures
qa-use browser logs console

插件快捷方式：

/qa-use:verify "login works with valid credentials"

（使用 AI 驱动的测试发现和分析封装上述 CLI 工作流）

模式 2：录制并生成测试

CLI 工作流：

# 1. Create session (auto-tunnels localhost targets)
qa-use browser create --no-headless

# 2. Navigate and interact
qa-use browser goto https://example.com
qa-use browser snapshot
qa-use browser click e1
qa-use browser fill e5 "test"

# 3. Generate test from blocks
qa-use browser get-blocks
qa-use browser generate-test -n "my_test"

# 4. Run test
qa-use test run my_test

插件快捷方式：

/qa-use:record start my_test
# ... perform interactions ...
/qa-use:record stop

模式 3：经过身份验证的探索

CLI 工作流：

# Create session that runs login test first
qa-use browser create --after-test-id <login-test-uuid>

# Session now authenticated, explore
qa-use browser goto /dashboard
qa-use browser snapshot

插件快捷方式：

/qa-use:explore /dashboard

（自动处理身份验证检测和会话创建）

模式 4：编辑现有测试

CLI 工作流：

# 1. Open test file in editor
vim qa-tests/login.yaml

# 2. Validate syntax
qa-use test validate login

# 3. Run to verify
qa-use test run login

插件快捷方式：

/qa-use:record edit login

（借助 AI 编辑并进行验证）

模式 5：使用快照差异避免不必要的快照

CLI 工作流：

# Create session and navigate
qa-use browser create --no-headless
qa-use browser goto https://evals.desplega.ai/checkboxes

# goto shows diff — initial page load shows all elements:
# Changes: 45 elements added
# + [e18] checkbox "I agree to the terms and conditions"
# + [e19] generic "I agree to the terms and conditions"

# ✅ Use ref from diff directly — no snapshot needed!
qa-use browser click e18

# Diff shows what changed:
# Changes: 5 elements added, 1 element modified
# + [e54] generic "Thanks for agreeing!"
# + [e55] link "Terms and Conditions"
# ~ [e18] checkbox "I agree to the terms and conditions"
#     +attrs: active, checked

# ✅ Can click e55 directly from diff output — no snapshot needed!
qa-use browser click e55

# ❌ Need to find an element NOT in the diff? Now run snapshot:
qa-use browser snapshot

关键原则： 操作后，将差异输出作为元素引用的主要来源。只有在需要查找差异中未包含的元素时，才回退到 snapshot。

优势：

• API 调用更少 = 自动化速度更快
• 差异引用始终是最新的（刚由服务返回）
• 即时查看发生的变化（新元素、属性变化、移除项）

无插件快捷方式 - 所有浏览器命令中均包含自动功能

CI/CD 集成

在 CI 中运行测试

环境变量：

export QA_USE_API_KEY="your-api-key"
export QA_USE_REGION="us"  # Optional: "us" or "auto"

基本测试执行：

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

# Run specific tag
qa-use test run --tag smoke

# Exit codes: 0 = pass, 1 = fail

GitHub Actions 示例

name: QA Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - name: Install qa-use
        run: npm install -g @desplega.ai/qa-use
      - name: Run tests
        run: qa-use test run --all
        env:
          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}

测试产物

屏幕截图：

• 失败时自动保存
• 位置：/tmp/qa-use/downloads/（本地）或云端（远程）

日志：

• 控制台日志：qa-use browser logs console -s <session-id>
• 网络日志：qa-use browser logs network -s <session-id>

高级主题

本地主机测试（自动隧道）

当 API 位于远程时，qa-use 会为本地主机目标自动建立隧道。 常见情况下无需任何标志：

qa-use browser create --no-headless http://localhost:3000
qa-use test run my_test   # auto-tunnels if base_url is localhost

三态 --tunnel 标志：

值	行为
auto（默认）	仅当基础 URL 是本地主机且 API URL 是远程时建立隧道
on（或单独使用 --tunnel）	即使在开发模式下也强制建立隧道
off（或 --no-tunnel）	从不建立隧道

Testing localhost (http://localhost:3000)?
  ├─ API remote (default)  → auto-tunnels. No flag needed.
  ├─ API also local (dev)  → no tunnel by default. Use --tunnel on to force.
  └─ Public URL target     → no tunnel (remote cloud browser)

插件快捷方式会自动检测隧道：

/qa-use:explore http://localhost:3000
/qa-use:record start local_test

故障排除请参阅 references/localhost-testing.md。

会话持久化

会话存储在 ~/.qa-use.json 中，并具有以下特性：

• TTL：30 分钟（默认）
• 自动解析：只有一个活动会话时，无需 -s 标志
• 清理：超时或显式执行 browser close 时自动清理

录制限制

会捕获的内容：

• goto、click、fill、type、check、uncheck、select、hover
• scroll、scroll-into-view、drag、upload、press

不会捕获的内容：

• 断言（必须手动添加）
• 等待（根据时间推断，可能需要调整）
• 复杂交互（多次拖动、悬停序列）

手动编辑： 编辑生成的 YAML，以添加断言并优化选择器。

WebSocket 会话

跨进程共享会话：

# Process 1: Create session (auto-tunnels if target is localhost + API remote)
qa-use browser create http://localhost:3000
# Output: ws://localhost:12345/browser/abc123

# Process 2: Connect to session
qa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123

深入参考

可在运行时通过 CLI 访问任意参考文档：qa-use docs <topic>

主题	CLI 命令	描述
browser-commands.md	qa-use docs browser-commands	完整的浏览器 CLI 参考，包含所有标志
checks.md	qa-use docs checks	API 检查和检查计划工作流
test-format.md	qa-use docs test-format	完整的测试 YAML 规范
localhost-testing.md	qa-use docs localhost-testing	本地开发的隧道设置
failure-debugging.md	qa-use docs failure-debugging	失败分类和诊断
ci.md	qa-use docs ci	CI/CD 集成模式和示例

使用 qa-use docs --list 查找所有可用主题和模板。

模板

模板	描述
basic-test.yaml	简单的导航和断言
auth-flow.yaml	使用凭据的登录流程
form-test.yaml	带验证的表单提交

测试格式概览

name: Login Test
description: Validates login functionality with valid credentials
tags:
  - smoke
  - auth
app_config: <app-config-id>
variables:
  email: [email protected]
  password: secret123
depends_on: setup-test  # Optional
steps:
  - action: goto
    url: /login
  - action: fill
    target: email input
    value: $email
  - action: click
    target: login button
  - action: to_be_visible
    target: dashboard

完整规范请参阅 references/test-format.md。

常见错误

❌ 错误	✅ 正确
browser navigate <url>	browser goto <url>
browser destroy	browser close
browser close <session-id>	browser close
猜测元素引用	使用 diff 输出或 snapshot 中的引用
每次操作后都运行 snapshot	使用 diff 输出；仅在需要时运行 snapshot
在开发环境（两者都在本地）强制使用 --tunnel	依赖自动模式，或明确使用 --tunnel on
test sync --pull	test sync pull（子命令，而非标志）
test sync --push	test sync push（子命令，而非标志）

故障排除

遇到问题或意外错误时，请使用内置文档：

# Check configuration state
qa-use setup

# Browse main documentation
qa-use docs

# List all available topics
qa-use docs --list

# Access specific topic
qa-use docs <topic>

情况	命令
身份验证 / API 密钥错误	先运行 qa-use setup，再运行 qa-use docs
未知的浏览器命令	qa-use docs browser-commands
测试失败	qa-use docs failure-debugging
本地主机 / 隧道问题	qa-use docs localhost-testing
测试 YAML 语法	qa-use docs test-format
API 检查 / 计划	qa-use docs checks
CI/CD 设置	qa-use docs ci

关键规则：

• 务必先查阅 qa-use docs，再尝试自行变通
• 切勿编造 API 密钥、令牌、URL 或凭据
• 如果 qa-use setup 显示没有配置，请如实报告，不要猜测

npx 替代方案

所有命令均假设已全局安装 qa-use。如需临时使用：

npx @desplega.ai/qa-use browser <command>