eTestClaw 使用指南

eTestClaw 是一款 AI 驱动的 CLI 测试助手，基于自然语言交互完成从需求分析、测试点生成、用例编写到自动化执行的完整测试流程。

目录

• 安装
• 配置
• 快速开始
• 核心概念
• 命令行与快捷键
• 技能系统
• MCP 服务器集成
• 测试用例管理
• 长期记忆
• 上下文压缩
• 图片处理模式
• 子代理并行执行
• 常见问题

安装

通过 npm 安装（推荐）

npm install -g @thinski/etestclaw

验证安装

etestclaw --version

配置

eTestClaw 首次启动时会自动在 ~/.etestclaw/config.json 生成默认配置文件。

配置文件路径

• 默认：~/.etestclaw/config.json（~ 指用户主目录，windows用户一般是C:\Users\你的开发网用户名）
• 自定义：etestclaw -c /path/to/config.json

完整配置项

{
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-your-api-key-here",
  "model": "gpt-4o",

  "mcpServers": {
    "playwright": {
      "disabled": false,
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  },

  "skill_dirs": [],

  "image_mode": "direct",

  "vl_model": {
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-your-vl-api-key-here",
    "model": "gpt-4o"
  },

  "context_compression": {
    "enabled": false,
    "trigger": [
      { "type": "messages", "value": 50 },
      { "type": "tokens", "value": 160000 }
    ],
    "keep": { "type": "messages", "value": 10 }
  }
}

配置项说明

| 配置项 | 必填 | 说明 | |--------|------|------| | base_url | 是 | LLM API 的 base URL，支持 OpenAI 及兼容 API | | api_key | 是 | LLM API 密钥 | | model | 是 | 使用的模型名称，如 gpt-4o、gpt-4o-mini | | mcpServers | 否 | MCP 服务器配置，用于扩展工具能力 | | skill_dirs | 否 | 额外搜索技能文件的目录列表 | | image_mode | 否 | 图片处理模式：direct（默认）或 vl | | vl_model | 否 | 当 image_mode 为 vl 时使用的视觉模型配置 | | context_compression | 否 | 上下文压缩配置，详见上下文压缩 |

快速开始

1. 填写配置

编辑 ~/.etestclaw/config.json，填入你的 API Key：

{
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-your-key",
  "model": "gpt-4o"
}

2. 启动程序

etestclaw

启动后显示欢迎界面：

══════════════════════════════════════════════════
  ◐ eTestClaw  · AI 驱动的专业测试助手
══════════════════════════════════════════════════
  /clear  清除对话历史    /cases  列出测试用例    /skills  查看技能    Ctrl+C  中断 / 退出
══════════════════════════════════════════════════

You ›

3. 基本交互

直接在提示符输入需求或任务描述，AI 会自动分析并执行。

核心概念

测试工作流

eTestClaw 遵循标准的测试流程：

需求分析 → 测试点生成 → 测试用例生成 → 评审 → 执行

每个环节都有对应的技能（Skill）来完成。

技能（Skill）

技能是 eTestClaw 的核心扩展单位。每个技能是一个独立目录，包含 SKILL.md 说明文件。技能可以被用户通过 /技能名 直接调用，也可以被 AI 在对话中自动触发。

MCP（Model Context Protocol）

MCP 是一种扩展 AI 工具能力的协议。通过配置 MCP 服务器，eTestClaw 可以连接各种外部服务（如 Playwright）来执行自动化操作。

工具（Tool）

eTestClaw 内置一组基础工具：

| 工具 | 说明 | |------|------| | read_file | 读取本地文件 | | write_file | 写入本地文件 | | bash | 执行 shell 命令 | | test_cases | 管理测试用例和测试点 | | memory | 管理长期记忆 | | task | 派发子代理并行执行任务 |

命令行与快捷键

内置命令

| 命令 | 说明 | |------|------| | /clear | 清除当前对话历史 | | /cases | 列出已保存的测试用例 | | /skills | 查看所有可用技能 | | /memory | 查看/管理长期记忆 | | /memory list | 查看当前记忆内容 | | /memory add <文本> | 添加新记忆 | | /memory remove <子串> | 移除包含指定子串的记忆 | | /memory clear | 清空所有记忆（需二次确认） |

快捷键

| 快捷键 | 说明 | |--------|------| | Ctrl+C（单次） | 中断当前正在执行的请求 | | Ctrl+C（双次） | 强制退出程序 |

Tab 自动补全

输入 / 开头的命令时，按 Tab 可自动补全技能名称。

技能系统

内置技能

| 技能 | 命令 | 说明 | |------|------|------| | 需求转测试点 | /requirement2testpoints | 深度分析需求文档，生成结构化测试点 | | 生成测试用例 | /generate-test-cases | 基于测试点生成细粒度测试用例 | | 评审测试用例 | /review-test-cases | 对已生成的测试用例进行系统性评审 | | 执行测试用例 | /execute-test-cases | 自动化执行测试用例，支持多浏览器并行 |

完整测试流程示例

# 1. 启动 eTestClaw
etestclaw

# 2. 分析需求并生成测试点
You › /requirement2testpoints 百度首页搜索功能
或者：
You › 帮我生成百度首页搜索功能的测试点

# 3. 基于测试点生成测试用例
You › /generate-test-cases 百度首页搜索功能
或者：
You › 生成百度首页搜索功能的测试用例

# 4. 评审测试用例
You › /review-test-cases 百度首页搜索功能
或者：
You › 评审百度首页搜索功能的测试用例

# 5. 执行测试用例
You › /execute-test-cases 百度首页搜索功能
如果测试点还没有生成，会自动先生成测试点，评审后再生成测试用例
或者：
You › 执行百度首页搜索功能的测试用例

技能工作目录

技能文件存放在以下目录（按优先级依次查找）：

1. 项目内 skills/ 目录
2. 当前工作目录 skills/
3. ~/.etestclaw/skills/
4. ~/.roo/skills/
5. ~/.claude/skills/
6. 自定义 skill_dirs 配置的目录

MCP 服务器集成

配置示例

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "my-sse-server": {
      "type": "sse",
      "url": "http://localhost:3000/sse",
      "disabled": true
    },
    "my-http-server": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "disabled": true
    },
    "my-ws-server": {
      "type": "websocket",
      "url": "ws://localhost:3000/mcp",
      "disabled": true
    }
  }
}

