OpenTest Skill

OpenTest 是一个面向 AI Agent 的自动化测试框架，让 AI 编辑器（Cursor、Claude Code、OpenClaw、Codex、Trae、Qoder 等）能够自动完成从需求解析到测试报告生成的全流程。

特性

• 一句话触发：在 AI 编辑器中说"帮我测试"，自动编排全流程
• 全流程自动化：捕获登录态 → 解析需求文档 → 生成测试用例 → 执行测试 → 生成报告
• 多平台支持：Cursor、Claude Code、OpenClaw、OpenAI Codex、Trae、Qoder
• 产物隔离：每个测试任务独立目录，登录态、用例、报告互不干扰
• Midscene.js 驱动：基于 AI Agent 的自然语言测试执行
• 多文档平台：支持飞书、语雀、Notion、58 美事等在线文档解析

架构概览

OpenTest 由 5 个协作 Skill 组成：

┌─────────────────────────────────────────────────────┐
│              opentest-test-task-manager              │
│                 （流程编排入口）                       │
│                                                      │
│  Step 1: 创建测试任务 ──────────────────────────────►  │
│  Step 2: 捕获登录态 ──► opentest-auth-capturer      │
│  Step 3: 解析文档 ────► opentest-doc-parser          │
│  Step 4: 生成用例 ────► opentest-test-case-generator │
│  Step 5: 执行测试 ────► opentest-test-executor       │
│                                                      │
└─────────────────────────────────────────────────────┘

| Skill | 职责 | |-------|------| | opentest-test-task-manager | 流程编排入口，管理任务目录和产物隔离 | | opentest-auth-capturer | 使用 Playwright 捕获浏览器登录态 | | opentest-doc-parser | 解析飞书/语雀/Notion 等在线文档 | | opentest-test-case-generator | 基于 AI 生成 Midscene.js 格式测试用例 | | opentest-test-executor | 执行 YAML 用例并生成 HTML 报告 |

安装

前置条件

• Node.js >= 18.0.0
• 已安装目标 AI 编辑器（Cursor / Claude Code / Codex / Trae / Qoder）

第一步：安装 Midscene Skills

OpenTest 的测试执行依赖 Midscene.js Skills。请根据你使用的 AI 编辑器选择对应的安装命令：

# 通用安装（自动检测平台）
npx skills add web-infra-dev/midscene-skills

# Cursor
npx skills add web-infra-dev/midscene-skills -a cursor

# Claude Code
npx skills add web-infra-dev/midscene-skills -a claude-code

# OpenClaw
npx skills add web-infra-dev/midscene-skills -a openclaw

# Qoder
npx skills add web-infra-dev/midscene-skills -a qoder

# Trae
npx skills add web-infra-dev/midscene-skills -a trae

为什么要安装 Midscene Skills？ OpenTest 生成的测试用例使用 Midscene.js 的自然语言 API（aiAction、aiAssert、aiQuery），执行测试时需要 Midscene Skills 来驱动浏览器。未安装将无法执行 Step 5（执行测试）。

第二步：安装 OpenTest Skill

在你的项目根目录运行：

npx opentest-skill init

安装程序会：

1. 自动检测已安装的 AI 编辑器
2. 交互式选择要安装到的平台
3. 将 Skill 文件部署到对应目录

全局安装

npm install -g opentest-skill
opentest init

非交互式安装

# 安装到所有检测到的平台
opentest init --tools all

# 只安装到 Cursor
opentest init --tools cursor

# 只安装到 OpenClaw（全局安装，无需在项目目录运行）
opentest init --tools openclaw

# 安装到多个平台
opentest init --tools cursor,claude-code,openclaw

注意：OpenClaw 是全局安装（技能安装到 ~/.openclaw/skills/opentest/），其他平台是项目级安装（安装到项目的 .xxx/skills/opentest/）。

第三步：安装 Playwright 浏览器

首次使用需要安装 Playwright 浏览器：

npx playwright install chromium

安装总结

| 步骤 | 命令 | 必需 | 说明 | |------|------|------|------| | 1 | npx skills add web-infra-dev/midscene-skills | 是 | 安装 Midscene 测试执行引擎 | | 2 | npx opentest-skill init | 是 | 安装 OpenTest 编排 Skills | | 3 | npx playwright install chromium | 是 | 安装浏览器运行时 |

安装后的目录结构

安装完成后，项目中会出现以下结构：

your-project/
├── opentest/
│   └── tasks/                          # 测试任务产物目录
├── .cursor/                            # (以 Cursor 为例)
│   ├── commands/
│   │   └── opentest.md                 # /opentest 命令入口
│   └── skills/
│       └── opentest/
│           ├── opentest-test-task-manager/
│           │   ├── SKILL.md            # 编排入口 Skill
│           │   ├── createTask.js       # 创建任务脚本
│           │   ├── generateCases.js    # 生成用例脚本
│           │   ├── runAuthCapture.js   # 捕获登录态脚本
│           │   ├── runDocParser.js     # 解析文档脚本
│           │   ├── runExecutor.js      # 执行测试脚本
│           │   └── lib/                # 工具库
│           ├── opentest-auth-capturer/
│           │   ├── SKILL.md
│           │   ├── captureAuth.js
│           │   └── captureAuthWeb.js
│           ├── opentest-doc-parser/
│           │   ├── SKILL.md
│           │   └── docParser.js
│           ├── opentest-test-case-generator/
│           │   └── SKILL.md
│           └── opentest-test-executor/
│               └── SKILL.md

使用方法

场景 1：全流程测试（最常用）

在 AI 编辑器的对话中直接说：

