# midscene

**Repository Path**: rain_yang/midscene

## Basic Information

- **Project Name**: midscene
- **Description**: 基于midscene AI ui 自动化
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-02-10
- **Last Updated**: 2026-02-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Midscene自动化测试项目

本项目是基于midscene.js框架的自动化测试项目，通过自然语言指令控制浏览器执行自动化任务。

## 系统要求

- Node.js >= 14.0.0
- npm 或 yarn 包管理器
- Python >= 3.7
- 支持的操作系统：Windows 10/11, macOS 10.15+, Linux (Ubuntu 18.04+, CentOS 7+)

## 项目结构说明

```
.
├── backend               # 后端服务目录
│   ├── api               # API路由模块
│   │   ├── __init__.py
│   │   └── routes.py     # API路由定义
│   ├── __init__.py
│   └── main.py           # 后端主应用
├── frontend              # 前端管理界面目录
│   ├── src               # 前端源码目录
│   │   ├── components    # Vue组件目录
│   │   ├── App.vue       # 根组件
│   │   └── main.js       # 入口文件
│   ├── index.html        # HTML模板
│   ├── package.json      # 前端依赖配置
│   └── vite.config.js    # Vite配置文件
├── midscene_run          # 运行缓存和输出目录
│   ├── cache             # 缓存文件目录
│   ├── output            # 输出文件目录
│   └── report            # 报告文件目录
├── output                # 结果输出目录
├── yaml                  # YAML测试用例配置文件目录
│   ├── cart_demo.yaml    # 购物车操作示例
│   ├── demo.yaml         # 基础示例
│   ├── form_demo.yaml    # 表单填写示例
│   ├── navigation_demo.yaml  # 导航操作示例
│   ├── scrape_demo.yaml  # 数据抓取示例
│   └── search_demo.yaml  # 商品搜索示例
├── main.py               # 项目入口文件
├── requirements.txt      # Python依赖包列表
├── README.md
├── package.json
└── package-lock.json
```

## 快速开始

### 方法一：直接在终端运行YAML文件（无需启动后端和前端服务）

如果您只需要运行YAML测试用例，可以直接在终端中使用命令运行，无需启动后端和前端服务。

#### 安装依赖

```bash
# 全局安装（推荐）
npm i -g @midscene/cli

# 或在项目中安装
npm install
```

#### 运行YAML测试用例

安装依赖后，可以使用以下命令直接运行YAML文件：

```bash
# 运行基础示例
npx midscene run ./yaml/demo.yaml

# 运行表单填写示例
npx midscene run ./yaml/form_demo.yaml

# 运行商品搜索示例
npx midscene run ./yaml/search_demo.yaml

# 运行数据抓取示例
npx midscene run ./yaml/scrape_demo.yaml

# 运行购物车操作示例
npx midscene run ./yaml/cart_demo.yaml

# 运行导航操作示例
npx midscene run ./yaml/navigation_demo.yaml
```

### 方法二：使用Web界面运行（需要启动后端和前端服务）

#### 创建和使用Python虚拟环境（推荐）

为了隔离项目依赖，建议使用Python虚拟环境：

##### Windows系统：

```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
venv\Scripts\activate

# 安装Python依赖
pip install -r requirements.txt
```

##### macOS/Linux系统：

```bash
# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate

# 安装Python依赖
pip install -r requirements.txt
```

#### 安装Node.js依赖

所有平台都可使用以下命令安装项目依赖：

