# GraphQL to HttpRunner
实现了一个基于GraphQL Schema自动生成HttpRunner YAML格式测试用例的Python工具。

## 一、主要功能
1. 解析GraphQL Schema文件，提取查询操作和类型定义
2. 通过内省查询(Introspection Query)自动获取GraphQL Schema
3. 为每个查询操作生成对应的HttpRunner测试用例
4. 自动构建GraphQL查询语句，包括字段选择和参数处理
5. 生成合适的测试断言
6. 直接生成GraphQL查询语句列表，方便开发调试
7. 支持API层和用例层测试用例的生成，满足HttpRunner分层测试需求

## 二、代码结构
项目采用模块化设计，主要包含以下文件：

### 核心模块
- `graphql_to_httprunner/models.py`: 数据模型模块，定义了GraphQL Schema的核心数据结构
  - `GraphQLType`: 表示GraphQL类型，包含字段和实现接口信息
  - `GraphQLSchema`: 表示整个Schema，包含类型、接口和根字段

- `graphql_to_httprunner/parser.py`: 解析器模块，负责解析GraphQL Schema文件
  - `GraphQLSchemaParser`: 解析GraphQL Schema的内容，提取类型、接口、枚举等信息

- `graphql_to_httprunner/introspection.py`: 内省查询模块，通过内省查询获取GraphQL Schema
  - `fetch_schema_from_introspection`: 向GraphQL服务发送内省查询请求，获取Schema

- `graphql_to_httprunner/generator.py`: 生成器模块，负责生成HttpRunner测试用例
  - `HttpRunnerTestCaseGenerator`: 根据Schema生成HttpRunner YAML测试用例，同时支持生成API层和用例层测试用例

- `graphql_to_httprunner/query_generator.py`: 查询语句生成器模块，负责生成GraphQL查询语句列表
  - `GraphQLQueryGenerator`: 根据Schema生成GraphQL查询语句

### 工具模块
- `graphql_to_httprunner/main.py`: 程序入口模块，提供命令行界面，协调调用解析器和生成器
- `graphql_to_httprunner/__init__.py`: 包初始化文件，提供模块导入接口
- `__main__.py`: 项目根目录入口点，允许直接运行项目

### 项目结构
```
graphql-schema-to-httprunner/
├── graphql_to_httprunner/        # 主包目录
│   ├── __main__.py               # 主包目录入口点
│   ├── __init__.py               # 包初始化文件
│   ├── models.py                 # 数据模型模块
│   ├── parser.py                 # 解析器模块
│   ├── introspection.py          # 内省查询模块
│   ├── generator.py              # 生成器模块
│   ├── query_generator.py        # 查询语句生成器模块
│   └── main.py                   # 命令行入口模块
├── __main__.py                   # 项目根目录入口点
├── pyproject.toml                # 项目配置文件
├── setup.py                      # 兼容旧式安装的配置文件
└── README.md                     # 项目说明文档
```

## 三、安装方法

### 3.1 使用pip安装（推荐）
```bash
# 从本地源码安装
pip install .

# 或者从Git仓库安装
pip install git+https://git.umlife.net/zhangchuzhao/graphql-schema-to-httprunner.git
```

### 3.2 开发模式安装
```bash
# 使用pip开发模式安装
pip install -e .

# 或者使用poetry安装
poetry install
```

## 四、使用方法

### 4.1 命令行使用（推荐）

安装后可以直接使用`gpl2hrun`命令：

