# GraphQL to HttpRunner

<div align="center">
  <img src="https://img.shields.io/pypi/v/graphql-to-httprunner.svg" alt="Version">
  <img src="https://img.shields.io/badge/python-3-blue" alt="Python">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  <img src="https://img.shields.io/badge/core-简单强大-orange" alt="Core">

  **基于 GraphQL Schema 自动生成 HttpRunner 测试用例的强大工具**

  [快速开始](#快速开始) • [完整文档](docs/) • [特色功能](#核心特色) • [示例](#使用示例)

</div>

---

## 简介

GraphQL to HttpRunner 是一个自动化测试工具，能够从 GraphQL Schema 或通过内省查询自动生成 HttpRunner 测试用例，大幅提升 GraphQL API 测试效率。

### 一句话概括

> 从 GraphQL Schema 到可运行的测试用例，只需一行命令。

## 核心特色

### 🚀 自动化生成
- **一键生成**：从 Schema 文件或 GraphQL 服务自动生成完整测试用例
- **智能查询**：自动构建 GraphQL 查询语句，包括字段、参数和默认值
- **分层测试**：支持 API 层和用例层分离，符合最佳实践

### 🔍 差异对比
- **详细对比**：精确识别 API 变更（新增、删除、修改）
- **多格式报告**：支持 Markdown、HTML 格式差异报告
- **自动备份**：生成新查询前自动备份旧版本

### ⚡ 智能更新
- **自动维护**：根据 API 变更自动更新测试用例
- **批量处理**：支持多项目批量生成和更新
- **自定义生成**：支持单个查询的自定义生成，按需获取

### 🛠️ 灵活配置
- **参数控制**：支持全量参数或仅必选参数模式
- **深度调节**：可调整查询嵌套深度，适应不同复杂度
- **模块化分类**：支持自定义模块分类和跨层级检索定位

### 🔗 无缝集成
- **CI/CD**：完美集成 Jenkins、GitLab CI 等持续集成平台
- **API变更监测**：集成到CI定时生成API变更差异报告
- **自动化维护**：集成到CI定时自动化维护用例和执行用例
- **可扩展**：提供 Python API，支持二次开发

## 快速开始

### 安装

```bash
pip install graphql-to-httprunner
```

### 3 分钟完成第一个测试

**步骤 1**: 从 GraphQL 服务生成测试用例

```bash
gpl2hrun -i http://localhost:8888/graphql -t
```

**步骤 2**: 运行测试

```bash
pip install httprunner  # 如果未安装
hrun testcases
```

**步骤 3**：查看测试报告，完成！ 🎉

### 常用场景

#### 场景 1：从 Schema 文件生成

```bash
gpl2hrun -f schema.graphql -t -u http://your-api-url
```

#### 场景 2：生成查询语句并生成API变更报告

```bash
gpl2hrun -f schema.graphql -q --report html
```

#### 场景 3：批量处理多个项目

```bash
gpl2hrun -b config.csv -t
```

#### 场景 4：自动更新测试用例

```bash
gpl2hrun -b config.csv -a
```

> 💡 更多用法请查看 [快速入门指南](docs/quickstart.md)

## 使用示例

### 生成测试用例

```bash
# 从内省查询生成
gpl2hrun -i http://localhost:8888/graphql -t

# 从 Schema 文件生成
gpl2hrun -f schema.graphql -t

# 生成 API 层测试用例
gpl2hrun -i http://localhost:8888/graphql -t --api -o api

# 只包含必选参数
gpl2hrun -f schema.graphql -t --required
```

### 生成查询语句

```bash
# 生成查询语句列表
gpl2hrun -f schema.graphql -q

# 生成并对比差异
gpl2hrun -f schema.graphql -q --report both

# 批量生成多个项目
gpl2hrun -b config.csv -q
```

### 批处理模式

创建 `config.csv`:

```csv
project_name,introspection_url,output,base_url,max_depth,required,api,is_cite,is_skip,offline
project1,http://api1.com/graphql,project1,http://api1.com,2,false,false,false,false,false
project2,http://api2.com/graphql,project2,http://api2.com,3,true,true,false,false,false
```

批量生成：

```bash
gpl2hrun -b config.csv -t
```

### 代码集成

```python
from graphql_to_httprunner.introspection import fetch_schema_from_introspection
from graphql_to_httprunner.generator import HttpRunnerTestCaseGenerator

# 获取 Schema
schema = fetch_schema_from_introspection("http://localhost:8888/graphql")

# 生成测试用例
generator = HttpRunnerTestCaseGenerator(schema, base_url="http://localhost:8888")
count = generator.generate_test_cases("testcases")
print(f"生成了 {count} 个测试用例")
```

## 完整功能列表

| 功能分类 | 具体功能 |
|---------|---------|
| **Schema 处理** | ✅ 解析 GraphQL Schema 文件<br>✅ 通过内省查询获取 Schema<br>✅ 支持 Query 和 Mutation 类型 |
| **测试用例生成** | ✅ 自动生成 HttpRunner YAML 测试用例<br>✅ API 层和用例层分离<br>✅ 支持全量参数或仅必选参数<br>✅ 支持 skip 关键字 |
| **查询语句生成** | ✅ 生成完整的 GraphQL 查询语句<br>✅ 智能处理参数和默认值<br>✅ 可调节查询嵌套深度 |
| **差异对比** | ✅ 自动备份和对比<br>✅ Markdown/HTML格式报告<br>✅ 详细的变更追踪 |
| **自动更新** | ✅ 根据差异自动更新测试用例<br>✅ 智能处理新增、删除、修改<br>✅ 保留自定义配置 |
| **批量处理** | ✅ 多项目批处理模式<br>✅ 单项目/单查询处理<br>✅ 灵活的配置管理 |
| **集成能力** | ✅ CI/CD 集成<br>✅ 定时API监测与用例维护<br>✅ 提供 Python API |

## 文档导航

### 📖 用户文档

- **[安装指南](docs/installation.md)** - 详细的安装说明和常见问题
- **[快速入门](docs/quickstart.md)** - 5-10 分钟快速上手教程
- **[用户手册](docs/user-guide.md)** - 完整的命令行参数和使用说明
- **[常见问题](docs/faq.md)** - FAQ 和疑难解答

### 🚀 高级功能

- **[高级功能](docs/advanced-features.md)** - 差异对比、自动更新、CI/CD 集成
- **[完整工作流示例](docs/examples/basic-workflow.md)** - 实际项目使用示例

### 🔧 开发者文档

- **[开发者指南](docs/developer-guide.md)** - 项目架构、开发环境、贡献指南
- **[API 参考](docs/api-reference.md)** - Python API 完整文档

## 主要参数

```bash
gpl2hrun --help
```

| 参数 | 说明 | 示例 |
|------|------|------|
| `-f, --schema-file` | GraphQL Schema 文件路径 | `-f schema.graphql` |
| `-i, --introspection-url` | GraphQL 内省查询 URL | `-i http://localhost:8888/graphql` |
| `-t, --testcases` | 生成测试用例 | `-t` |
| `-q, --queries` | 生成查询语句列表 | `-q` |
| `-o, --output` | 输出路径 | `-o testcases` |
| `-u, --base-url` | API 基础 URL | `-u http://localhost:8888` |
| `-d, --max-depth` | 查询嵌套深度 | `-d 3` |
| `--api` | 生成 API 层测试用例 | `--api` |
| `--required` | 只包含必选参数 | `--required` |
| `--report` | 生成差异报告 | `--report html` |
| `-b, --batch` | 批处理模式 | `-b config.csv` |
| `-a, --auto-update` | 自动更新测试用例 | `-a` |

> 💡 完整参数说明请查看 [用户手册](docs/user-guide.md#完整参数说明)

## 实际应用场景

### 1. 日常开发测试

```bash
# 快速为新 API 生成测试
gpl2hrun -i http://localhost:8888/graphql -t --query-name newAPI
hrun testcases/test_newAPI.yml
```

### 2. API 变更监测

```bash
# 每日定时检查 API 变更
gpl2hrun -b config.csv -q --report html

# 有变更时自动更新测试用例
gpl2hrun -b config.csv -a
```

### 3. 持续集成

```groovy
// Jenkins Pipeline
pipeline {
    agent any
    stages {
        stage('生成测试') {
            steps {
                sh 'gpl2hrun -b config.csv -a'
            }
        }
        stage('运行测试') {
            steps {
                sh 'hrun testcases'
            }
        }
    }
}
```

### 4. 多环境测试

```bash
# 开发环境
gpl2hrun -i http://dev.api.com/graphql -t -o dev_testcases

# 测试环境
gpl2hrun -i http://test.api.com/graphql -t -o test_testcases

# 生产环境（只读）
gpl2hrun -i http://prod.api.com/graphql -q --report html
```


## 为什么选择这个工具？

### 🎯 解决的问题

- ❌ **手动编写测试用例费时费力**
  - ✅ 自动生成，节省 90% 时间

- ❌ **API 变更后测试用例失效**
  - ✅ 自动对比差异，智能更新

- ❌ **多项目维护成本高**
  - ✅ 批处理模式，一键搞定

- ❌ **测试覆盖率难以保证**
  - ✅ 自动生成全覆盖用例

### 💡 适用场景

- ✅ GraphQL API 测试自动化
- ✅ API 接口回归测试
- ✅ API 变更监测和文档化
- ✅ 持续集成/持续部署 (CI/CD)
- ✅ 多项目/多环境测试管理



## 贡献

欢迎贡献代码、报告问题或提出建议！

- **项目主页**: https://git.umlife.net/zhangchuzhao/graphql-schema-to-httprunner
- **PyPI**: https://pypi.org/project/graphql-to-httprunner
- **问题反馈**: [提交 Issue](https://git.umlife.net/zhangchuzhao/graphql-schema-to-httprunner/issues)
- **贡献代码**: [开发者指南](docs/developer-guide.md#代码贡献指南)。


## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。


---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给一个 Star ⭐**

[立即开始](docs/quickstart.md) • [查看文档](docs/) • [报告问题](https://git.umlife.net/zhangchuzhao/graphql-schema-to-httprunner/issues)

</div>
