# auto_script_generator

**Repository Path**: lls0229/auto_script_generator

## Basic Information

- **Project Name**: auto_script_generator
- **Description**: 基于大语言模型的测试用例 → 自动化脚本生成工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Auto Script Generator

基于多种数据源（Excel / 飞书 / 钉钉 / 企业微信）的测试用例自动生成 pytest + Selenium 测试脚本的工具。支持中文动作描述的规则映射和 AI（DeepSeek）兜底解析，提供 **Windows 桌面 GUI** 和 **命令行** 两种使用方式。

## 目录结构

```
auto_script_generator/
├── README.md
├── conftest.py                        # Pytest 全局 fixture — driver 初始化/销毁
├── pytest.ini                         # Pytest 配置（pythonpath = .）
├── run.py                             # 入口脚本：读取数据源 → 生成测试脚本
├── setup.py                           # 包安装配置

├── generator/                         # 核心生成器模块
│   ├── config.yaml                   # 全局配置（数据源 + AI 参数 + 作者）
│   ├── config.example.yaml           # 配置模板（含详细注释）
│   ├── config_validator.py           # 配置校验（字段拼写检测 + 必填项检查）
│   ├── action_mapping.py             # 中文动作 → 函数名规则映射
│   ├── ai_mapper.py                  # AI 兜底解析 + NL 场景展开 + 用例审查
│   ├── parser.py                     # 用例解析器：动作映射 + AI 兜底
│   ├── script_generator.py           # 脚本生成器（Jinja2 模板渲染）
│   └── data_sources/                 # 数据源适配层
│       ├── base.py                   # 抽象基类 + 异常定义
│       ├── excel_ds.py               # Excel（单文件 + 文件夹自动扫描）
│       ├── feishu_ds.py              # 飞书（独立表格 + 知识库 Wiki）
│       ├── dingtalk_ds.py            # 钉钉在线表格
│       └── wecom_ds.py               # 企业微信智能表格

├── gui/                               # 🆕 Windows 桌面 GUI（tkinter）
│   ├── app.py                        # GUI 入口
│   ├── main_window.py                # 主窗口（配置/获取/审查/生成）
│   └── dialogs.py                    # 对话框（数据源配置 + AI 设置）

├── generated_tests/                   # 生成的测试脚本输出（按数据源分目录）
│   ├── excel/                         # Excel 来源生成的脚本
│   ├── feishu/                        # 飞书来源生成的脚本
│   └── ...

├── keywords/                          # 关键字函数库
│   └── actions.py                     # Selenium 封装（11 个关键字函数）

├── pages/                             # 页面对象模块
│   └── login_page.py                  # 登录页 Page Object

├── templates/                         # 模板目录
│   └── test_template.py.j2           # Jinja2 测试脚本模板

├── test/                              # 单元测试
│   ├── test_feishu_utils.py           # 富文本提取 + 列映射
│   ├── test_action_mapping.py         # 动作映射完整性
│   ├── test_parser.py                 # 用例解析器
│   ├── test_excel_utils.py            # Excel 工具函数
│   ├── test_config_validator.py       # 配置校验器
│   └── test_ai_mapper.py              # AI 解析（需 API Key）

└── test_cases/                        # 本地 Excel 用例
    └── login_test.xlsx
```

## 工作流程

```
┌─────────────────────────────────────────────────┐
│ config.yaml                                     │
│   data_source.type / data_source.sources        │
└───────────────┬─────────────────────────────────┘
                ▼
┌─────────────────────────────────────────────────┐
│ data_sources/__init__.py  (工厂)                │
│   ├─ excel_ds.py    (本地 Excel)                │
│   ├─ feishu_ds.py   (飞书 API)                  │
│   ├─ dingtalk_ds.py (钉钉 API)                  │
│   └─ wecom_ds.py    (企业微信 API)               │
└───────────────┬─────────────────────────────────┘
                ▼  fetch_test_cases()
┌─────────────────────────────────────────────────┐
│ parser.py                                       │
│   ├─ action_mapping.py  (规则映射优先)           │
│   └─ ai_mapper.py       (AI 兜底)               │
└───────────────┬─────────────────────────────────┘
                ▼
┌─────────────────────────────────────────────────┐
│ script_generator.py  (Jinja2 渲染)              │
└───────────────┬─────────────────────────────────┘
                ▼
         generated_tests/{数据源}/
```

