qa-use

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

qa-use

E2E testing and browser automation for AI-driven development workflows.

面向AI驱动开发工作流的端到端（E2E）测试与浏览器自动化工具。

Critical Insight: Plugin Commands as Shortcuts

关键提示：插件命令作为快捷方式

For AI Harnesses (codex, opencode, etc.):

Plugin commands (slash commands like

/qa-use:verify

) are convenience shortcuts that wrap CLI workflows. Harnesses with only the Bash tool can access ALL functionality via CLI commands documented below.

Pattern throughout this document:

CLI Workflow: Step-by-step CLI commands (works for ALL harnesses)
Plugin Shortcut: Optional slash command (convenience)

针对AI工具（codex、opencode等）：

插件命令（如

/qa-use:verify

这类斜杠命令）是封装CLI工作流的便捷快捷方式。仅支持Bash工具的平台可通过下文记录的CLI命令访问全部功能。

本文档通用格式：

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

Core Workflow

核心工作流

1. Browser Control & Session Lifecycle

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

CLI Workflow:

bash

undefined

CLI工作流：

bash

undefined

Create browser session

创建浏览器会话

qa-use browser create --viewport desktop

For localhost testing

本地测试专用

qa-use browser create --tunnel --no-headless

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


**Plugin Shortcut:**

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

(Wraps create + goto + snapshot with autonomous exploration)

**Critical:** Always run `snapshot` before interacting. Never guess element refs.

**Snapshot Diff Feature:**
After each action (goto, click, fill, etc.), the browser automatically shows DOM changes:
- **Summary**: "5 elements added, 1 element modified"
- **Added elements**: `+ [e54] generic "Thanks for agreeing!"` (green)
- **Modified elements**: `~ [e18] checkbox "I agree..."` with `+attrs: checked, active` (yellow)
- **Removed elements**: `- [e99] button "Submit"` (red)

This helps you understand what changed after each action without manually inspecting the DOM.

qa-use browser close


**插件快捷方式：**

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

（封装了创建会话、导航、快照及自动探索流程）

**重要提示：** 交互前必须执行`snapshot`命令，切勿猜测元素引用。

**快照差异功能：**
每次操作（导航、点击、填充等）后，浏览器会自动展示DOM变化：
- **摘要**："新增5个元素，修改1个元素"
- **新增元素**：`+ [e54] generic "Thanks for agreeing!"`（绿色标识）
- **修改元素**：`~ [e18] checkbox "I agree..."` 附带`+attrs: checked, active`（黄色标识）
- **移除元素**：`- [e99] button "Submit"`（红色标识）

无需手动检查DOM，即可快速了解每次操作后的页面变化。

2. Understanding Blocks

2. 理解Blocks（交互块）

What are blocks?

Blocks are atomic recorded interactions from a browser session. They are:

Automatically captured during any browser interaction (click, fill, goto, scroll, etc.)
Stored server-side with the session
Retrieved via
```
qa-use browser get-blocks
```
The foundation for test generation

Why blocks matter:

Record-once, replay-many: Interactive recording becomes automated test
AI-friendly: Agents can analyze blocks to understand user intent
Version control: Blocks stored with session enable test iteration
Bridge CLI → Tests: Natural workflow from exploration to automation

How blocks work:

bash

undefined

什么是Blocks？

Blocks是浏览器会话中记录的原子化交互操作，具备以下特性：

所有浏览器交互（点击、填充、导航、滚动等）都会自动捕获为Blocks
与会话一起存储在服务器端
可通过
```
qa-use browser get-blocks
```
命令获取
是生成自动化测试用例的基础

Blocks的重要性：

一次录制，多次复用：交互式录制可直接转为自动化测试
AI友好：智能体可分析Blocks理解用户意图
版本控制：与会话绑定的Blocks支持测试用例迭代
桥接CLI与测试：从探索到自动化的自然工作流

Blocks的使用流程：

bash

undefined

1. Create session and interact

1. 创建会话并执行交互操作

qa-use browser create --tunnel --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

