# 关键字驱动脚本

**Repository Path**: QQsakura/keyword-driven-script

## Basic Information

- **Project Name**: 关键字驱动脚本
- **Description**: 关键字测试框架搭建
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-01-14
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# keyword-driven-script

关键字驱动 HTTP API 测试框架。
Excel 或 YAML 定义测试用例，反射引擎逐步骤执行。
支持 AI 自动发现与录制 API、GraphQL 识别、CSV/Excel 数据驱动。

---

## 目录

- [1. 安装与快速开始](#1-安装与快速开始)
- [2. 编写测试用例](#2-编写测试用例)
  - [2.1 Excel 格式](#21-excel-格式)
  - [2.2 YAML 格式](#22-yaml-格式)
  - [2.3 多步骤用例](#23-多步骤用例)
- [3. 执行用例](#3-执行用例)
  - [3.1 全部执行](#31-全部执行)
  - [3.2 筛选执行](#32-筛选执行)
  - [3.3 跳过报告直接执行](#33-跳过报告直接执行)
- [4. 变量与动态求值](#4-变量与动态求值)
  - [4.1 {{变量名}} 缓存引用](#41-变量名-缓存引用)
  - [4.2 内置变量](#42-内置变量)
  - [4.3 ${func(args)} 动态求值](#43-funcargs-动态求值)
  - [4.4 数据源注入（数据驱动）](#44-数据源注入数据驱动)
- [5. 断言语法](#5-断言语法)
- [6. 数据提取](#6-数据提取)
- [7. 反射关键词扩展](#7-反射关键词扩展)
- [8. 数据驱动测试](#8-数据驱动测试)
  - [8.1 CSV 数据源](#81-csv-数据源)
  - [8.2 Excel 数据源](#82-excel-数据源)
  - [8.3 变量替换优先级](#83-变量替换优先级)
- [9. AI API 发现](#9-ai-api-发现)
  - [9.1 自动发现 --ai-discover](#91-自动发现---ai-discover)
  - [9.2 交互录制 --ai-record](#92-交互录制---ai-record)
  - [9.3 GraphQL 自动识别](#93-graphql-自动识别)
- [10. 完整字段参考](#10-完整字段参考)
- [11. 配置与环境变量](#11-配置与环境变量)
- [12. 项目结构](#12-项目结构)
- [13. 设计原则](#13-设计原则)

---

## 1. 安装与快速开始

### 环境要求

- Python 3.8+
- pip

### 安装

```bash
git clone <repo-url> && cd keyword-driven-script
```

首次运行自动安装基础依赖：

```bash
python main.py --config "///"
```

AI 功能需要额外安装：

```bash
pip install anthropic playwright
python -m playwright install chromium
```

### 快速体验

```bash
# 执行全部用例（Excel + YAML）
python main.py --config "///"

# 运行单元测试
python -m pytest tests/ -v
```

---

## 2. 编写测试用例

用例文件放在 `case/` 目录下。支持 Excel 和 YAML 两种格式，可以混合使用。

### 2.1 Excel 格式

创建 `.xlsx` 文件，首行为列名，后续每行为一个步骤：

| 用例标题 | 接口         | 请求方式 | 请求参数 | 请求体                            | 请求执行后数据提取                  | 数据提取执行后断言 |
| -------- | ------------ | -------- | -------- | --------------------------------- | ----------------------------------- | ------------------ |
| 用户登录 | /api/login   | post     |          | `{"user":"admin","pass":"123"}` | token:$.data.token | 200===$.code |                    |
| 获取资料 | /api/profile | get      |          |                                   |                                     | $.data.name        |

**规则**：

- 首行必须是列名（固定），区分大小写
- 每一行是一个步骤，步骤按顺序执行
- **空 `用例标题` 的行**：自动归入上一个有标题的用例（实现多步骤）
- 列值为 `-` 或空格的将被忽略
- 列顺序不固定，可自由排列

### 2.2 YAML 格式

创建 `.yaml` 文件，使用简单格式：

```yaml
- name: 用户登录
  request:
    method: post
    url: /api/login
    json: {"user": "admin", "pass": "123"}
  assertion: 200===$.code
  extractor: token:$.data.token

- name: 获取个人资料
  request:
    method: get
    url: /api/profile
    headers:
      Authorization: "Bearer {{token}}"
  assertion: $.data.name
```

**顶层字段说明**：

| 字段                | 必填 | 说明                                                  |
| ------------------- | ---- | ----------------------------------------------------- |
| `name`            | ✅   | 用例名称                                              |
| `request`         | ✅   | 请求定义（字典），内含 method/url/json/params/headers |
| `request.method`  | ✅   | `get` / `post` / `put` / `delete`             |
| `request.url`     | ✅   | API 路径（可含 {{变量}}）                             |
| `request.json`    |      | 请求体，字典或列表                                    |
| `request.data`    |      | 请求体（备选，json 优先）                             |
| `request.params`  |      | URL 查询参数，字典                                    |
| `request.headers` |      | 请求头，字典（可含 {{变量}}）                         |
| `assertion`       |      | 断言（支持 === / != / 存在性检查）                    |
| `extractor`       |      | 数据提取（`键名:jsonpath表达式`）                   |
| `数据驱动`        |      | 数据文件路径（相对 case/），如`data/users.csv`      |

### 2.3 多步骤用例

多个步骤共用一个 `用例标题`（空标题合并）实现业务流程编排。

**Excel 多步骤**：

| 用例标题     | 接口              | 请求方式 | 请求执行后数据提取                  | 数据提取执行后断言 |
| ------------ | ----------------- | -------- | ----------------------------------- | ------------------ |
| 完整下单流程 | /api/login        | post     | token:$.data.token | 200===$.code |                    |
| _空_       | /api/cart/add     | post     |                                     | 200===$.code       |
| _空_       | /api/order/create | post     | order_id:$.data.id | 200===$.code |                    |

**YAML 多步骤**（使用 `name` 和 `extractor` 串联）：

```yaml
- name: 完整下单流程——步骤1: 登录
  request:
    method: post
    url: /api/login
    json: {"user": "admin", "pass": "123"}
  assertion: 200===$.code
  extractor: "token:$.data.token"

- name: ""
  request:
    method: post
    url: /api/order/create
    json: {"product_id": "p001", "token": "{{token}}"}
  assertion: 200===$.code
  extractor: "order_id:$.data.id"

- name: ""
  request:
    method: get
    url: /api/order/{{order_id}}/status
  assertion: paid===$.data.status
```

步骤间通过 `{{变量名}}` 传递数据，变量来自上一步的 `extractor` 提取。

---

## 3. 执行用例

### 3.1 全部执行

```bash
python main.py --config "///"
```

自动扫描 `case/` 目录下所有 `.xlsx` 和 `.yaml` 文件。

### 3.2 筛选执行

参数格式：`文件名模糊/工作簿模糊/用例名模糊/用例等级`

```bash
# 按文件名包含"登录"执行
python main.py --config "登录///"

# 按文件名+工作簿名+用例名执行
python main.py --config "case_datas/Sheet1/登录/P0"

# 多条件筛选（逗号=或）
python main.py --config "case_datas,api_test/Sheet1,Sheet2/登录,注册/P0,P1"

# 仅执行 AI 生成的用例
python main.py --config "ai_generated///"
```

规则：空段表示不限制，逗号分隔多个条件（匹配任一即通过）。

### 3.3 跳过报告直接执行

绕过 Allure 报告生成，直接使用 pytest 执行：

```bash
python test_configuration_case_executor.py
```

---

## 4. 变量与动态求值

### 4.1} 缓存引用

从运行时缓存读取值。变量通过 `extractor` 存入，也可手动写入。

```yaml
url: /api/user/{{user_id}}
json: {"auth": "{{token}}"}
```

### 4.2 内置变量

无需任何配置，在用例中直接使用：

| 变量名             | 说明                 | 示例值         |
| ------------------ | -------------------- | -------------- |
| `{{随机数}}`     | 0~100000000 随机整数 | `42315678`   |
| `{{现在时间戳}}` | 当前 Unix 时间戳     | `1719600000` |

```yaml
json: {"order_id": "ORD_{{随机数}}"}
json: {"timestamp": {{现在时间戳}}}
```

### 4.3 $ 动态求值

在字符串中嵌入函数调用，运行时替换为函数返回值。

**支持的函数**：

| 函数                    | 说明             | 示例                        |
| ----------------------- | ---------------- | --------------------------- |
| `random_number(a, b)` | 取 a~b 随机整数  | `${random_number(1,100)}` |
| `get_time()`          | 当前 Unix 时间戳 | `${get_time()}`           |
| `get_time(format)`    | 格式化时间       | `${get_time(%Y-%m-%d)}`   |
| `read_token(key)`     | 从缓存读取值     | `${read_token(token)}`    |

```yaml
json: {"price": "${random_number(10, 999)}"}
json: {"date": "${get_time(%Y-%m-%d)}"}
```

**注意**：`${}` 与 `{{}}` 可以混合使用，`${}` 优先执行。

### 4.4 数据源注入（数据驱动）

当使用数据驱动时，每行数据自动注入到步骤的 `数据源` 字段。变量替换时**优先从数据源查找**，再回退到缓存。

详见 [第 8 章：数据驱动测试](#8-数据驱动测试)。

---

## 5. 断言语法

验证响应结果。支持以下三种断言模式，可多行组合：

| 语法                          | 说明                     | 示例                      |
| ----------------------------- | ------------------------ | ------------------------- |
| `预期值 === jsonpath表达式` | 相等比较                 | `200===$.code`          |
| `预期值 !== jsonpath表达式` | 不等比较                 | `error!==$.data.status` |
| `jsonpath表达式`            | 存在性检查（有值即通过） | `$.data.id`             |

**多行断言**：换行分隔，同时检查多项：

```yaml
assertion: |
  200===$.code
  success===$.message
  $.data.id
```

**变量引用**：断言中也支持 `{{变量}}`：

```yaml
assertion: "{{期望状态}}===$.data.status"
```

---

## 6. 数据提取

从响应结果中提取数据存入缓存，供后续步骤使用。

格式：`缓存键名:jsonpath表达式`

```yaml
extractor: "token:$.data.token"
```

提取后，后续步骤通过 `{{token}}` 引用。

**多字段提取**：换行分隔

```yaml
extractor: |
  token:$.data.token
  user_id:$.data.user.id
  role:$.data.user.role
```

**特殊提取**：

- `cookie:header` — 提取 Set-Cookie
- 用例步骤中的 `身份信息` 列可以引用提取结果

---

## 7. 反射关键词扩展

添加 `key_word` 字段可绕过默认 HTTP 执行流程，调用自定义逻辑。

```yaml
- name: 特殊处理
  request:
    method: get
    url: /api/status
  key_word: "global_notification"
  assertion: 200===$.code
```

`key_word` 值对应 `privatization_func_set/privatization_func_set.py` 中的函数名。内置扩展函数：

- `global_notification` — 全局通知
- `client_online` — 客户端在线状态轮询

可通过修改 `PrivatizationFuncSet` 类添加自定义扩展函数。

---

## 8. 数据驱动测试

用 CSV 或 Excel 数据文件驱动测试用例，一行数据自动生成一个参量化用例。

### 8.1 CSV 数据源

**步骤 1**：准备数据文件 `case/data/users.csv`

```csv
username,password,expect_name
alice,pass123,Alice
bob,pass456,Bob
charlie,pass789,Charlie
```

**步骤 2**：在用例中添加 `数据驱动` 字段

```yaml
- name: 用户登录验证
  request:
    method: post
    url: /api/login
    json: {"user": "{{username}}", "pass": "{{password}}"}
  数据驱动: "data/users.csv"
  assertion: "{{expect_name}}===$.data.name"
```

**步骤 3**：执行，自动展开

```
# 3 行数据 → 自动生成 3 个参量化用例
用户登录验证_row1  → username=alice,   password=pass123, expect_name=Alice
用户登录验证_row2  → username=bob,     password=pass456, expect_name=Bob
用户登录验证_row3  → username=charlie, password=pass789, expect_name=Charlie
```

### 8.2 Excel 数据源

同样支持 `.xlsx` / `.xls` 文件，读取第一个工作表，首行为列名。

```yaml
数据驱动: "data/test_data.xlsx"
```

### 8.3 变量替换优先级

`{{变量}}` 的查找顺序：

1. **数据源**（当前步骤的 `数据源` 字段，由数据驱动自动注入）
2. **内置变量**（`{{随机数}}`、`{{现在时间戳}}`）
3. **运行时缓存**（`cache/program_data_cache`，由 extractor 存入）

这意味着数据驱动的行字段值会优先于缓存值，不会相互污染。

---

## 9. AI API 发现

### 9.1 自动发现 --ai-discover

无需手动写用例，AI 自动分析网页并生成测试用例。

```bash
export ANTHROPIC_API_KEY=sk-ant-...

python main.py --ai-discover "https://example.com"
```

工作流程：

1. Playwright 以**无头**模式打开页面
2. 自动捕获所有 XHR/Fetch 请求
3. 加载完毕后自动滚动页面，触发懒加载请求
4. Claude/GPT-4 分析 API 结构、参数依赖和业务流
5. 在 `case/ai_generated/` 目录生成 YAML 用例文件
6. 同时保存 `_analysis.json` 分析报告

自定义输出目录：

```bash
python main.py --ai-discover "https://example.com" --ai-output "case/my_project"
```

### 9.2 交互录制 --ai-record

录制用户真实操作流程，生成多步骤测试用例。

```bash
python main.py --ai-record "https://example.com"
```

工作流程：

1. Playwright 以**非无头**模式启动浏览器（用户可见）
2. 用户在页面中自由操作（点击、填写、导航等）
3. 操作完成后，在终端按 **Enter** 结束录制
4. Claude/GPT-4 分析整个会话的所有网络请求
5. 在 `case/ai_generated/` 生成 YAML 用例文件

适用场景：复杂多步骤业务、需要登录态验证、表单提交流程、文件上传。

### 9.3 GraphQL 自动识别

AI 捕获和生成阶段自动处理 GraphQL：

- **自动检测**：请求体含 `query`/`mutation` 字段且 URL 含 `graphql` 时自动标记
- **提取信息**：识别 operationType（query/mutation）和 operationName（如 `GetUser`）
- **LLM 提示**：传给 AI 分析时标注 `(GraphQL query GetUser)`，引导正确分析
- **断言适配**：生成用例时默认使用 `$.data` 存在性检查（而非 `$.code`）

手动编写 GraphQL 用例：

```yaml
- name: GraphQL 查询用户
  request:
    method: post
    url: /api/graphql
    json:
      query: "query GetUser($id: ID!) { user(id: $id) { name email } }"
      variables:
        id: "123"
  assertion: "$.data.user.name"
```

---

## 10. 完整字段参考

### Excel 列 / YAML 全格式字段

| 中文列名               | YAML 字段              | 必填 | 说明                                    |
| ---------------------- | ---------------------- | ---- | --------------------------------------- |
| `用例标题`           | `name`               | ✅   | 用例名称。空标题=合并到上一步           |
| `接口`               | `request.url`        | ✅   | API 路径或完整 URL                      |
| `请求方式`           | `request.method`     | ✅   | get/post/put/delete                     |
| `请求参数`           | `request.params`     |      | URL query 参数，JSON 字符串             |
| `请求体`             | `request.json`       |      | 请求 body，JSON 字符串                  |
| `请求执行后数据提取` | `extractor`          |      | `键名:jsonpath表达式`，提取响应到缓存 |
| `数据提取执行后断言` | `assertion`          | ✅   | 验证响应结果                            |
| `数据驱动`           | `数据驱动`           |      | 数据文件路径（相对 case/）              |
| `域名`               | `request.url` 含协议 |      | 接口的 base URL                         |
| `身份信息`           | `request.headers`    |      | 请求头，JSON 字符串或缓存提取表达式     |
| `动作描述`           | -                      |      | 步骤描述（日志显示）                    |
| `用例级别`           | -                      |      | P0/P1/P2，用于筛选                      |
| `key_word`           | `key_word`           |      | 反射关键词，调用自定义函数              |
| `执行后等待`         | -                      |      | 秒数，步骤执行后等待                    |
| `域名别名`           | -                      |      | 缓存 key，运行时读取域名                |
| `用例执行结果`       | -                      |      | 运行时写入，不手动填写                  |

### 断言表达式参考

| 表达式                   | 含义                           | 示例             |
| ------------------------ | ------------------------------ | ---------------- |
| `200===$.code`         | 响应 JSON 的 code 字段等于 200 | API 通用成功检查 |
| `success===$.message`  | message 字段等于 "success"     | 特定消息检查     |
| `$.data.id`            | data.id 存在且有值             | 存在性检查       |
| `{{变量名}}===$.field` | 预期的值来自变量               | 数据驱动 + 断言  |

### 数据提取表达式参考

| 表达式                     | 含义                  | 示例结果      |
| -------------------------- | --------------------- | ------------- |
| `token:$.data.token`     | 提取 data.token       | `"abc123"`  |
| `user_id:$.data.user.id` | 提取嵌套字段          | `42`        |
| `items:$.data.list`      | 提取整个数组          | `[1,2,3]`   |
| `cookie:header`          | 特殊：提取 Set-Cookie | `"sid=xxx"` |

---

## 11. 配置与环境变量

| 变量                       | 默认值                       | 说明                                 |
| -------------------------- | ---------------------------- | ------------------------------------ |
| `KEYWORD_SSL_VERIFY`     | `false`                    | SSL 证书验证（`true`/`false`）   |
| `ANTHROPIC_API_KEY`      | —                           | Claude API 密钥（推荐，AI 功能需要） |
| `OPENAI_API_KEY`         | —                           | GPT API 密钥（备选）                 |
| `AI_LLM_PROVIDER`        | `anthropic`                | LLM 提供商，可选`openai`           |
| `AI_LLM_MODEL`           | `claude-sonnet-4-20250514` | LLM 模型名                           |
| `AI_LLM_TIMEOUT`         | `120`                      | LLM 调用超时（秒）                   |
| `PLAYWRIGHT_HEADLESS`    | `true`                     | 是否无头浏览器                       |
| `PLAYWRIGHT_TIMEOUT`     | `30000`                    | 页面加载超时 (ms)                    |
| `AI_OUTPUT_DIR`          | `case/ai_generated/`       | AI 生成 YAML 输出目录                |
| `AI_POST_LOAD_WAIT_MS`   | `3000`                     | AI 发现时加载后等待 (ms)             |
| `AI_POST_SCROLL_WAIT_MS` | `2000`                     | AI 发现时滚动后等待 (ms)             |

---

## 12. 项目结构

```
├── main.py                              # 入口：AI 发现/录制/用例执行
├── test_configuration_case_executor.py   # pytest 测试执行器
├── AGENTS.md                            # 开发者/AI 规范
├── README.md                            # 用户文档（本文档）
│
├── base_function/                       # 核心引擎
│   ├── common_base.py     # 日志、缓存、中文→英文 key 翻译
│   ├── reflex_action.py   # 反射执行引擎（核心）
│   ├── debug_talk.py      # ${func(args)} 动态求值
│   ├── read_excel.py      # Excel 用例读取
│   ├── read_yaml.py       # YAML 用例读取
│   └── data_driver.py     # 数据驱动引擎（CSV/Excel 加载与扩展）
│
├── ai_service/                          # AI 模块
│   ├── api_discovery.py   # Playwright 捕获 + LLM 分析
│   ├── test_generator.py  # AI 生成 YAML 用例
│   ├── models.py          # 数据模型
│   └── config.py          # AI 配置
│
├── privatization_func_set/              # 反射关键词自定义函数
│   ├── privatization_func_set.py
│   └── des3.py
│
├── tests/                               # 54 个单元测试
│   └── test_core_functions.py
│
├── case/                                # 用例与数据目录
│   ├── yaml_demo.yaml                   # YAML 基础示例
│   ├── graphql_demo.yaml               # GraphQL 示例
│   ├── data_driver_demo.yaml           # 数据驱动示例
│   ├── case_datas_模板.xlsx            # Excel 模板
│   ├── 用例文件填写说明.md                # 详细填写参考
│   ├── data/                           # 数据文件目录
│   │   └── organizations.csv           # 数据驱动示例数据
│   └── ai_generated/                   # AI 生成用例 (gitignored)
│
├── cache/                               # 运行时缓存（自动清理）
│   ├── program_data_cache              # JSON 键值存储
│   └── log/
│
└── report/                              # Allure 报告输出
```

---

## 13. 设计原则

1. **Excel/YAML 即源码** — 测试用例与代码分离，非技术人员可维护
2. **反射执行** — 每步骤独立执行，通过 `key_word` 支持自定义扩展
3. **AI 辅助** — AI 只做发现和生成，不参与执行，保证稳定性
4. **按序编排** — 多步骤用例顺序执行，步骤间通过缓存传递数据
5. **数据驱动** — CSV/Excel 数据与用例分离，一行数据一个测试
6. **解耦设计** — AI 模块、数据驱动引擎、执行引擎独立，可单独使用