---

## 🆕 Windows 桌面 GUI

除了命令行方式，v0.2.0 起提供 **Windows 桌面图形界面**（兼容 Linux/macOS）：

```bash
# 方式一：通过 entry point 启动
auto-script-gui

# 方式二：通过模块启动
python -m gui

# 方式三：直接运行
python gui/app.py
```

### GUI 主界面功能

| 区域 | 功能 |
|------|------|
| **工具栏** | 加载/保存配置、校验、获取用例、AI 审查、生成脚本、停止 |
| **左侧面板** | ① 数据源列表（类型/标签/连接状态）- 支持添加/编辑/删除/测试连接<br>② 用例文件列表（多选 + 全选/取消）- 按数据源分组展示<br>③ 输出日志（实时着色输出） |
| **右侧面板** | ① 用例预览（Tab 页签）- 按 test_id 分组展示解析后的步骤<br>② AI 审查（Tab 页签）- 评分 + 问题分级列表（ERROR/WARN/TIP）<br>③ 生成脚本（Tab 页签）- 文件列表 + 代码预览 |

### GUI 特性

- **后台线程**：耗时的数据源连接/获取/生成操作在后台线程执行，UI 不卡顿
- **实时输出**：通过 Queue 将后台 `print` / `log` 输出实时转发到日志区
- **停止按钮**：所有耗时操作支持随时取消（`threading.Event` 信号）
- **文件筛选**：勾选左侧用例文件列表中的文件，精确控制要处理的文件子集
- **AI 审查分文件**：支持按来源文件分别审查，汇总评分
- **脚本预览**：生成后可在「生成脚本」Tab 中直接查看代码内容
- **安全防护**：输出目录选择时禁止写入系统目录，验证写入权限

### GUI 默认布局

```
┌──────────────────────────────────────────────────────────┐
│  菜单栏: [文件] [工具] [帮助]                            │
│  工具栏: [加载][保存] | [校验][获取][审查][生成][停止]   │
│           [Dry-run]        配置路径          [进度条]     │
├─────────────────────┬────────────────────────────────────┤
│ 数据源列表 (Tree)    │  Tab: [用例预览][AI审查][生成脚本] │
│ ┌──────────────┐    │  ┌────────────────────────────────┐ │
│ │类型 │标签│状态│    │  │test_id│func│page│element│...   │ │
│ ├──────────────┤    │  ├────────────────────────────────┤ │
│ │ ...          │    │  │ ...                            │ │
│ └──────────────┘    │  └────────────────────────────────┘ │
│ [添加][编辑][删除]  │                                     │
│                     │                                     │
│ 用例文件 (多选)      │                                     │
│ ┌──────────────┐    │                                     │
│ │源│文件名│路径│    │                                     │
│ ├──────────────┤    │                                     │
│ │ ...          │    │                                     │
│ └──────────────┘    │                                     │
│ [全选][取消] [刷新] │                                     │
│                     │                                     │
│ 输出目录: [______]  │                                     │
│                     │                                     │
│ 输出日志 (彩色)      │                                     │
│ ┌──────────────┐    │                                     │
│ │[STEP] ...    │    │                                     │
│ │[PASS] ...    │    │                                     │
│ └──────────────┘    │                                     │
├─────────────────────┴────────────────────────────────────┤
│ 状态栏: 就绪                     数据源: 2/2 已连接       │
└──────────────────────────────────────────────────────────┘
```

---

## 数据源配置

所有数据源通过 `generator/config.yaml` 统一配置。支持两种模式：

