Metadata-Version: 2.3
Name: graphql-to-httprunner
Version: 1.1.0
Summary: Automatically generate HttpRunner test cases based on GraphQL Schema
License: MIT
Keywords: graphql,httprunner,api,automation,test
Author: Devin
Author-email: zhangchuzhao@dingtalk.com
Requires-Python: >=3.5
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: pyyaml (==5.1.2)
Requires-Dist: requests (==2.22.0)
Description-Content-Type: text/markdown

# GraphQL to HttpRunner

一个基于GraphQL Schema自动生成HttpRunner测试用例的自动化工具。

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

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

### 核心模块
- `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                      # 兼容旧式安装的配置文件
├── MANIFEST.in                   # 指定打包时要包含和排查的文件
└── README.md                     # 项目说明文档
```

## 三、安装方法

### 3.1 使用pip安装（推荐）
```bash
# 从PIPY仓库安装
pip install graphql-to-httprunner

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

### 3.2 开发模式安装
```bash
# 从本地源码安装
pip install .

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

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

## 四、使用方法

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

安装后可以直接使用`gpl2hrun`或`gpl2case`或`graphql2httprunner`或`graphql2testcase`命令：

```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 源码执行使用方式

如果没有通过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 参数说明
```bash
gpl2hrun -h

usage: gpl2hrun [-h] (-f SCHEMA_FILE | -i INTROSPECTION_URL) (-t | -q) [-o OUTPUT] [-u BASE_URL] [-d MAX_DEPTH] [--api] [--required]

将GraphQL Schema转换为HttpRunner测试用例或查询语句

optional arguments:
  -h, --help
  -f SCHEMA_FILE, --schema-file SCHEMA_FILE
  -i INTROSPECTION_URL, --introspection-url INTROSPECTION_URL
  -t, --testcases
  -q, --queries
  -o OUTPUT, --output OUTPUT
  -u BASE_URL, --base-url BASE_URL
  -d MAX_DEPTH, --max-depth MAX_DEPTH
  --api
  --required
```

- `-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
```

### 4.6 打包上传PyPI
```bash
# 打标签（轻量或附注）
git tag v1.0.0 或 git tag -a v1.0.0 -m "发布正式版本 v1.0.0"
# 推送标签(单个或所有)
git push v1.0.0 或 git push --tags
# 本地配置pyproject.toml和pypi token信息
poetry config pypi-token xxx
# 编译打包
poetry build
# 上传发布
poetry publish
```


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