帮我测试这个需求 https://xxx.feishu.cn/docx/xxx

OpenTest 会自动执行以下流程：

Step 1: 创建测试任务
    ↓ 自动
Step 2: 捕获登录态（弹出浏览器让你登录）
    ↓ 登录完成后自动继续
Step 3: 解析需求文档（提取功能需求、业务规则）
    ↓ 自动
Step 4: 生成测试用例（15-25 条 Midscene.js YAML 用例）
    ↓ 自动
Step 5: 执行测试 + 生成 HTML 报告

整个过程你只需要在 Step 2 登录浏览器，其余全自动。

场景 2：只说"帮我测试"

帮我测试

AI 会询问你的需求文档 URL，然后自动启动全流程。

场景 3：只执行已有用例

如果你之前已经生成过测试用例：

跑一下测试

AI 会检查任务目录中的已有用例，直接跳到执行步骤。

场景 4：对指定系统测试

测试一下 https://staging.example.com

AI 会以该 URL 作为被测系统地址，启动全流程。

测试任务产物

每个测试任务在 opentest/tasks/<taskId>/ 下产生隔离的产物：

opentest/tasks/TASK-20260423-143025/
├── task.json                          # 任务元数据
├── auth/
│   └── auth-state.json                # 登录态（自动同步）
├── docs/
│   └── 2026-04-23T14-30-25/
│       ├── raw-content.md             # 原始文档内容
│       ├── structured-requirement.md  # 结构化需求文档
│       └── images/                    # 文档图片
├── cases/
│   ├── auth-state.json                # 执行器可见的登录态副本
│   └── BATCH-001/
│       ├── BATCH-INFO.md              # 用例批次信息
│       ├── 01-首页可打开并显示主导航.yaml
│       ├── 02-首页包含登录入口.yaml
│       └── ...                        # 更多用例 YAML
└── runs/
    └── RUN-001/
        ├── report/
        │   ├── index.html             # HTML 测试报告
        │   ├── summary.json           # 结构化报告数据
        │   └── artifacts/
        │       ├── screenshots/       # 步骤截图
        │       └── midscene/          # Midscene 原生报告
        └── logs/
            └── executor.log           # 执行日志

测试用例格式

OpenTest 生成基于 Midscene.js 的自然语言 YAML 用例：

name: "用户登录成功"
category: "main_flow"
priority: "P0"
baseUrl: "https://example.com/login"
preconditions:
  - "用户已注册账号"
steps:
  - type: "action"
    description: "在用户名输入框输入 admin"
    expected: "输入框显示admin"
  - type: "action"
    description: "在密码输入框输入 123456"
    expected: "密码输入框显示掩码"
  - type: "action"
    description: "点击登录按钮"
    expected: "开始登录请求"
  - type: "assertion"
    description: "验证页面显示欢迎消息"
    expected: "页面包含'欢迎回来'文本"
  - type: "screenshot"
    description: "截图保存登录成功状态"

用例分类

| 分类 | 说明 | 优先级 | 数量 | |------|------|--------|------| | main_flow | 主流程测试 | P0 | 3-5 条 | | exception_flow | 异常流程测试 | P1 | 3-4 条 | | edge_case | 边界条件测试 | P1/P2 | 2-3 条 | | data_validation | 数据验证测试 | P1 | 2-3 条 | | ui_ux | UI/UX 测试 | P2 | 2-3 条 | | permission | 权限控制测试 | P0/P1 | 1-2 条 | | state_management | 状态管理测试 | P1/P2 | 1-2 条 | | cross_page | 跨页面流程测试 | P1 | 1-2 条 |

支持的文档平台

| 平台 | 域名 | 说明 | |------|------|------| | 飞书文档 | feishu.cn, larksuite.com | 需要登录态 | | 语雀 | yuque.com | 需要登录态 | | Notion | notion.so | 公开文档免登录 | | 58 美事文档 | docs.58corp.com | 需要登录态 | | 通用网页 | 任意 URL | - |

支持的 AI 编辑器

| 平台 | Skill 安装目录 | 安装范围 | 命令入口 | |------|---------------|---------|----------| | Cursor | .cursor/skills/opentest/ | 项目级 | /opentest | | Claude Code | .claude/skills/opentest/ | 项目级 | 自动触发 | | OpenClaw | ~/.openclaw/skills/opentest/ | 全局 | 自动触发 | | OpenAI Codex | .agents/skills/opentest/ | 项目级 | 自动触发 | | Trae | .trae/skills/opentest/ | 项目级 | 自动触发 | | Qoder | .qoder/skills/opentest/ | 项目级 | 自动触发 |

登录态管理

OpenTest 使用 Playwright 的 storageState 机制管理登录态：

1. 运行 captureAuth.js 时自动打开 Chromium 浏览器
2. 用户在浏览器中完成登录
3. 回复"已登录"后，AI 触发保存
4. 登录态保存为 auth-state.json（包含 cookies + localStorage）
5. 后续测试自动加载该登录态

登录态文件查找顺序

1. 环境变量 AUTH_STATE_PATH 指定的路径
2. 任务目录下 auth/auth-state.json
3. 任务目录下 cases/auth-state.json（执行器可见副本）

开发

# 克隆仓库
git clone https://github.com/jiazhengc/agent_skills.git
cd agent_skills/opentest-skill

# 安装依赖
npm install

# 开发模式
npm run dev -- --help

# 编译
npm run build

# 本地测试安装
node dist/index.js init /path/to/test-project

许可证

ISC

相关项目

• Midscene.js - AI 驱动的 UI 自动化框架
• Playwright - 浏览器自动化框架
• codereview-skill - 代码审查 AI Skill