- **单来源模式**：设置 `data_source.type` 选择一种数据源
- **多来源模式**：设置 `data_source.sources` 数组，同时读取多个来源

### 单来源模式

```yaml
data_source:
  type: "feishu"          # excel | feishu | dingtalk | wecom
  feishu:
    app_id: "xxx"
    ...
```

### 多来源模式

```yaml
data_source:
  sources:
    - type: excel
      excel:
        file_path: "test_cases/login_test.xlsx"
    - type: feishu
      feishu:
        app_id: "xxx"
        ...
```

多来源模式下每个来源生成到独立子目录：`generated_tests/excel/`、`generated_tests/feishu/` …。同类型多个来源自动加后缀 `_2`、`_3`。

---

## 各数据源信息获取方式

### 1. Excel（本地文件）

支持两种读取模式：

#### 单文件模式（向后兼容）

```yaml
data_source:
  type: "excel"
  excel:
    file_path: "test_cases/login_test.xlsx"
```

#### 🆕 文件夹自动扫描模式（推荐）

```yaml
data_source:
  type: "excel"
  excel:
    folder_path: "test_cases"
```

- 自动扫描文件夹下所有 `.xlsx` / `.xls` 文件
- 仅读取含 `test_id` + `action`/`nl_scenario` 列的合法测试用例文件
- 自动排除 Excel 临时文件（`~$` 开头）
- 包含路径遍历防护（`os.path.realpath` + 边界检查）

> 表格列名要求：`test_id`（用例编号）、`action`（动作描述）、`element`（元素名）、`value`（输入值）、`expected`（预期结果）、`page_object`（页面对象）。**所有数据源均支持中英文列名混用**。

---

### 2. 飞书 (Feishu / Lark)

支持两种 URL 格式：独立电子表格（`/sheets/`）和知识库 Wiki 页面（`/wiki/`）。

#### 2.1 获取 App ID 和 App Secret