MCP 服务器类型

| 类型 | 说明 | 必填配置 | |------|------|---------| | stdio | 标准输入输出（默认） | command, args | | sse | Server-Sent Events | url | | streamable-http | HTTP 流式传输 | url | | websocket | WebSocket | url |

高级配置

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "DEBUG": "1"
      },
      "alwaysAllow": ["screenshot", "click"],
      "timeout": 120
    }
  }
}

| 高级配置 | 说明 | |----------|------| | env | 传递给进程的环境变量 | | alwaysAllow | 无需用户确认自动允许的工具列表 | | timeout | 连接超时时间（秒），默认 60 | | disabled | 设置为 true 可禁用该服务器 |

测试用例管理

测试用例文件存储位置

当前目录/
└── cases/
    ├── {功能名称}.md           # 测试用例
    ├── {功能名称}-test-points.md  # 测试点
    └── {功能名称}-{timestamp}.md # 执行结果

测试用例格式（XMind 兼容 Markdown）

# {功能名称} 测试用例

## {子模块名称}
### TC-001 {测试用例标题} 【P0】
#### 前置条件
- {具体的数据状态}
- {用户/权限状态}
- {系统状态}
#### 测试步骤
- 步骤1: {具体操作}
- 步骤2: {具体操作}
#### 预期结果
- {可验证的具体结果}

### TC-002 {测试用例标题} 【P1】
...

测试点格式（XMind 兼容 Markdown）

# {功能名称} 测试点

## {子模块名称}
### TP-001 {测试点标题}
- 优先级: P0 | P1 | P2
- 场景类型: 正常 | 异常 | 边界
- 覆盖规则: {对应的业务规则}
- 前置状态: {系统/数据状态}
- 测试思路: {验证方法}

### TP-002 {测试点标题}
...

优先级定义

| 优先级 | 说明 | |--------|------| | P0 | 核心业务规则验证、主流程关键节点，阻塞发布 | | P1 | 重要交互逻辑、异常处理、权限校验，版本必测 | | P2 | 辅助交互、极端边界，有时间时测试 |

长期记忆

eTestClaw 支持跨会话的长期记忆功能。

记忆命令

