# lmtester

**Repository Path**: cy2015/lmtester

## Basic Information

- **Project Name**: lmtester
- **Description**: LMTester 是一个现代化的自动化测试平台，它利用大型语言模型（LLM）的强大能力，将自然语言编写的测试步骤转化为实际的浏览器操作。平台内置了一个基于 LangGraph 实现的 ReAct Agent，能够智能规划和执行测试任务，极大地简化了自动化用例的编写和维护过程。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: autotest
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-11
- **Last Updated**: 2025-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LMTester - AI Agent 驱动的自动化测试平台

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![Framework: FastAPI](https://img.shields.io/badge/framework-FastAPI-green.svg)](https://fastapi.tiangolo.com/)
[![Frontend: Vanilla JS](https://img.shields.io/badge/frontend-vanilla%20js-orange.svg)](https://javascript.info/)

**LMTester** 是一个现代化的自动化测试平台，它利用大型语言模型（LLM）的强大能力，将自然语言编写的测试步骤转化为实际的浏览器操作。平台内置了一个基于 **LangGraph** 实现的 ReAct Agent，能够智能规划和执行测试任务，极大地简化了自动化用例的编写和维护过程。

<div align="center">
  <p>
    <strong><a href="https://demo.lmtester.com/playback/6xvk60eq.webm" target="_blank">🎥 点击观看 LMTester 功能介绍视频</a></strong>
  </p>
  <p><em>LMTester - 下一代自动化测试</em></p>
</div>

***

## 核心功能

* **直观的 Web 界面**: 通过网页浏览器即可完成所有操作，包括任务/套件的创建、编辑、配置和运行。
* **自然语言驱动**: 用简单、高层次的自然语言（如“点击登录按钮并验证欢迎信息”）来定义测试步骤，无需编写繁琐的定位器代码。
* **智能 Agent 执行**: 内置基于 LangGraph 的 ReAct (Reason+Act) Agent，能够动态规划每一步操作，选择最合适的工具，甚至在遇到错误时尝试自我修复。
* **任务与套件管理**: 支持将测试步骤组织成独立的“任务”（Task），并可将多个任务组合成“测试套件”（Suite）进行批量执行。
* **Excel 快速导入**: 支持从 `.xlsx` 文件一键导入测试用例，自动生成多个任务 YAML 文件，大幅提升用例迁移效率。
* **实时执行日志**: 通过 WebSocket 提供实时的、彩色的执行日志，清晰展示每一步的执行过程和结果。
* **自动化测试报告**: 测试完成后，自动生成详细的 HTML、JSON 和 TXT 格式报告，包括执行摘要、步骤详情和失败截图。
* **灵活的模型配置**: 支持通过 UI 或环境变量配置不同的 LLM 模型（如 GPT-4o, Gemini 等）用于规划和工具调用。
* **Midscene.js 集成**: 深度集成强大的开源 UI 自动化工具 [Midscene.js](https://midscenejs.com/)，利用其 MCP (Model Control Protocol) 服务来驱动浏览器。

***

## 技术架构

LMTester 采用前后端分离架构，并通过子进程的方式执行测试，确保了 Web 服务和测试执行的隔离。

```mermaid
graph TD
    subgraph "用户浏览器"
        A[Web UI - index.html]
    end
    
    subgraph "LMTester 后端服务"
        B[FastAPI Server - app/main.py]
    end
    
    subgraph "测试执行环境"
        C[测试运行器 - main.py Subprocess]
        D[ReAct Agent - LangGraph]
        E[Midscene.js MCP Server]
    end
    
    subgraph "目标浏览器"
        F[Chrome/Edge with Midscene Extension]
    end
    
    A -->|发起运行请求 HTTP API| B
    B -->|启动子进程| C
    A -.->|连接日志 WebSocket| B
    B -.->|转发实时日志| A
    C -->|调用| D
    D -->|规划/执行循环| E
    E -->|控制浏览器| F
```

1.  **Web UI**: 用户通过浏览器与前端界面交互，管理测试用例并发起测试运行。
2.  **FastAPI Server**: 后端服务，负责处理 API 请求（任务/套件的CRUD）、管理配置文件、并通过 WebSocket 向前端推送实时日志。
3.  **测试运行器**: 当用户发起测试时，FastAPI 后端会启动一个独立的 Python 子进程 (`main.py`)来执行测试，避免阻塞 Web 服务。
4.  **ReAct Agent**: 在 `main.py` 进程中，LangGraph 构建的 Agent 负责解析每个高层测试步骤，通过与 LLM 多轮交互，规划出具体的 Midscene 工具调用。
5.  **Midscene.js MCP Server**: 一个由 `npx` 启动的 Node.js 服务，它接收 Agent 的工具调用指令，并将其转换为对浏览器的实际操作。
6.  **目标浏览器**: 安装了 Midscene 插件并处于“桥接模式”的浏览器，负责执行最终的 UI 操作。

***

## 典型工作流 (Typical Workflows)

LMTester 提供多种方式来创建和管理您的测试用例，以适应不同的需求。

### 方式一：通过 Web UI 创建 (推荐)
这是最直观、最推荐的使用方式，特别适合创建新测试或进行少量修改。
1.  在浏览器中打开 LMTester 界面。
2.  点击“创建新任务”或“创建新套件”。
3.  在图形化表单中填写所有信息（任务名称、步骤、变量等）。
4.  点击保存，系统将为您自动生成对应的 `.yaml` 文件。

### 方式二：通过 Excel 批量导入 (高效)
当您需要从现有的测试用例管理工具迁移大量用例时，这是最高效的方式。
1.  点击“导入 Excel”按钮将您的测试用例文件上传到平台。
2.  系统会自动为您解析 Excel 内容，并生成所有对应的任务文件。

### 方式三：(高级) 手动编辑 YAML 文件
这是一种面向高级用户的用法，适用于需要进行批量修改、与 Git 等版本控制工具集成，或进行代码审查的场景。
1.  在 `tasks/` 或 `suites/` 目录下找到对应的 `.yaml` 文件。
2.  使用文本编辑器直接修改文件内容。
3.  刷新 LMTester 网页界面，更改将自动加载。

## 安装与部署

### 前提条件 (Prerequisites)

在开始之前，请确保您的开发环境中已安装以下软件：

* **Node.js**: **必需**。平台通过 `npx` 命令启动 `Midscene.js` 服务。
    * **推荐版本**: [LTS (长期支持)](https://nodejs.org/zh-cn) 版本。
    * **验证安装**: `node -v` 和 `npm -v`。

* **Python**: **必需**。后端服务和 Agent 基于 Python。
    * **推荐版本**: 3.10 或更高版本。
    * **验证安装**: `python --version` 或 `python3 --version`。

* **Midscene Chrome 扩展**: **必需**。用于连接和控制您的桌面浏览器。
    * **安装**: 从 [Chrome 应用商店](https://chromewebstore.google.com/detail/midscenejs/gbldofcpkknbggpkmbdaefngejllnief) 安装。
    * **配置**: 打开扩展，切换到 **"Bridge Mode"**，并点击 **"Allow Connection"**。

### 安装步骤

1.  **克隆仓库**
    ```bash
    git clone -b autotest https://gitee.com/zonasw/lmtester.git
    cd lmtester
    ```

2.  **创建并激活 Python 虚拟环境**
    ```bash
    # Windows
    python -m venv venv
    .\venv\Scripts\activate

    # macOS / Linux
    python3 -m venv venv
    source venv/bin/activate
    ```

3.  **安装 Python 依赖**
    ```bash
    pip install -r requirements.txt
    ```

4.  **配置环境变量（重要）**

    这是配置 LMTester 的**推荐方法**。平台依赖以下 6 个环境变量来与 LLM 服务交互。

    | 环境变量                 | 用途说明                                                                             | 示例值                               |
    | ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------ |
    | `OPENAI_API_KEY`         | **必需**。用于 Midscene 工具执行 (如 `aiTap`) 的 API 密钥。                           | `sk-xxxxxxxxxx`                      |
    | `OPENAI_BASE_URL`        | (可选) Midscene 工具执行所指向的 API 端点。用于代理或私有化部署。                        | `https://api.openai.com/v1`          |
    | `MIDSCENE_MODEL_NAME`    | (可选) Midscene 工具执行时使用的模型名称。默认为 `google/gemini-2.5-flash-preview`。 | `google/gemini-2.5-flash-preview`    |
    | `PLANNER_OPENAI_API_KEY` | **必需**。用于 Agent 规划步骤的 LLM API 密钥。如果未提供，将回退使用 `OPENAI_API_KEY`。 | `sk-yyyyyyyyyy`                      |
    | `PLANNER_OPENAI_BASE_URL`| (可选) Planner LLM 的自定义 API 端点。如果未提供，将回退使用 `OPENAI_BASE_URL`。        | `https://api.openai.com/v1`          |
    | `PLANNER_LLM_MODEL`      | (可选) Planner 使用的 LLM 模型名称。默认为 `openai/gpt-4o`。                           | `openai/gpt-4o`                      |

    **配置示例 (macOS / Linux):**
    将以下内容添加到您的 `.zshrc`, `.bashrc`, 或 `.profile` 文件中:
    ```bash
    export OPENAI_API_KEY="sk-xxxxxxxxxx"
    export OPENAI_BASE_URL="[https://api.openai.com/v1](https://api.openai.com/v1)"
    export MIDSCENE_MODEL_NAME="google/gemini-2.5-flash-preview"
    export PLANNER_OPENAI_API_KEY="sk-yyyyyyyyyy"
    export PLANNER_OPENAI_BASE_URL="[https://api.openai.com/v1](https://api.openai.com/v1)"
    export PLANNER_LLM_MODEL="openai/gpt-4o"
    ```

    **配置示例 (Windows - Command Prompt):**
    ```cmd
    setx OPENAI_API_KEY "sk-xxxxxxxxxx"
    setx OPENAI_BASE_URL "[https://api.openai.com/v1](https://api.openai.com/v1)"
    setx MIDSCENE_MODEL_NAME "google/gemini-2.5-flash-preview"
    setx PLANNER_OPENAI_API_KEY "sk-yyyyyyyyyy"
    setx PLANNER_OPENAI_BASE_URL "[https://api.openai.com/v1](https://api.openai.com/v1)"
    setx PLANNER_LLM_MODEL "openai/gpt-4o"
    ```
    > **注意**: 在设置环境变量后，您需要重新启动您的终端或命令行窗口才能使其生效。

***

## 使用指南

### 1. 启动后端服务

在项目根目录下，确保您的虚拟环境已激活，然后运行：

```bash
uvicorn app.main:app --host 0.0.0.0 --port 8081 --reload
```

### 2. 访问 Web 界面

打开浏览器，访问 `http://localhost:8081`。

### 3. 操作流程

1.  **配置检查**:
    * 展开左侧的 **“配置”** 面板。
    * 如果您已设置环境变量，这里会显示“检测到系统环境变量”。
    * 如果您希望**临时覆盖**环境变量进行某次测试，可以在这里输入新的密钥或模型信息。这些临时值不会被保存。

2.  **创建任务 (Task)**:
    * 点击 **“创建新任务”** 按钮。
    * 在弹出的模态框中，填写任务名称、描述、可选的变量和至少一个测试步骤。
    * 点击 **“创建任务文件”**。

3.  **从 Excel 批量创建任务**:
    * **准备用例**: 准备好您的测试用例 Excel 文件。
    * **上传文件**: 回到 LMTester 界面，点击 **“导入 Excel”** 按钮，并选择您的 Excel 文件。平台会自动解析文件内容，清空所有现有任务，并为您创建全新的任务列表。

4.  **创建测试套件 (Suite)**:
    * 点击 **“创建新套件”** 按钮。
    * 填写套件信息，并按住 `Ctrl/Cmd` 选择要包含的任务。
    * 点击 **“创建套件文件”**。

5.  **运行测试**:
    * 在任务或套件列表中，点击项目右侧的 **运行按钮** (▶️)。
    * **“执行日志”** 窗口将实时显示进度。

6.  **查看报告**:
    * 测试运行结束后，日志区域下方会出现报告链接，点击即可查看。

***

## 核心概念解析

### 任务 (Task) 定义

任务是测试执行的基本单元，以 YAML 格式存储在 `tasks/` 目录下。

**示例 `login-test.yaml`:**
```yaml
task_name: 'TC-001: 用户成功登录'
description: '测试一个标准用户能否成功登录系统'
variables:
  login_url: '[https://www.saucedemo.com/](https://www.saucedemo.com/)'
  username: 'standard_user'
  password: 'secret_sauce'
high_level_steps:
- name: '导航到登录页'
  instruction: '导航到网址 {login_url}'
- name: '输入凭据'
  instruction: '在用户名输入框中输入 "{username}"，然后在密码输入框中输入 "{password}"'
- name: '点击登录'
  instruction: '点击登录按钮'
- name: '验证登录成功'
  instruction: '验证: 页面上应该能看到文本 "Products"'
```

### 测试套件 (Suite) 定义

套件用于组织和批量运行多个任务，以 YAML 格式存储在 `suites/` 目录下。

**示例 `regression-suite.yaml`:**
```yaml
suite_name: '核心功能回归测试'
description: '覆盖登录和购物流程的核心功能'
tasks:
- file: tasks/login-test.yaml
- file: tasks/add-to-cart.yaml
```

### ReAct Agent 执行流

当一个高层步骤（如 `在用户名输入框中输入 "standard_user"`）被执行时，Agent 会启动一个内部循环：  
1.  **Reason (思考)**: Agent 将当前指令、可用工具列表和历史执行记录打包成一个 Prompt，发送给 Planner LLM，询问“下一步应该调用哪个工具以及使用什么参数？”。  
2.  **Act (行动)**: Agent 解析 LLM 返回的 JSON 格式的工具调用指令，并通过 `mcp_client` 执行该工具（例如 `midscene_aiInput`）。  
3.  **Observe (观察)**: Agent 捕获工具的执行结果（成功信息或错误），并将其作为“观察”结果。  
4.  **Loop**: Agent 将这次的“观察”结果加入到历史记录中，并重复第一步，直到 LLM 认为当前高层步骤已完成并决定调用 `complete_high_level_step` 工具，或达到最大循环次数。  

***

## 项目结构

```
.
├── app/                  # FastAPI 后端应用
│   ├── api/              # API 路由
│   ├── core/             # 应用核心配置 (settings, directories)
│   ├── models/           # Pydantic 数据模型
│   ├── services/         # 业务逻辑服务
│   ├── utils/            # 工具函数 (logging, files)
│   └── main.py           # FastAPI 应用入口
├── agent/                # ReAct Agent 核心逻辑
│   ├── graph_builder.py  # LangGraph 图构建
│   ├── planner.py        # LLM 规划器 (调用LLM生成下一步计划)
│   ├── executor.py       # Midscene 工具执行器
│   └── task_runner.py    # 任务和高层步骤的执行逻辑
├── config/               # 配置文件
│   ├── prompts/          # LLM Prompt 模板
│   └── settings.yaml     # 应用设置
├── mcp_client/           # 与 Midscene MCP 服务交互的客户端
├── reporting/            # 报告生成模块
├── static/               # 前端静态文件 (JS, CSS)
├── suites/               # 测试套件 YAML 文件
├── tasks/                # 测试任务 YAML 文件
├── utils/                # 通用工具 (日志、配置加载器)
├── index.html            # 前端主页面
├── main.py               # 命令行测试执行器 (由后端启动)
└── requirements.txt      # Python 依赖
```

***

## 主要依赖

* **Backend**: [FastAPI](https://fastapi.tiangolo.com/), [Uvicorn](https://www.uvicorn.org/)
* **Agent**: [LangGraph](https://python.langchain.com/docs/langgraph)
* **LLM Interface**: [OpenAI Python SDK](https://github.com/openai/openai-python)
* **UI Automation**: [Midscene.js MCP](https://midscenejs.com/docs/mcp-service)
* **Frontend**: Vanilla JavaScript, HTML5, CSS3

---

感谢使用 LMTester！如果您有任何问题或建议，欢迎提交 Issue 或 Pull Request。