graphql-to-httprunner 1.9.3

Automatically generate HttpRunner test cases based on GraphQL Schema

GraphQL to HttpRunner

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

快速开始 • 完整文档 • 特色功能 • 示例

---

简介

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，支持二次开发

快速开始

安装

pip install graphql-to-httprunner

3 分钟完成第一个测试

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

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

步骤 2: 运行测试

pip install httprunner  # 如果未安装
hrun testcases

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

常用场景

场景 1：从 Schema 文件生成

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

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

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

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

gpl2hrun -b config.csv -t

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

gpl2hrun -b config.csv -a

💡 更多用法请查看 快速入门指南

使用示例

生成测试用例

# 从内省查询生成
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

生成查询语句

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

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

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

批处理模式

创建 config.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

批量生成：

gpl2hrun -b config.csv -t

代码集成

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

文档导航

📖 用户文档

• 安装指南 - 详细的安装说明和常见问题
• 快速入门 - 5-10 分钟快速上手教程
• 用户手册 - 完整的命令行参数和使用说明
• 常见问题 - FAQ 和疑难解答

🚀 高级功能

• 高级功能 - 差异对比、自动更新、CI/CD 集成
• 完整工作流示例 - 实际项目使用示例

🔧 开发者文档

• 开发者指南 - 项目架构、开发环境、贡献指南
• API 参考 - Python API 完整文档

主要参数

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

💡 完整参数说明请查看 用户手册

实际应用场景

1. 日常开发测试

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

2. API 变更监测

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

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

3. 持续集成

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

4. 多环境测试

# 开发环境
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
• 贡献代码: 开发者指南。

许可证

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

---

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

立即开始 • 查看文档 • 报告问题