Swagger to Test Cases -- API 自动化测试用例生成 + 测试框架

从 Swagger/OpenAPI 2.0/3.x 规格文件生成 API 自动化测试用例，支持两种输出：

Excel 用例表 和 pytest 测试框架文件。

同时提供一个完整的测试运行框架，包含配置管理、日志、HTTP封装、Fixture、报告五大核心模块。

核心模块架构

swagger-to-testcases/
  framework/              # 测试运行框架
    __init__.py           # 框架入口，统一导出
    config.py             # 1. 配置模块 - 多环境切换
    logger.py             # 2. 日志模块 - 结构化日志
    http_client.py        # 3. HTTP请求封装 - 统一请求+断言+提取
    fixtures.py           # 4. Fixture机制 - 登录/初始化/清理
    reporter.py           # 5. 报告模块 - Allure报告
    conftest.py           # pytest 全局配置模板
  config/                 # 多环境配置文件
    default.yaml          # 默认配置
    dev.yaml              # 开发环境
    test.yaml             # 测试环境
  scripts/
    parse_swagger.py      # Swagger 解析器
    generate_testcases.py # Excel/pytest 生成器
    run.py                # 一键管道脚本
  project_templates/
    pyproject.toml        # 项目依赖模板

模块 1: 配置模块 (framework/config.py)

多环境配置管理，优先级：环境变量 > 环境YAML > default.yaml

功能

• 支持 dev/test/staging/prod 多环境切换
• 管理 base_url、账号、数据库连接、认证配置
• 环境变量覆盖：TEST_BASE_URL, TEST_DATABASE_HOST 等
• 配置项通过点号路径访问：config.get('database.host')

使用

from framework import config

# 切换环境
# export TEST_ENV=test
base_url = config.base_url       # http://test.example.com/api/v1
db_host = config.database['host']
timeout = config.timeout          # 30

# 设置运行时 token
config.set_token('xxx-token-xxx')

配置文件格式 (config/default.yaml)

base_url: "http://localhost:8080"
timeout: 30
headers:
  Content-Type: "application/json"
accounts:
  admin:
    username: "admin"
    password: "admin123"
database:
  host: "localhost"
  port: 3306
  database: "test_db"
auth:
  login_path: "/api/login"
  token_key: "token"
  token_type: "Bearer"
report:
  allure_dir: "reports/allure-results"
  log_dir: "reports/logs"

模块 2: 日志模块 (framework/logger.py)

结构化日志，请求/响应/断言都有专用方法，失败时快速定位。

功能

• 双输出：控制台(INFO级别) + 按日期文件(DEBUG级别)
• 专用方法：logger.request(), logger.response(), logger.assertion()
• 自动脱敏：Authorization、token、cookie、password 等敏感字段掩码
• 自动截断：过长 body/headers 超过2000字符自动截断
• 提取变量：logger.extract() 记录关联变量值
• 测试步骤：logger.step() 标记测试流程节点

日志格式

2026-06-05 16:30:00 | INFO  | test_user.py:25 | REQUEST  GET http://...
2026-06-05 16:30:00 | INFO  | test_user.py:26 | RESPONSE 200 (45ms)
2026-06-05 16:30:00 | INFO  | test_user.py:27 | ASSERT [PASS] status code == 200
2026-06-05 16:30:00 | ERROR | test_user.py:27 | ASSERT [FAIL] jsonpath $.code

模块 3: HTTP请求封装 (framework/http_client.py)

统一请求入口，自动处理 header、token、超时、重试、异常，内置断言和关联提取。

功能清单

使用

from framework import client

# 基础请求
resp = client.get('/api/users', params={'page': 1})

# 自动断言 + 提取
resp = client.get('/api/users/1')
resp.assert_status(200)\
   .assert_jsonpath({'$.code': 0})\
   .assert_business_code()\
   .extract({'user_id': '$.data.id'})

# 使用提取的变量
client.get('/api/users/{{user_id}}')

# POST 带 body 自动生成
client.post('/api/users', body={'name': 'John', 'email': 'john@test.com'})
   .assert_status(201)