1. 打开 [飞书开放平台](https://open.feishu.cn/app)
2. 进入你的应用 → **凭证与基础信息**
3. 复制 **App ID** 和 **App Secret**

> 如果没有应用，先点击「创建企业自建应用」。

#### 2.2 开启权限

在飞书开放平台的应用页面：

1. 左侧菜单 → **权限管理**
2. 搜索并开启以下权限：
   - `knowledge_base:knowledge_base`（知识库，Wiki 类型表格需要）
   - `sheets:spreadsheet`（电子表格）
3. 发布新版本使权限生效

#### 2.3 获取表格 Token 和子表 ID

**独立电子表格**（URL 以 `/sheets/` 开头）：

```
https://xxx.feishu.cn/sheets/ABC123def456?sheet=ghi789
                            ^^^^^^^^^^^^^^      ^^^^^^
                            spreadsheet_token   sheet_id
```

**知识库 Wiki**（URL 以 `/wiki/` 开头）：

```
https://xxx.feishu.cn/wiki/M1gCwbVK3irAXHknLPOcrMMNnGb?sheet=UlHKiE
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^      ^^^^^^
                          wiki_token                        sheet_id
```

#### 2.4 将应用添加到知识库协作者（Wiki 类型必需）

1. 打开飞书知识库 → 右上角「…」→ **知识库设置**
2. 点击 **成员管理** → **添加协作者**
3. 搜索你的应用名称并添加（只读权限即可）

#### 2.5 配置示例

```yaml
# 独立电子表格
data_source:
  type: "feishu"
  feishu:
    app_id: "cli_xxxxxxxx"
    app_secret: "xxxxxxxx"
    spreadsheet_token: "ABC123def456"
    sheet_id: "ghi789"

# 知识库 Wiki 页面（优先使用 wiki_token）
data_source:
  type: "feishu"
  feishu:
    app_id: "cli_xxxxxxxx"
    app_secret: "xxxxxxxx"
    wiki_token: "M1gCwbVK3irAXHknLPOcrMMNnGb"
    sheet_id: "UlHKiE"
```

> **提示**：`wiki_token` 和 `spreadsheet_token` 二选一。同时填写时优先使用 `wiki_token`（代码会自动通过 Wiki API 解析为实际的文档 token）。

> **子表 ID 查询**：如果表格有多个子表（Sheet1、Sheet2…），可以在 URL 中切换子表查看 `?sheet=` 后面的值，或使用飞书 API 的 [获取表格元数据](https://open.feishu.cn/document/server-docs/docs/sheets-v3/spreadsheet/get-spreadsheet) 接口查询所有子表信息。

---

### 3. 钉钉 (DingTalk)

> **重要**：钉钉 Open API **仅支持企业空间**的文档，不支持个人空间（`utm_scene=person_space`）的文档。如文档在个人空间，请先移动到企业空间或导出为 Excel。

#### 3.1 创建应用并获取凭证

1. 打开 [钉钉开放平台](https://open.dingtalk.com/)
2. 进入 **应用开发** → 创建应用（选择**企业内部应用**）
3. 在应用详情页 → **凭证与基础信息** 获取 **AppKey** 和 **AppSecret**

#### 3.2 开启权限

应用详情 → **权限管理**，搜索并开启以下权限后**发布新版本**：

| 权限 | 用途 |
|---|---|
| `Document.Workbook.Read` | 读取钉钉表格（必需） |
| `Contact.User.Read` | 查询通讯录用户信息（用于自动获取 operatorId） |
| 企业员工手机号信息 | 如果希望通过手机号自动查用户（可选） |

#### 3.3 获取配置信息

**对于 `/spreadsheetv2/` 格式的 URL**（企业空间文档）：

```
https://alidocs.dingtalk.com/spreadsheetv2/WAX4rKeJIGg5jAbY/edit?docKey=ybEnB5jAeV2vMlP1&dentryKey=WAX4rKeJIGg5jAbY&type=s
                                                  ^^^^^^^^^^^^^^^^              ^^^^^^^^^^^^^^^^^^^^
                                                  路径 ID（不是 workbook_id）    docKey 才是 workbook_id
```

| 配置项 | 取自 | 示例值 |
|---|---|---|
| `workbook_id` | `?docKey=` 参数的值 | `ybEnB5jAeV2vMlP1` |
| `sheet_name` | 打开文档，看底部工作表标签页名称 | `Sheet1` |

> **注意**：`/spreadsheetv2/` 路径中的 ID **不是** workbook_id，URL 中 `docKey` 参数的值才是！

#### 3.4 operator_id / user_id / mobile 三选一

钉钉表格 API 要求 `operatorId`（即操作人的 unionId）。代码支持三种方式自动获取，优先级从高到低：

| 配置项 | 说明 | 获取方式 |
|---|---|---|
| `operator_id` | unionId（最高优先级）| 钉钉管理后台 → 通讯录 → 成员详情 |
| `user_id` | userId | 代码自动调 API 查 unionId |
| `mobile` | 手机号 | 代码自动：手机号 → userId → unionId |

#### 3.5 配置示例

```yaml
data_source:
  type: "dingtalk"
  dingtalk:
    app_key: "dingxxxxxxxx"
    app_secret: "xxxxxxxx"
    workbook_id: "ybEnB5jAeV2vMlP1"  # URL 中 docKey 的值
    sheet_name: "Sheet1"
    # 以下三选一
    operator_id: ""                   # unionId（已知时直接填）
    user_id: ""                       # userId（会自动查 unionId）
    mobile: ""                        # 手机号（会自动查 userId → unionId）
```

#### 3.6 常见问题

| 错误 | 原因 | 解决 |
|---|---|---|
| `InvalidVersion` | API 路径错误 | 路径应为 `/v1.0/doc/workbooks/`（注意 `doc` 前缀） |
| `uuid not exist` | workbook_id 用了路径中的 ID | 改用 URL 中 `docKey` 参数的值 |
| `forbidden.acrossOrg` | 文档在个人空间 | 文档移至企业空间或导出 Excel |
| `operator has no permission` | 用户无文档权限 | 将用户添加为文档协作者 |
| `MissingoperatorId` | 未配置 operatorId | 填 `user_id` 或 `mobile`，代码自动查 |

---

### 4. 企业微信 (WeCom) ⚠ 暂不可用

> **当前状态**：企微自建应用调用文档 API 需要满足以下前置条件，目前暂无法配置，代码已注释。满足条件后取消注释即可启用。

#### 前置阻塞条件

企业微信自建应用调用 API 需完成以下配置（缺一不可）：

| 序号 | 要求 | 阻塞原因 |
|---|---|---|
| 1 | **设置可信域名** | 需要拥有一个已备案的域名 |
| 2 | **设置接收消息服务器 URL** | 需要部署一个回调服务（公网 HTTPS 可达） |
| 3 | **配置企业可信 IP** | 需要固定公网 IP |

企微管理后台逻辑：**配置企业可信 IP 之前，必须先完成可信域名或接收消息服务器 URL 的配置**。个人开发者 / 本地开发环境通常不具备固定公网 IP 和已备案域名，因此企微表格 API 暂不可用。

#### 解决方案

满足上述条件后，按以下步骤启用：

1. 取消 `generator/data_sources/__init__.py` 中 `wecom` 相关代码的注释
2. 取消 `generator/config.yaml` 中 `wecom` 配置段的注释
3. 按下方 URL 格式填写配置

#### URL 格式参考

支持两种表格类型：**普通表格**（`/sheet/`）和 **智能表格**（`/smartsheet/`）。

**普通表格**：

```
https://doc.weixin.qq.com/sheet/e3_Ae4AAAYpANwCNygecbXrLTvaaNNXl?tab=BB08J2
                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^      ^^^^^^
                               doc_id                                sheet_id
```

**智能表格**：

```
https://doc.weixin.qq.com/smartsheet/s3_xxx?sheet=yyy
                                    ^^^^^^       ^^^
                                    doc_id       sheet_id
```

#### 配置示例（取消注释后填入）

```yaml
# 普通表格
data_source:
  type: "wecom"
  wecom:
    corp_id: "wwxxxxxxxxxxxx"
    corp_secret: "xxxxxxxx"
    doc_id: "e3_Ae4AAAYpANwCNygecbXrLTvaaNNXl"
    sheet_id: "BB08J2"
    doc_type: "sheet"
```

---

## 生成的测试脚本注释

每个生成的测试文件顶部自动包含注释块：

```python
"""
作者: lls0229
生成时间: 2026-06-10 14:12:00
测试模块: login
数据源: feishu
"""
```

作者信息在 `config.yaml` 中配置：

```yaml
author: "lls0229"
```

---

## 环境要求

- Python 3.9+
- Chrome 浏览器 + ChromeDriver（需在 PATH 中）

## 运行测试

```bash
# 运行全部单元测试（无需网络 / API Key / 浏览器）
pytest test/ -v

# 单独运行某个测试模块
pytest test/test_parser.py -v
pytest test/test_action_mapping.py -v
pytest test/test_config_validator.py -v
```

> 单元测试覆盖纯逻辑模块（动作映射、用例解析、富文本提取、列名映射、配置校验），无外部依赖。

## 安装

```bash
# 安装依赖（含 GUI 所需的 tkinter，Windows Python 默认包含）
pip install -e .

# 或者手动安装
pip install pandas openpyxl selenium jinja2 openai pyyaml tenacity pytest requests
```

安装后可通过命令行直接启动：

```bash
auto-script-gen          # 命令行模式
auto-script-gui          # 🆕 GUI 桌面模式
```

> `auto-script-gui` 在 Linux 下需额外安装 `python3-tk`：`sudo apt install python3-tk`（Ubuntu/Debian）或 `sudo yum install python3-tkinter`（RHEL/CentOS）。

## 配置 DeepSeek API Key

```bash
# Windows (CMD)
set DEEPSEEK_API_KEY=your-deepseek-api-key

# Windows (PowerShell)
$env:DEEPSEEK_API_KEY="your-deepseek-api-key"

# Linux / macOS
export DEEPSEEK_API_KEY="your-deepseek-api-key"
```

## 运行

```bash
# ── 命令行模式 ──
# 1. 编辑 generator/config.yaml，选择数据源并填写凭证
# 2. 生成测试脚本
python run.py

# 3. 执行生成的测试（按数据源筛选）
pytest generated_tests/feishu/ -v
pytest generated_tests/excel/ -v

# 4. 执行所有测试
pytest generated_tests/ -v

# ── 🆕 GUI 桌面模式 ──
auto-script-gui              # 通过 entry point
python -m gui                # 通过模块
python gui/app.py            # 直接运行
```

### CLI 参数

```bash
python run.py --help                        # 查看帮助
python run.py --config prod.yaml            # 指定配置文件
python run.py --source excel,feishu         # 只处理指定数据源（逗号分隔）
python run.py --output-dir ./my_tests       # 自定义输出目录
python run.py --dry-run                     # 试运行：读取 + 解析 + 预览，不写文件
python run.py --validate                    # 仅校验：只测试数据源连接正常与否
python run.py --review                      # AI 审查：生成脚本前审查用例完整性
```

> 不带参数时行为与之前完全一致（使用默认 `generator/config.yaml`）。

### AI 审查模式

`--review` 参数在生成测试脚本前，由 AI 自动审查全部用例并输出报告：

- **评分**（0-100）：综合评估用例覆盖质量
- **问题分级**：ERROR（必须修复）/ WARNING（建议修复）/ TIP（锦上添花）
- **检查维度**：断言缺失、边界覆盖不足、元素名不一致、预期结果可疑、安全测试缺失

```bash
python run.py --review --dry-run   # 仅审查不生成（建议先用这个预览）
python run.py --review             # 审查后正式生成
```

> 需要 `DEEPSEEK_API_KEY` 环境变量（或 `config.yaml` 中的 `ai_config.api_key`）。

### 配置校验

启动时自动校验 `config.yaml`：
- **ERROR**（阻止运行）：缺少必填字段、不支持的数据源类型、token/凭证缺失
- **WARN**（提示建议）：字段拼写错误（如 `filepath` → 建议 `file_path`）、未配置 AI 等

拼写错误会给出最接近的正确字段名，方便快速定位。

## CI/CD（Gitee Go）

项目包含 Gitee Go 流水线配置 `.workflow/ci-pipeline.yml`，每次 push 自动运行单元测试和试运行。

### 启用步骤

1. 打开仓库 → 顶部 **"服务"** → **"Gitee Go"**
2. 新建流水线 → 选择已有的 `.workflow/ci-pipeline.yml`

### 流水线内容

| 步骤 | 说明 |
|------|------|
| pip install | 安装项目依赖 |
| 创建测试配置 | 从 `config.example.yaml` 复制（`config.yaml` 含凭证不入库） |
| pytest | 运行 94 个单元测试（跳过需 API Key 的 `test_ai_mapper.py`） |
| --dry-run | 试运行：读取用例 + 解析 + 预览 |
| --validate | 校验数据源连接 |

### Gitee Go YAML 编写注意事项

Gitee Go 的格式与 GitHub Actions / GitLab CI 不同，以下是踩坑记录：

- **配置文件位置**：必须放在 `.workflow/` 目录下，不能放在仓库根目录
- **stage 是扁平结构**：`stages` 下直接是 `- name: xxx`，**不需要** `- stage:` 嵌套包裹
- **步骤类型**：Python 单元测试用 `ut@python`，**不是** `build@python`
- **stage 必填字段**：`strategy: naturally` 和 `trigger: auto` 缺一不可
- **displayName 限制**：不支持 `+` 等特殊字符，只允许中英文和数字
- **pip 缓存**：Gitee Go 各 stage 之间不共享环境，每个 stage 需独立 `pip install`

> 如果通过图形视图创建了流水线，要先删除再用代码视图导入，避免图形视图覆盖 YAML 文件。

## 测试用例表格格式

无论使用哪种数据源，表格列结构需保持一致（支持中英文列名）：

| 列名（英文） | 列名（中文） | 说明 | 示例 |
|---|---|---|---|
| `test_id` | 用例编号 | 唯一标识 | `Login_front_001` |
| `action` | 动作/操作 | 中文操作描述 | `打开网址`、`输入文本`、`点击按钮` |
| `element` | 元素名 | 页面对象属性名 | `username_input` |
| `value` | 输入值 | 输入文本内容或选项 | `admin` |
| `expected` | 预期结果 | 断言文本或 URL | `密码错误` |
| `page_object` | 页面对象 | 页面类名 | `Login` |

| `nl_scenario` | 场景描述 | AI 展开的自然语言描述（可选） | `用admin/123456登录，应跳转首页` |

> **两种编写方式可混用**：`nl_scenario` 有值时 AI 自动拆解该行为多步骤（忽略同行 action/element/value/expected），`nl_scenario` 为空时走传统逐行编写。

### 支持的动作

| 中文描述 | 关键字函数 | 说明 |
|---|---|---|
| 打开网址 | `open_page` | 导航到指定 URL |
| 页面导航 / 导航到 | `navigate` | 同 `open_page` |
| 输入文本 | `input_text` | 等待元素可见后清空并输入 |
| 点击按钮 / 点击元素 | `click_button` | 等待可点击后 JS 点击 |
| 选择下拉 / 下拉选择 | `select_option` | 按可见文本选择下拉选项 |
| 等待元素可见 / 等待元素 | `wait_visible` | 等待元素出现在 DOM 且可见 |
| 鼠标悬停 / 悬停 | `hover` | ActionChains 悬停 |
| 滚动到元素 / 滚动到 | `scroll_to` | JS scrollIntoView |
| 断言文本相等 | `assert_text_equal` | 断言元素文本等于预期值 |
| 断言页面包含 | `assert_url_contains` | 断言 URL 包含预期子串 |
| 断言元素可见 / 验证元素可见 | `assert_element_visible` | 断言元素在页面上可见 |

> 规则匹配不到的动作会自动通过 AI（DeepSeek）解析，支持更灵活的自然语言描述。

### 自然语言场景展开（AI）

在 `nl_scenario` 列中可以用一句话描述整个测试场景，AI 自动拆解为完整的操作步骤。适合快速编写常见场景，减少逐行填写的工作量。

**示例**：

```
nl_scenario: 用 admin / 123456 登录 https://xxx/login，应该跳转到用户首页
test_id: NL_Login_001
```

AI 自动展开为：

```
open_page          → https://xxx/login
input_text         → username_input = admin
input_text         → password_input = 123456
click_button       → login_button
assert_url_contains → /index.html
```

**前提条件**：

- 已设置 `DEEPSEEK_API_KEY` 环境变量（AI 展开依赖 DeepSeek）
- 表格中包含 `nl_scenario` 列（支持列名：`nl_scenario` / `场景描述` / `自然语言描述` / `nl描述`）
- AI 会自动收集同批次中定义的页面对象和元素名，使拆解结果更准确

**注意事项**：

- 描述中包含 URL 时 AI 自动提取并在第一步 `open_page`
- `assert_text_equal` / `assert_element_visible` 内部已含等待逻辑，AI 不会在它们前面插入多余的 `wait_visible`
- "账号xxx"、"密码xxx" 等带前缀的描述，AI 会自动剥离前缀只保留纯值
- AI 调用失败时该行静默跳过，不影响传统行解析

---

## 更新日志

### v0.3.1 (2026-06-28) — AI 防幻觉

**🔒 一致性锁（AI Cache）**
- 新增 `generator/ai_cache.py`：SHA256 哈希 → JSON 持久化缓存
- 同一输入永远返回同一输出，不再重复调 API（首次结果写入 `.ai_cache.json`）
- 覆盖全部 AI 调用场景：动作解析 / 场景展开 / 用例审查 / 元素定位

**✅ 结果校验**
- XPath 存在性 + 可见性 + 标签类型三重验证（`verify_locator()`）
- `expand_scenario`：过滤非法元素名（注入攻击防护）、参数长度上限
- `review_test_suite`：score 0-100 边界修正、severity 值修正

**📋 审计日志**
- JSONL 格式记录每次 AI 调用：时间/输入/输出/耗时/来源（cache 或 api）
- 自动轮转保留最新 1000 条，写入 `generator/ai_audit.log`

### v0.3.0 (2026-06-28) — AI 元素定位

**🤖 AI 元素定位**
- **无需 Page Object 即可运行**：`element` 列为空时，AI 自动分析页面 DOM 定位元素
- 新增 `generator/ai_locator.py`：JS 注入提取 DOM 摘要 → DeepSeek 匹配元素 → 返回 XPath
- URL 级 DOM 缓存（5 分钟），同页面多步骤复用，减少 API 调用
- 7 个关键字函数支持 AI 兜底：`input_text` / `click_button` / `select_option` / `wait_visible` / `hover` / `scroll_to` / `assert_element_visible` / `assert_text_equal`
- 向后兼容：有 `element` 值时走 Page Object；无值时走 AI 定位

**📝 Excel 用法变化**
- 旧：`element=username_input`（必须填）
- 新：`element=留空` → AI 根据 `action` + `value` 自动匹配元素

### v0.2.0 (2026-06-18) — Windows GUI 版本

**🆕 新增**
- **Windows 桌面 GUI**（`gui/` 模块，基于 tkinter）：可视化配置、获取用例、AI 审查、生成脚本
- **Excel 文件夹自动扫描**：支持 `folder_path` 配置，自动扫描目录下所有合法测试用例文件
- **数据源多选/筛选**：GUI 中可按文件粒度勾选要处理的用例子集
- **AI 测试用例完整性审查**：`--review` 参数（CLI）和 GUI Tab，AI 自动审查并打分
- **NL 场景展开优化**：自动剥离"账号/密码"前缀、去冗余 `wait_visible`
- **生成脚本源文件追溯**：模板中记录来源文件信息
- **`setup.py` entry points**：`auto-script-gen`（CLI）和 `auto-script-gui`（GUI）

**🔒 安全增强**
- Excel 文件夹扫描增加路径遍历防护（`os.path.realpath` + 边界检查）
- AI 参数验证：防止超长输入 DoS、非法元素名注入
- 自然语言输入长度限制（500 字符）
- 输出目录安全验证：禁止系统目录写入
- 配置调试日志脱敏（密钥/Token/手机号等）

**🧵 线程安全**
- AI 客户端初始化加线程锁（`threading.Lock`），防止多线程竞态
- GUI 所有耗时操作在后台线程执行，UI 通过 Queue 轮询更新
- 解析器支持外部取消信号（`cancel_event`），停止按钮即时响应

**🔧 改进**
- 统一 LLM 调用实现（`_call_llm_internal`），消除 `ai_mapper.py` 中 ~50 行重复代码
- `parser.py` 增强异常处理：区分 `FileNotFoundError` / `UnicodeDecodeError` / `IOError`
- `config_validator.py` 支持 `folder_path` 字段校验
- 配置支持旧版 `file_path` → 新版 `folder_path` 自动迁移提示
- `generator/__init__.py` 添加版本号（`__version__ = "0.2.0"`）

**📝 文档**
- 补充 `docs/AI_INTEGRATION_PLAN.md`（6 个 AI 扩展方向规划）
- 代码审查报告 + 修复日志（`docs/CODE_REVIEW_REPORT_2026-06-18.md`、`docs/FIX_LOG_2026-06-18.md`）