```bash
# 基于schema.graphql文件生成HttpRunner用例层测试用例
gpl2hrun -f schema.graphql -t -o testcases -u http://your-api-url -d 2

# 基于内省查询URL生成HttpRunner用例层测试用例
gpl2hrun -i http://your-graphql-server/graphql -t -o testcases -u http://your-api-url -d 2

# 基于schema.graphql文件生成HttpRunner API层测试用例
gpl2hrun -f schema.graphql -t --api -o api -u http://your-api-url -d 2

# 基于内省查询URL生成HttpRunner API层测试用例
gpl2hrun -i http://your-graphql-server/graphql -t --api -o api -u http://your-api-url -d 2

# 基于schema.graphql文件生成HttpRunner用例层测试用例（仅包含必选参数）
gpl2hrun -f schema.graphql -t -o testcases --required -u http://your-api-url -d 2

# 基于schema.graphql文件生成HttpRunner API层测试用例（仅包含必选参数）
gpl2hrun -f schema.graphql -t --api -o api --required -u http://your-api-url -d 2

# 基于schema.graphql文件生成GraphQL查询语句
gpl2hrun -f schema.graphql -q -o queries.yml -d 2

# 基于内省查询URL生成GraphQL查询语句
gpl2hrun -i http://your-graphql-server/graphql -q -o queries.yml -d 2
```

### 4.2 未安装gpl2hrun命令的使用方式

如果没有通过pip安装，或者需要直接运行源码，可以使用以下方式：

```bash
# 使用根目录的__main__.py入口点（省略模块/指定模块）
python . -f schema.graphql -t -o testcases -u http://your-api-url -d 2
python __main__.py -f schema.graphql -t -o testcases -u http://your-api-url -d 2

# 使用包目录__main__.py入口点
python -m graphql_to_httprunner -f schema.graphql -t -o testcases -u http://your-api-url -d 2

# 使用graphql_to_httprunner/main.py入口点
python -m graphql_to_httprunner.main -f schema.graphql -t -o testcases -u http://your-api-url -d 2
```

### 4.3 模块导入方式使用

```python
from graphql_to_httprunner.parser import GraphQLSchemaParser
from graphql_to_httprunner.generator import HttpRunnerTestCaseGenerator

# 解析GraphQL Schema文件
with open('schema.graphql', 'r') as f:
    schema_content = f.read()
    
parser = GraphQLSchemaParser(schema_content)
schema = parser.parse()

# 生成测试用例
generator = HttpRunnerTestCaseGenerator(schema, base_url="http://your-api-url")
testcase_count = generator.generate_test_cases("testcases")
print(f"已生成{testcase_count}个测试用例")
```

### 4.4 参数说明
- `-f, --schema-file`: GraphQL Schema文件路径
- `-i, --introspection-url`: GraphQL内省查询URL，如 http://localhost:9527/graphql
- `-t, --testcases`: 生成HttpRunner测试用例
- `-q, --queries`: 生成GraphQL查询语句列表
- `--api`: 生成API层测试用例而非用例层测试用例（仅当使用 `-t` 时有效）
- `--required`: 只包含必选参数，默认情况下包含所有参数（仅当使用 `-t` 时有效）
- `-o, --output`: 输出目录路径（生成测试用例时）或文件路径（生成查询语句时）
- `-u, --base-url`: GraphQL API基础URL，默认为'http://localhost:8888'
- `-d, --max-depth`: GraphQL查询嵌套的最大深度，默认为2

> 注意：
> - `-f` 和 `-i` 是互斥参数，只能二选一使用
> - `-t` 和 `-q` 是互斥参数，只能二选一使用
> - 如果使用 `-t` 选项，则 `-o` 参数指定输出目录；如果使用 `-q` 选项，则 `-o` 参数指定输出文件路径
> - `--api` 参数仅在 `-t` 参数存在时有效，用于指定生成API层测试用例
> - `--required` 参数仅在 `-t` 参数存在时有效，用于指定只包含必选参数

### 4.5 执行HttpRunner测试用例
```bash
# 运行用例层测试用例
hrun testcases
# 运行API层测试用例
hrun api
```

## 五、注意事项
1. 使用$$来转义$符号，以避免与HttpRunner变量语法冲突
2. HttpRunner接口响应内容引用变量约定为content
3. 内省查询需要目标GraphQL服务支持标准的内省查询API
4. 如果内省查询URL与基础URL不同，需要同时指定 `-i` 和 `-u` 参数
5. 生成的查询语句列表以YAML格式存储，键为操作名称，值为对应的查询语句