qa-use browser create --tunnel --no-headless qa-use browser goto https://example.com qa-use browser snapshot # 返回结果：[ref=e1] button qa-use browser click e1 # 记录为Block qa-use browser fill e5 "text" # 记录为Block

2. Retrieve blocks (JSON array)

2. 获取Blocks（JSON数组格式）

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

3. 基于Blocks生成测试用例YAML文件

qa-use browser generate-test -n "my_test" -o qa-tests/my_test.yaml

4. Run generated test

4. 运行生成的测试用例

qa-use test run my_test


**Plugin Shortcut:**

/qa-use:record start my_test

qa-use test run my_test


**插件快捷方式：**

/qa-use:record start my_test

... perform interactions ...

... 执行交互操作 ...

/qa-use:record stop

(Wraps the interactive workflow with AI-powered test generation)

/qa-use:record stop

（封装了交互式工作流及AI驱动的测试用例生成）

3. Test Management

3. 测试用例管理

CLI Workflow:

bash

undefined

CLI工作流：

bash

undefined

Run test by name

按名称运行测试用例

qa-use test run login

Run with autofix (AI self-healing)

启用AI自修复功能运行测试

qa-use test run login --autofix

Validate syntax

验证测试用例语法

qa-use test validate login

Show test details

查看测试用例详情

qa-use test info login

List test runs

列出测试运行记录

qa-use test runs --status failed


**Plugin Shortcut:**

/qa-use:test-run login --autofix

(Convenience shortcut for common test execution)

qa-use test runs --status failed


**插件快捷方式：**

/qa-use:test-run login --autofix

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

4. Test Sync Lifecycle

4. 测试用例同步生命周期

CLI Workflow:

bash

undefined

CLI工作流：

bash

undefined

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


**No Plugin Shortcut** - Use CLI commands directly

qa-use test diff login.yaml


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

Essential Commands

核心命令

Browser Session Management

浏览器会话管理

Command	Description
`qa-use browser create`	Create remote browser session
`qa-use browser create --tunnel`	Create local browser with API tunnel
`qa-use browser create --no-headless`	Show browser window (tunnel mode only)
`qa-use browser create --viewport <size>`	Set viewport: `desktop` , `tablet` , `mobile`
`qa-use browser create --ws-url <url>`	Connect to existing WebSocket browser
`qa-use browser create --after-test-id <uuid>`	Run a test first, then become interactive
`qa-use browser create --var <key=value>`	Override app config variables (repeatable)
`qa-use browser list`	List active sessions
`qa-use browser status`	Show current session details (app_url, recording_url, etc.)
`qa-use browser close`	Close active session

Sessions auto-persist in

~/.qa-use.json

. One active session = no

-s

flag needed.

命令	描述
`qa-use browser create`	创建远程浏览器会话
`qa-use browser create --tunnel`	创建带API隧道的本地浏览器会话
`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 close`	关闭活跃会话

会话会自动持久化到

~/.qa-use.json

文件中。仅存在一个活跃会话时，无需使用

-s

参数指定会话ID。

Navigation

页面导航

Command	Description
`qa-use browser goto <url>`	Navigate to URL
`qa-use browser back`	Go back
`qa-use browser forward`	Go forward
`qa-use browser reload`	Reload page

命令	描述
`qa-use browser goto <url>`	导航到指定URL
`qa-use browser back`	后退到上一页
`qa-use browser forward`	前进到下一页
`qa-use browser reload`	刷新当前页面

Element Interaction

元素交互

Command	Description
`qa-use browser click <ref>`	Click element by ref
`qa-use browser click --text "Button"`	Click by semantic description
`qa-use browser fill <ref> "value"`	Fill input field
`qa-use browser type <ref> "text"`	Type with delays (for autocomplete)
`qa-use browser press <key>`	Press key (e.g., `Enter` , `Tab` )
`qa-use browser check <ref>`	Check checkbox
`qa-use browser uncheck <ref>`	Uncheck checkbox
`qa-use browser select <ref> "option"`	Select dropdown option
`qa-use browser hover <ref>`	Hover over element
`qa-use browser scroll down 500`	Scroll by pixels
`qa-use browser scroll-into-view <ref>`	Scroll element into view
`qa-use browser drag <ref> --target <ref>`	Drag element to target
`qa-use browser mfa-totp [ref] <secret>`	Generate TOTP code (optionally fill)
`qa-use browser upload <ref> <file>...`	Upload file(s) to input

