# testFramework

**Repository Path**: wolfyang888/test-framework

## Basic Information

- **Project Name**: testFramework
- **Description**: 测试的MCP框架
- **Primary Language**: Lua
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# lua-cloud 测试框架

基于 Lua 的轻量级测试框架，提供断言、测试步骤管理、代码覆盖率统计、多语言覆盖率支持、可视化报告和 MCP 服务功能。

## 架构概览

```
┌──────────────────────────────────────────────────────────────────┐
│                        Trae IDE                                  │
│               AI Agent ←─stdio JSON-RPC─→ mcp_server.lua        │
└──────────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         ▼                    ▼                    ▼
  source_analyzer      TestRunner            Coverage
  (源码分析)           (测试执行)            (覆盖率)
         │                    │                    │
         │                    ▼                    ▼
         │          coverage_adapters        merge_reports
         │          (python/cpp/java)       (多语言合并)
         │                    │                    │
         └────────────────────┼────────────────────┘
                              ▼
                    report_server (HTTP可视化)
```

## 目录结构

```
testFramework/
├── mcp_server.lua                   # MCP 协议适配层（Trae IDE 集成）
├── source_analyzer.lua              # 源码分析器（函数签名提取）
├── merge_reports.lua                # 多语言覆盖率报告合并
├── coverage_adapters/               # 多语言覆盖率适配器
│   ├── shared.lua                   # 共享工具函数
│   ├── python_adapter.lua           # Python 适配器（coverage.py）
│   ├── cpp_adapter.lua              # C/C++ 适配器（gcov/lcov）
│   └── java_adapter.lua             # Java 适配器（JaCoCo）
├── standardized_test_framework.lua  # 核心断言与步骤管理
├── testRunner.lua                   # 通用测试运行器
├── coverage.lua                     # 代码覆盖率跟踪模块
├── coverage_runner.lua              # 子进程覆盖率运行器
├── config.lua                       # 配置管理模块
├── report_server.lua                # HTTP 报告服务器
├── start_test_all.lua               # 统一测试入口
├── start_report_server.lua          # 独立报告服务器入口
├── coverage_viewer.html             # 覆盖率可视化查看页面
├── case_view.html                   # 测试案例报告页面
├── run_test.html                    # 测试执行页面
├── index.html                       # 主导航页面
├── design.md                        # 设计文档
└── README.md                        # 本文档
```

## 快速开始

### 方式一：运行测试并查看报告

```bash
lua54 test/testFramework/start_test_all.lua --coverage
```

### 方式二：多语言覆盖率

```bash
lua54 test/testFramework/start_test_all.lua --coverage --lang=python
lua54 test/testFramework/start_test_all.lua --coverage --lang=python,cpp,java
```

### 方式三：MCP Server（Trae IDE 集成）

```bash
lua54 test/testFramework/mcp_server.lua
```