# 数据库断言
client.db_assert(
    config.database,
    table='users',
    where={'id': 1},
    expect={'status': 1}
)

模块 4: Fixture机制 (framework/fixtures.py)

测试前置/后置管理，登录、初始化、清理一站式。

功能

使用

from framework import fixture

class TestUser:
    @pytest.fixture(autouse=True)
    def setup(self):
        fixture.login_if_needed('admin')   # 登录前置
        yield
        fixture.cleanup()                  # 清理后置

模块 5: 报告模块 (framework/reporter.py)

生成 Allure 报告 + 邮件发送，自动附加请求/响应/断言信息。

功能

• 自动检测 allure-pytest 可用性，不可用时降级为文件记录
• attach_request/response/assertion 附加详细数据到 Allure 报告
• 自动脱敏：敏感 header 值掩码
• generate_summary() 生成 JSON 摘要报告（总数/通过/失败/跳过/通过率）
• 邮件发送：通过 SMTP 发送精美 HTML 报告，支持附件（Allure报告zip/Excel用例/日志）
• 邮件内容：通过率可视化进度条、失败用例详情、测试结果表格
• 密码安全：SMTP密码支持环境变量 TEST_REPORT_EMAIL_PASSWORD

邮件配置 (config/default.yaml)

report:
  email:
    smtp_host: "smtp.163.com"
    smtp_port: 465
    smtp_ssl: true
    from_addr: "test-report@163.com"
    from_name: "API测试报告"
    password: ""              # 推荐用环境变量避免明文
    to_addrs:
      - "dev-team@company.com"
    cc_addrs: []

使用

from framework import reporter

# 方式1：直接发送（使用配置的收件人）
reporter.send_email(
    summary={'total': 100, 'passed': 98, 'failed': 2, 'skipped': 0},
    title='User模块测试报告'
)

# 方式2：指定收件人 + 附件
reporter.send_email(
    summary=summary,
    to_addrs=['qa@company.com', 'dev@company.com'],
    attachments=['reports/allure-report.zip', 'tests/testcases.xlsx']
)

# 方式3：一键打包 Allure 报告并发送
reporter.send_email_with_allure(
    summary=summary,
    allure_report_dir='reports/allure-report',
    testcases_xlsx='tests/testcases.xlsx'
)

# 方式4：使用 EmailSender 直接控制
from framework.reporter import EmailSender
sender = EmailSender()
sender.send_simple(
    subject='构建通知',
    body='<h3>测试全部通过</h3><p>详情见附件</p>',
    body_type='html'
)

命令行使用

# 运行测试并生成报告
pytest tests/ --alluredir=reports/allure-results -v

# 生成 Allure 静态报告
allure generate reports/allure-results -o reports/allure-report

# 发送邮件报告（在 conftest 的 pytest_sessionfinish hook 中自动发送）

工作流程

方式一：生成 Excel 用例表（默认）

python scripts/run.py swagger.json
# 输出: swagger_testcases.xlsx

方式二：生成 pytest 测试框架

python scripts/run.py swagger.json --format pytest --output tests/ --with-excel
# 输出: tests/test_*.py + tests/conftest.py + tests/testcases.xlsx

方式三：分步执行

# Step 1: 解析 Swagger
python scripts/parse_swagger.py swagger.json > testcases.json

# Step 2: 生成文件
python scripts/generate_testcases.py testcases.json tests/ --format pytest --with-excel

在项目中运行

1. 将 framework/ 目录复制到测试项目
2. 配置 config/default.yaml 和环境配置文件
3. 将生成的 tests/ 目录放到项目根目录
4. 安装依赖：pip install -r requirements.txt（或使用 project_templates/pyproject.toml）
5. 运行：pytest tests/ --alluredir=reports/allure-results -v
6. 查看报告：allure serve reports/allure-results

Excel 输出格式

26列完整测试用例表，视觉格式化（蓝色表头/冻结首行/自动筛选/颜色编码）。

详见 references/field_spec.md。

依赖

requests>=2.28
openpyxl>=3.1
pyyaml>=6.0
pytest>=7.0
pymysql>=1.0          # 可选，DB断言需要
allure-pytest>=2.13   # 可选，Allure报告需要