命令	描述
`qa-use browser click <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>...`	向输入框上传文件

Inspection & Snapshot Diff

检查与快照差异

Command	Description
`qa-use browser snapshot`	Get ARIA tree with element refs (shows snapshot diff after actions)
`qa-use browser url`	Get current URL
`qa-use browser screenshot`	Save screenshot.png
`qa-use browser screenshot file.png`	Save to custom path
`qa-use browser screenshot --base64`	Output base64 to stdout
`qa-use browser evaluate <expression>`	Execute JavaScript in browser context

The snapshot-diff feature automatically displays DOM changes after each browser action:

Added elements: Shown with
```
+
```
prefix and green color
Modified elements: Shown with
```
~
```
prefix and yellow color, including attribute changes (
```
+attrs: checked
```
)
Removed elements: Shown with
```
-
```
prefix and red color

命令	描述
`qa-use browser snapshot`	获取带元素引用的ARIA树（操作后自动展示快照差异）
`qa-use browser url`	获取当前页面URL
`qa-use browser screenshot`	保存为screenshot.png
`qa-use browser screenshot file.png`	保存到指定路径
`qa-use browser screenshot --base64`	以base64格式输出到标准输出
`qa-use browser evaluate <expression>`	在浏览器上下文执行JavaScript代码

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

新增元素：以
```
+
```
前缀和绿色标识展示
修改元素：以
```
~
```
前缀和黄色标识展示，包含属性变化（如
```
+attrs: checked
```
）
移除元素：以
```
-
```
前缀和红色标识展示

Test Operations

测试操作

Command	Description
`qa-use test run <name>`	Run test by name
`qa-use test run --all`	Run all tests
`qa-use test run <name> --tunnel`	Run with local browser tunnel
`qa-use test run <name> --autofix`	Enable AI self-healing
`qa-use test run <name> --update-local`	Persist AI fixes to file
`qa-use test run <name> --download`	Download assets to `/tmp/qa-use/downloads/`
`qa-use test run <name> --var key=value`	Override variable
`qa-use test validate <name>`	Validate test syntax
`qa-use test list`	List available tests
`qa-use test info <name>`	Show test details (steps, tags, description)
`qa-use test info --id <uuid>`	Show cloud test details by ID
`qa-use test runs [name]`	List test run history
`qa-use test runs --id <uuid>`	Filter runs by test ID
`qa-use test runs --status failed`	Filter runs by status
`qa-use test init`	Initialize test directory
`qa-use test sync pull`	Pull tests from cloud
`qa-use test sync push --all`	Push all local tests to cloud
`qa-use test sync push --id <uuid>`	Push specific test
`qa-use test sync push --force`	Push tests, overwriting conflicts
`qa-use test diff <file>`	Compare local vs cloud test
`qa-use test schema [path]`	View test definition schema

命令	描述
`qa-use test run <name>`	按名称运行测试用例
`qa-use test run --all`	运行所有测试用例
`qa-use test run <name> --tunnel`	通过本地浏览器隧道运行测试
`qa-use test run <name> --autofix`	启用AI自修复功能
`qa-use test run <name> --update-local`	将AI修复结果持久化到本地文件
`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]`	查看测试用例定义 schema

Logs & Debugging

日志与调试

Command	Description
`qa-use browser logs console`	View console logs from session
`qa-use browser logs console -s <id>`	View logs from specific/closed session
`qa-use browser logs network`	View network request logs
`qa-use browser logs network -s <id>`	View network logs from specific session

命令	描述
`qa-use browser logs console`	查看会话中的控制台日志
`qa-use browser logs console -s <id>`	查看指定/已关闭会话的控制台日志
`qa-use browser logs network`	查看网络请求日志
`qa-use browser logs network -s <id>`	查看指定会话的网络请求日志