```bash
npm i -g @midscene/cli
# 或在项目中安装
npm i @midscene/cli --save-dev

#### 安装Python依赖（FastAPI后端服务）

如果你需要使用文件上传功能，需要安装Python依赖：

```bash
pip install -r requirements.txt
```

#### 安装前端依赖

进入前端目录并安装依赖：

```bash
cd frontend
npm install
```

#### 运行项目

##### 启动FastAPI后端服务

确保已激活Python虚拟环境：

```bash
# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate
```

然后启动后端服务：

```bash
python -m backend.main
```

或者使用uvicorn：

```bash
uvicorn backend.main:app --reload
```

默认服务地址为：http://localhost:8000

##### 启动前端管理界面

```bash
cd frontend
npm install
npm run dev
```

默认前端地址为：http://localhost:3000

## API接口说明

### 文件上传接口

- URL: `/upload-yaml/`
- 方法: POST
- 参数: `file` (上传的YAML文件)
- 支持格式: `.yaml`, `.yml`
- 描述: 上传YAML文件到项目[yaml](file:///D:/Code/python_code/AI/Midscene/yaml)目录

### 获取文件列表接口

- URL: `/yaml-files/`
- 方法: GET
- 描述: 列出[yaml](file:///D:/Code/python_code/AI/Midscene/yaml)目录中的所有YAML文件

### 执行测试用例接口

- URL: `/run-test/{filename}`
- 方法: POST
- 参数: `filename` (要执行的YAML文件名)
- 描述: 执行指定的YAML测试用例

### 获取任务状态接口

- URL: `/task-status/{task_id}`
- 方法: GET
- 参数: `task_id` (任务ID)
- 描述: 获取测试任务的执行状态

## 前端功能说明

前端管理界面基于Vue 3 + Vite + Element Plus技术栈构建，提供以下功能：

1. YAML文件拖拽上传
2. 文件格式和大小验证
3. YAML文件列表展示
4. 文件信息查看（文件名、大小、修改时间）
5. 执行测试用例功能
6. 实时查看任务执行状态和输出

## 后端架构说明

后端服务采用模块化设计，将不同的功能分离到不同的模块中：

1. `backend/main.py` - 应用主文件，负责创建FastAPI实例和配置中间件
2. `backend/api/routes.py` - API路由定义，包含所有接口的实现

这种结构使得代码更易于维护和扩展。

## 示例说明

### 基础示例

基础示例演示了如何使用自然语言指令控制浏览器执行简单任务。

运行命令：
```bash
npx midscene run ./yaml/demo.yaml
```

### 表单填写示例

表单填写示例演示了如何自动填写和提交表单。

运行命令：
```bash
npx midscene run ./yaml/form_demo.yaml
```

### 商品搜索示例

商品搜索示例演示了如何在电商网站上进行商品搜索操作。

运行命令：
```bash
npx midscene run ./yaml/search_demo.yaml
```

### 数据抓取示例

数据抓取示例演示了如何从网页中提取数据并保存。

运行命令：
```bash
npx midscene run ./yaml/scrape_demo.yaml
```

### 购物车操作示例

购物车操作示例演示了如何在电商网站上进行购物车相关操作。

运行命令：
```bash
npx midscene run ./yaml/cart_demo.yaml
```

### 导航操作示例

导航操作示例演示了如何在多个页面之间进行导航。

运行命令：
```bash
npx midscene run ./yaml/navigation_demo.yaml
```

## 跨平台说明

本项目具有良好的跨平台特性：

- 所有命令在 Windows (cmd, PowerShell)、Mac (Terminal) 和 Linux (bash, zsh) 上都可以正常执行
- 路径分隔符使用正斜杠 (/) 格式，兼容所有操作系统
- 配置文件格式统一，无需针对不同系统进行修改

## 常见问题

### 1. 执行测试用例时出现"系统找不到指定的文件"错误

这通常是因为Node.js环境未正确配置导致的。请确保：

1. 已安装Node.js (版本 >= 14.0.0)
2. 已在项目目录下安装@midscene/cli包：
   ```bash
   npm install @midscene/cli --save-dev
   ```

### 2. 前端界面无法连接到后端服务

请确保后端服务正在运行，并且端口没有被其他程序占用。默认后端服务端口为8000。

### 3. 上传YAML文件失败

请检查文件格式是否为.yaml或.yml，并且文件大小不超过10MB。

### 4. Python虚拟环境相关问题

#### 如何退出虚拟环境：

```bash
deactivate
```

#### 如何删除虚拟环境：

直接删除 `venv` 文件夹即可。

#### 虚拟环境的好处：

1. 隔离项目依赖，避免不同项目间的依赖冲突
2. 便于管理项目特定的Python包版本
3. 简化项目部署和环境配置