/memory list              # 查看当前记忆
/memory add <文本>         # 添加新记忆
/memory remove <子串>      # 移除包含指定子串的记忆
/memory clear              # 清空所有记忆（需二次确认）

存储位置

记忆文件位于 ~/.etestclaw/memories/MEMORY.md，每条记忆有 2200 字符限制。

工作机制

• 记忆在每次启动时加载到系统提示中
• 新增或修改记忆在下次启动时生效
• 记忆不会自动去重，相同内容会被合并

上下文压缩

当对话历史过长时，eTestClaw 可以自动压缩上下文以节省 token。

启用上下文压缩

{
  "context_compression": {
    "enabled": true,
    "trigger": [
      { "type": "messages", "value": 50 },
      { "type": "tokens", "value": 160000 }
    ],
    "keep": { "type": "messages", "value": 10 }
  }
}

配置说明

| 配置项 | 说明 | |--------|------| | enabled | 是否启用压缩 | | trigger | 触发压缩的条件（消息数或 token 数） | | keep | 压缩后保留的最近消息数 |

触发示例

• 消息数达到 50 条时触发压缩
• 或 token 数达到 160000 时触发压缩
• 压缩后保留最近 10 条消息

图片处理模式

direct 模式（默认）

图片以 URL 或 base64 形式直接发送给 LLM 处理。

vl 模式

使用独立的视觉模型（Vision-LLM）来描述图片内容，适用于超长文本或复杂图片场景。

配置 vl 模式

{
  "image_mode": "vl",
  "vl_model": {
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-your-vl-key",
    "model": "gpt-4o"
  }
}

子代理并行执行

eTestClaw 支持通过 task 工具派发多个子代理并行执行任务，显著提升测试执行效率。

并行执行测试用例

/execute-test-cases 百度搜索功能 --parallel=5

支持的并行指定方式：

• --parallel=5
• 并行5个
• 同时开5个浏览器

最大并行数为 10。

工作原理

1. 主代理分析测试用例，将任务均匀分配到 N 个子代理
2. 所有子代理同时执行，互相独立
3. 执行完成后，主代理汇总所有结果生成报告

常见问题

Q: 首次启动报错 "Config file not found"

这是正常现象，程序会自动生成默认配置文件。编辑 ~/.etestclaw/config.json 填入你的 API Key 后重新启动即可。

Q: MCP 服务器连接失败

1. 确认服务器命令/URL 配置正确
2. 检查依赖是否已安装（如 npx @playwright/mcp@latest）
3. 查看错误提示中的具体失败原因
4. 可以设置 disabled: true 临时禁用该服务器

Q: 记忆功能不生效

记忆的新增和修改在下次启动时才会加载到系统提示中。当前会话的修改不会立即生效。

Q: 上下文压缩后丢失了重要信息

可以在 /memory add 中将重要信息保存为长期记忆，或者调高 context_compression.keep 的值来保留更多消息。

Q: 如何查看所有可用技能？

在程序中输入 /skills 即可查看所有技能列表及其说明。

Q: 测试用例文件存储在哪里？

默认存储在运行 etestclaw 命令的当前目录下的 cases/ 子目录中。

附录

项目结构

etestclaw/
├── src/
│   ├── index.ts            # CLI 入口
│   ├── config.ts           # 配置管理
│   ├── llm-client.ts       # LLM API 封装
│   ├── mcp-client.ts       # MCP 客户端
│   ├── agent/              # AI Agent 核心
│   │   ├── query-engine.ts
│   │   ├── prompt-builder.ts
│   │   └── context-compressor.ts
│   ├── skills/             # 技能系统
│   │   ├── loader.ts
│   │   ├── parser.ts
│   │   ├── dispatcher.ts
│   │   └── executor.ts
│   ├── subagents/          # 子代理系统
│   ├── tools/              # 内置工具
│   │   ├── FileReadTool.ts
│   │   ├── FileWriteTool.ts
│   │   ├── BashTool.ts
│   │   ├── TestCaseTool.ts
│   │   └── MemoryTool.ts
│   ├── memory/              # 长期记忆
│   └── ui/                  # 终端 UI
├── skills/                  # 内置技能
├── cases/                   # 测试用例输出目录
└── dist/                    # 编译输出

相关链接

• npm 包：https://www.npmjs.com/package/@thinski/etestclaw
• 项目地址：https://github.com/thinski/etestclaw