在 Trae IDE 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "lua-cloud-autotest": {
      "command": "lua54",
      "args": ["test/testFramework/mcp_server.lua"],
      "cwd": "${workspaceFolder}",
      "env": {
        "LUA_PATH": "${workspaceFolder}/?.lua;${workspaceFolder}/?/init.lua;;"
      }
    }
  }
}
```

### 方式四：仅启动报告服务器

```bash
lua54 test/testFramework/start_report_server.lua
```

### 命令行参数

| 参数 | 说明 |
|------|------|
| `--only=pattern` | 仅运行匹配 pattern 的测试文件 |
| `--coverage` | 启用代码覆盖率跟踪 |
| `--timeout=ms` | 设置默认超时时间（毫秒） |
| `--timeout-pass` | 超时视为通过 |
| `--include-unsafe` | 运行黑名单中的测试脚本 |
| `--lang=python,cpp,java` | 启用多语言覆盖率收集 |

---

## MCP Tool API

MCP Server 通过 stdio JSON-RPC 2.0 协议与 Trae IDE 通信，提供以下 5 个 Tool：

| Tool | 功能 | 示例 |
|------|------|------|
| `generate_tests` | 分析源码提取上下文 / 写入测试代码 | `{"action":"analyze","source_files":["src/utils.lua"]}` |
| `run_tests` | 执行测试并返回结果 | `{"with_coverage":true}` |
| `coverage_analyze` | 分析覆盖率并返回报告 | `{"report_format":"summary"}` |
| `optimize_tests` | 根据覆盖率生成优化建议 | `{"strategy":"maximize_coverage"}` |
| `test_workflow` | 一键闭环：分析→测试→覆盖率→优化 | `{"source_files":["src/utils.lua"]}` |

### 通信协议

- **传输方式**：stdio（stdin/stdout）
- **消息格式**：JSON-RPC 2.0
- **每条消息**：一行 JSON，以 `\n` 结尾

**请求示例**：
```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_tests","arguments":{"with_coverage":true}}}
```

**响应示例**：
```json
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"success\":true,...}"}]}}
```

---

## 模块说明

### 1. mcp_server.lua — MCP 协议适配层

MCP Server 适配层，通过 stdio 传输 JSON-RPC 2.0 消息，与 Trae IDE 集成。

**核心职责**：
- 处理 `initialize` / `tools/list` / `tools/call` 等 MCP 方法
- 路由 Tool 调用到对应 Handler
- 委托业务逻辑给 testRunner / coverage / source_analyzer

### 2. source_analyzer.lua — 源码分析器

轻量级源码分析器，基于正则模式提取函数签名和导出接口。

**API**：

| 方法 | 说明 |
|------|------|
| `SourceAnalyzer.analyze_files(source_files, doc_files)` | 分析源文件，提取导出接口、依赖、文档注释 |
| `SourceAnalyzer.write_test_file(output_path, test_code)` | 将测试代码写入文件 |
| `SourceAnalyzer.infer_require_path(source_path)` | 推断 require 路径 |

### 3. testRunner.lua — 通用测试运行器

可复用于不同 Lua 项目的通用测试运行器，负责测试发现、子进程执行、超时控制、覆盖率聚合。

**新增方法**：

| 方法 | 说明 |
|------|------|
| `runner:run_single(test_file, opts)` | 执行单个测试文件并返回结果 |
| `runner:try_merge_multi_language_reports()` | 自动合并多语言覆盖率报告 |

### 4. coverage.lua — 覆盖率引擎

基于 `debug.sethook` 的行级代码覆盖率跟踪模块。

**新增方法**：

| 方法 | 说明 |
|------|------|
| `Coverage.load_from_json(json_path)` | 从 JSON 文件加载覆盖率报告 |

### 5. coverage_adapters/ — 多语言覆盖率适配器

| 适配器 | 语言 | 依赖工具 | 原理 |
|--------|------|---------|------|
| `python_adapter.lua` | Python | coverage.py | `sys.settrace()` 运行时 hook |
| `cpp_adapter.lua` | C/C++ | gcov + lcov | 编译时插桩 |
| `java_adapter.lua` | Java | JaCoCo + Maven | 字节码插桩 |
| `shared.lua` | - | - | 共享工具函数 |

### 6. merge_reports.lua — 报告合并工具

将多个语言的 `coverage_report_<lang>.json` 合并为一份 `coverage_report.json`。

```bash
lua54 test/testFramework/merge_reports.lua test/.test_all_logs
```

### 7. config.lua — 配置管理

新增 `multi_language` 配置项：

```lua
multi_language = {
    python = { enabled = false, source_dir = "src/python", test_cmd = "pytest" },
    cpp = { enabled = false, source_dir = "src/cpp", build_dir = "build" },
    java = { enabled = false, source_dir = "src/java", jacoco_csv = "target/site/jacoco/jacoco.csv" },
}
```

### 8. report_server.lua — HTTP 报告服务器

提供可视化报告查看和配置管理功能，**多语言覆盖率数据零改动即可展示**。

#### 路由列表

| 路径 | 方法 | 功能 |
|------|------|------|
| `/` | GET | 主导航页面 |
| `/api/config` | GET/POST | 获取/保存配置 |
| `/api/test_result` | GET | 获取测试结果 |
| `/api/coverage_report` | GET | 获取覆盖率报告（含多语言） |
| `/api/run_test_stream` | GET | SSE 流式执行测试 |
| `/api/health` | GET | 健康检查 |

---

## 编写测试

### 方式一：使用标准化框架

```lua
local STF = require("testFramework.standardized_test_framework")
local ok = STF.ok

ok(myModule.add(1, 2) == 3, "add(1,2) 应返回 3")
```

### 方式二：异步测试

```lua
local runner = STF.TestRunner:new()
runner:add_step("连接服务", function()
    client:connect(function()
        ok(true, "连接成功")
        runner:next_step()
    end)
end)
runner:next_step()
```

---

## 文件约定

- 测试文件放在 `test/` 目录下，以 `test_` 开头
- `test/testFramework/` 目录下的文件不会被自动发现为测试
- 测试脚本退出码 0 = 通过，非 0 = 失败
- 覆盖率数据统一使用 Format B JSON 格式

## 输出文件

运行测试后，以下文件会生成在 `test/.test_all_logs/` 目录：

| 文件 | 说明 |
|------|------|
| `test_result.json` | 测试结果报告 |
| `coverage_report.json` | 聚合覆盖率 JSON 报告（含多语言） |
| `coverage_report.txt` | 聚合覆盖率文本报告 |
| `coverage_report_python.json` | Python 覆盖率数据 |
| `coverage_report_cpp.json` | C/C++ 覆盖率数据 |
| `coverage_report_java.json` | Java 覆盖率数据 |
| `*.coverage.json` | 各测试的覆盖率数据 |
| `*.out` / `*.err` | 各测试的输出日志 |

---

## CI/CD 集成

```bash
lua54 test/testFramework/start_test_all.lua --coverage
if [ $? -eq 0 ]; then
    echo "All tests passed!"
else
    echo "Some tests failed!"
    exit 1
fi
```