Test Generation

测试用例生成

Command	Description
`qa-use browser generate-test`	Generate test YAML from recorded session
`qa-use browser generate-test -s <id>`	Generate from specific session
`qa-use browser generate-test -n <name>`	Specify test name
`qa-use browser generate-test -o <path>`	Specify output path
`qa-use browser get-blocks`	Get recorded interaction blocks (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`	获取录制的交互Blocks（JSON格式）

Waiting

等待操作

Command	Description
`qa-use browser wait <ms>`	Fixed wait
`qa-use browser wait-for-selector ".class"`	Wait for selector
`qa-use browser wait-for-load`	Wait for page load

命令	描述
`qa-use browser wait <ms>`	固定时长等待
`qa-use browser wait-for-selector ".class"`	等待选择器对应的元素出现
`qa-use browser wait-for-load`	等待页面加载完成

Variable Overrides

变量覆盖

Use

--var

to override app config variables at runtime. Common variables:

Variable	Description
`base_url`	Base URL for the app (e.g., preview deployment URL)
`login_url`	Login page URL
`login_username`	Username/email for authentication
`login_password`	Password for authentication

Example with ephemeral preview URL:

bash

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

可使用

--var

参数在运行时覆盖应用配置变量，常用变量如下：

变量	描述
`base_url`	应用基础URL（如预览部署URL）
`login_url`	登录页面URL
`login_username`	认证用用户名/邮箱
`login_password`	认证用密码

临时预览URL示例：

bash

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

Common Patterns

常见使用模式

Pattern 1: Feature Verification

模式1：功能验证

CLI Workflow:

bash

undefined

CLI工作流：

bash

undefined

1. Search for existing test

1. 搜索已存在的测试用例

qa-use test list | grep "login"

2. Run test with autofix

2. 启用自修复功能运行测试

qa-use test run login --autofix

3. Debug failures

3. 调试失败场景

qa-use browser logs console


**Plugin Shortcut:**

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

(Wraps the above CLI workflow with AI-powered test discovery and analysis)

qa-use browser logs console


**插件快捷方式：**

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

（封装了AI驱动的测试用例发现与分析流程）

Pattern 2: Record & Generate Test

模式2：录制并生成测试用例

CLI Workflow:

bash

undefined

CLI工作流：

bash

undefined

1. Create session

1. 创建会话

qa-use browser create --tunnel --no-headless

2. Navigate and interact

2. 导航并执行交互

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

3. 基于Blocks生成测试用例

qa-use browser get-blocks qa-use browser generate-test -n "my_test"

4. Run test

4. 运行测试用例

qa-use test run my_test


**Plugin Shortcut:**

/qa-use:record start my_test

qa-use test run my_test


**插件快捷方式：**

/qa-use:record start my_test

... perform interactions ...

... 执行交互操作 ...

/qa-use:record stop

undefined

/qa-use:record stop

undefined

Pattern 3: Authenticated Exploration

模式3：已认证状态下的探索

CLI Workflow:

bash

undefined

CLI工作流：

bash

undefined

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


**Plugin Shortcut:**

/qa-use:explore /dashboard

(Automatically handles auth detection and session creation)

qa-use browser goto /dashboard qa-use browser snapshot


**插件快捷方式：**

/qa-use:explore /dashboard

（自动处理认证检测与会话创建）

Pattern 4: Edit Existing Test

模式4：编辑已有测试用例

CLI Workflow:

bash

undefined

CLI工作流：

bash

undefined

1. Open test file in editor

1. 在编辑器中打开测试用例文件

vim qa-tests/login.yaml

2. Validate syntax

2. 验证语法

qa-use test validate login

3. Run to verify

3. 运行测试验证

qa-use test run login


**Plugin Shortcut:**

/qa-use:record edit login

(AI-assisted editing with validation)

qa-use test run login


**插件快捷方式：**

/qa-use:record edit login

（AI辅助编辑及语法验证）

Pattern 5: Understanding DOM Changes with Snapshot Diff

模式5：通过快照差异理解DOM变化

CLI Workflow:

bash

undefined

CLI工作流：

bash

undefined

Create session and navigate

创建会话并导航

qa-use browser create --tunnel --no-headless qa-use browser goto https://evals.desplega.ai/checkboxes

Output shows initial elements:

输出初始元素：

Changes: 45 elements added

变化：新增45个元素

+ [e18] checkbox "I agree to the terms and conditions"

+ [e19] generic "I agree to the terms and conditions"

Click checkbox

点击复选框

qa-use browser click e18

Snapshot diff automatically shows:

自动展示快照差异：

Changes: 5 elements added, 1 element modified

变化：新增5个元素，修改1个元素

+ [e54] generic "Thanks for agreeing!"

+ [e55] link "Terms and Conditions"

~ [e18] checkbox "I agree to the terms and conditions"

+attrs: active, checked


**Why this matters:**
- Instantly see what changed after each action
- Identify new elements that appeared (e.g., success messages, modals)
- Track attribute changes (checked, disabled, aria-expanded)
- Debug failed assertions by understanding actual DOM state changes

**No Plugin Shortcut** - Automatic feature in all browser commands


**该功能的价值：**
- 即时查看每次操作后的页面变化
- 识别新增元素（如成功提示、弹窗）
- 跟踪属性变化（如checked、disabled、aria-expanded）
- 通过了解实际DOM状态变化调试断言失败问题

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

CI/CD Integration

CI/CD集成

Running Tests in CI

在CI中运行测试

Environment Variables:

bash

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

Basic Test Execution:

bash

undefined

环境变量配置：

bash

export QA_USE_API_KEY="your-api-key"
export QA_USE_REGION="us"  # 可选值："us" 或 "auto"

基础测试执行：

bash

undefined

Run all tests

运行所有测试用例

qa-use test run --all

Run specific tag

运行指定标签的测试用例

qa-use test run --tag smoke

Exit codes: 0 = pass, 1 = fail

退出码：0=通过，1=失败

undefined

undefined

GitHub Actions Example

GitHub Actions示例

yaml

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 }}

yaml

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 }}

Test Artifacts

测试产物

Screenshots:

Automatically saved on failure
Location:
```
/tmp/qa-use/downloads/
```
(local) or cloud (remote)

Logs:

Console logs:

qa-use browser logs console -s <session-id>

Network logs:

qa-use browser logs network -s <session-id>

截图：

测试失败时自动保存
存储位置：本地为
```
/tmp/qa-use/downloads/
```
，远程为云端

日志：

控制台日志：

qa-use browser logs console -s <session-id>

网络日志：

qa-use browser logs network -s <session-id>

Advanced Topics

进阶主题

Localhost Testing (Tunnel Mode)

本地测试（隧道模式）

When to use tunnel mode:

Testing localhost (http://localhost:3000)?
  ├─ YES → Use --tunnel
  │   └─ qa-use browser create --tunnel [--no-headless]
  │       (Starts local Playwright, creates localtunnel, keeps running)
  │
  └─ NO (Public URL) → Use remote browser (default)
      └─ qa-use browser create
          (Uses desplega.ai cloud browser via WebSocket)

The
--tunnel
flag is a binary choice:

Local tunnel mode: Playwright on your machine + localtunnel
Remote mode: WebSocket URL to cloud-hosted browser

For test execution:

bash

undefined

何时使用隧道模式：

是否测试本地服务（http://localhost:3000）？
  ├─ 是 → 使用--tunnel参数
  │   └─ qa-use browser create --tunnel [--no-headless]
  │       (启动本地Playwright，创建localtunnel，保持运行)
  │
  └─ 否（公网URL） → 使用远程浏览器（默认）
      └─ qa-use browser create
          (通过WebSocket连接desplega.ai云端浏览器)

--tunnel
参数为二选一选项：

本地隧道模式：本地机器运行Playwright + localtunnel
远程模式：通过WebSocket URL连接云端托管的浏览器

测试执行场景：

bash

undefined

Local app

本地应用

qa-use test run my_test --tunnel [--headful]

Public app

公网应用

qa-use test run my_test


**Plugin shortcuts handle tunnel detection automatically:**

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


See [references/localhost-testing.md](references/localhost-testing.md) for troubleshooting.

qa-use test run my_test


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

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


故障排查请参考[references/localhost-testing.md](references/localhost-testing.md)。

Session Persistence

会话持久化

Sessions are stored in

~/.qa-use.json

and have:

TTL: 30 minutes (default)
Auto-resolve: One active session = no
```
-s
```
flag needed
Cleanup: Automatic on timeout or explicit
```
browser close
```

会话存储在

~/.qa-use.json

文件中，具备以下特性：

TTL（存活时间）：默认30分钟
自动解析：仅存在一个活跃会话时，无需使用
```
-s
```
参数指定
自动清理：超时或执行
```
browser close
```
命令时自动清理

Block Limitations

Blocks的限制

What's captured:

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

What's NOT captured:

Assertions (must be added manually)
Waits (inferred from timing, may need adjustment)
Complex interactions (multi-drag, hover sequences)

Manual editing: Edit generated YAML to add assertions and refine selectors.

支持捕获的操作：

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

不支持捕获的操作：

断言（需手动添加）
等待操作（可从时间推断，可能需要调整）
复杂交互（如多步拖拽、连续悬停）

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

WebSocket Sessions

WebSocket会话

Sharing sessions across processes:

bash

undefined

跨进程共享会话：

bash

undefined

Process 1: Create session

进程1：创建会话

qa-use browser create --tunnel

Output: ws://localhost:12345/browser/abc123

输出：ws://localhost:12345/browser/abc123

Process 2: Connect to session

进程2：连接到已有会话

qa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123

undefined

qa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123

undefined

Deep-Dive References

深度参考文档

Document	Description
browser-commands.md	Complete browser CLI reference with all flags
test-format.md	Full test YAML specification
localhost-testing.md	Tunnel setup for local development
failure-debugging.md	Failure classification and diagnostics
ci.md	CI/CD integration patterns and examples

文档	描述
browser-commands.md	完整的浏览器CLI命令参考及所有参数说明
test-format.md	完整的测试用例YAML规范
localhost-testing.md	本地开发环境测试的隧道设置指南
failure-debugging.md	失败场景分类与诊断指南
ci.md	CI/CD集成模式与示例

Templates

模板

Template	Description
basic-test.yaml	Simple navigation and assertion
auth-flow.yaml	Login flow with credentials
form-test.yaml	Form submission with validation

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

Test Format Overview

测试用例格式概述

yaml

name: Login Test
description: Validates login functionality with valid credentials
tags:
  - smoke
  - auth
app_config: <app-config-id>
variables:
  email: test@example.com
  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

See references/test-format.md for complete specification.

yaml

name: Login Test
description: Validates login functionality with valid credentials
tags:
  - smoke
  - auth
app_config: <app-config-id>
variables:
  email: test@example.com
  password: secret123
depends_on: setup-test  # 可选
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。

Common Mistakes

常见错误

❌ Wrong	✅ Correct
`browser navigate <url>`	`browser goto <url>`
`browser destroy`	`browser close`
`browser close <session-id>`	`browser close`
Guessing element refs	Always `snapshot` first
Testing localhost without `--tunnel`	Use `--tunnel` flag
`test sync --pull`	`test sync pull` (subcommand, not flag)
`test sync --push`	`test sync push` (subcommand, not flag)

❌ 错误用法	✅ 正确用法
`browser navigate <url>`	`browser goto <url>`
`browser destroy`	`browser close`
`browser close <session-id>`	`browser close`
猜测元素引用	始终先执行 `snapshot`
测试本地服务未使用 `--tunnel`	使用 `--tunnel` 参数
`test sync --pull`	`test sync pull` （子命令，非参数）
`test sync --push`	`test sync push` （子命令，非参数）

npx Alternative

npx替代方案

All commands use

qa-use

assuming global install. For one-off use:

bash

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

假设已全局安装qa-use，所有命令使用

qa-use

前缀。如需一次性使用：

bash

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