NEE's Blog

打造高效API自动化测试框架：基于BDD的保利威直播API测试实践

May 21, 2025

前言

随着微服务架构的广泛应用，API作为系统间通信的桥梁变得越来越重要。如何保证API的稳定性和正确性，成为了开发团队面临的重要挑战。本文将为大家介绍一套基于BDD（行为驱动开发）的API自动化测试框架，该框架专为保利威直播API测试而设计，支持中文测试描述，简化了测试编写流程，提高了测试效率。

一、框架核心理念

我们打造的API测试框架基于以下几个核心理念：

  1. 业务语言驱动测试：使用中文Gherkin语法编写测试场景，让测试脚本更接近业务描述，降低技术门槛
  2. 关注点分离：将请求准备、发送、响应验证分离，使测试脚本结构清晰
  3. 数据生命周期管理：自动创建和清理测试数据，避免测试数据污染
  4. 通用步骤复用：提供丰富的预定义步骤，减少重复代码
  5. 全面的测试类型支持：支持各种测试场景，从基础功能到边界条件

二、技术栈与架构

该框架采用了以下技术栈：

  • Cucumber.js：提供BDD测试驱动能力
  • PactumJS：强大的API测试库
  • TypeScript：提供类型安全保障
  • Chai：断言库

整体架构如下：

polyv-live-openapi-tests/
├── .cursor/           # Cursor IDE配置
│   └── rules/         # 开发规范和指引
│       └── tasks/     # 任务相关规范文件
│           ├── 010-feature-generation.mdc  # 特性文件生成规范
│           ├── 020-scene-generation.mdc    # 场景添加规范 
│           ├── 030-data-lifecycle.mdc      # 数据生命周期管理规范
│           └── 040-scenario-patterns.mdc   # 场景模式规范
├── docs/              # API文档目录
├── scripts/           # 工具脚本
├── src/
│   ├── api/           # API请求封装
│   │   └── urls.ts    # API URL配置
│   ├── features/      # 功能测试文件，按模块组织
│   │   ├── account/   # 账户相关功能
│   │   ├── channel/   # 频道相关功能
│   │   ├── user/      # 用户相关功能
│   │   └── robot/     # 机器人相关功能
│   ├── steps/         # 步骤定义
│   │   └── common/    # 通用步骤定义
│   │       ├── api.steps.ts  # API测试步骤
│   │       └── data.steps.ts # 数据准备步骤
│   ├── support/       # 支持文件
│   └── snapshots/     # 快照测试文件
├── test/              # 单元测试
├── test-snapshots/    # 测试快照目录
├── logs/              # 日志文件
├── .env.example       # 环境变量示例
├── .env               # 环境变量配置
├── cucumber.js        # Cucumber配置
├── package.json       # 项目配置
└── tsconfig.json      # TypeScript配置

三、项目规范与开发流程

1. 特性文件组织规范

特性文件（.feature）是测试的核心，遵循严格的组织规范：

  • 按业务模块组织（如账户、频道、用户等）
  • 一个特性文件对应一个API功能
  • 使用统一的标签命名规范

例如，一个典型的特性文件如下：

# API文档路径: docs/channel/update_channelname.md
@channel @update_channel_name
Feature: 修改频道名称
  作为直播管理员
  我希望能够修改直播频道的名称
  以便于更新频道信息

  @update @create
  Scenario: 成功修改频道名称
    # 先创建一个测试频道
    Given 创建一个新频道
    And 我保存响应中 "data.channelId" 到上下文的 "channelId"
    # 更新频道名称
    When 我设置查询参数 "name" 为 "更新后的频道名称"
    And 我设置路径参数 "channelId" 为 "{context.channelId}"
    And 我基于键名 "CHANNEL.UPDATE_NAME" 发送请求
    Then 响应状态码应为 200
    And 响应JSON应匹配
      """
      {
        "code": 200,
        "status": "success",
        "message": "",
        "data": true
      }
      """

2. 流程化的测试开发

我们建立了一套完整的测试开发流程：

  1. 特性文件生成：根据API文档生成基础特性文件
  2. 场景添加：为特性添加各种测试场景
  3. 执行测试：通过标签选择性执行测试
  4. 报告生成：自动生成测试报告

整个流程使用特定命令简化操作：

# 根据API URL生成特性文件
/add_feat -u https://example.api.polyv.net/api/doc/channel/update 修改频道名称

# 为现有特性添加测试场景
/add_scene src/features/channel/update_channel_name.feature

# 运行带特定标签的测试
/test channel update

四、测试步骤库

框架提供了丰富的预定义步骤，覆盖API测试全流程：

1. 请求准备阶段

# 设置查询参数
我设置查询参数 "name" 为 "测试频道"

# 设置请求体
我设置JSON请求体为表格数据
  | 字段名 | 值     |
  | name  | 测试频道 |

2. 请求发送阶段

# 简化版请求发送（推荐）
我基于键名 "CHANNEL.UPDATE_NAME" 发送请求

# 带方法的请求发送
我基于键名 "CHANNEL.UPDATE_NAME" 发送 "POST" 请求

3. 响应验证阶段

# 状态码验证
响应状态码应为 200

# JSON结构验证
响应JSON应匹配
  """
  {
    "code": 200,
    "data": {
      "id": "*",        # 任意值匹配
      "name": "*测试*"   # 包含"测试"的字符串
    }
  }
  """

# 字段验证
响应字段 "data.success" 应为 true

五、数据生命周期管理

测试数据管理是API测试的难点，我们通过工厂模式和自动清理机制解决：

  1. 通用创建步骤：提供便捷的资源创建步骤 
    # 创建测试数据
Given 创建一个新频道
And 我保存响应中 "data.channelId" 到上下文的 "channelId"
  2. 自动数据清理：使用标签触发清理钩子 
    @channel @create @update
Scenario: 成功修改频道名称
  # 带@create标签的场景会自动清理创建的资源
  3. 上下文数据共享：通过上下文传递数据 
    # 使用上下文中的数据
When 我设置路径参数 "channelId" 为 "{context.channelId}"

六、高级功能特性

1. 深度JSON匹配

支持通配符、模式匹配和部分匹配验证：

响应JSON应匹配
  """
  {
    "code": 200,
    "data": {
      "id": "*",           # 任意值匹配
      "name": "*测试*",     # 包含"测试"的字符串
      "createTime": "*"    # 任意值匹配
    }
  }
  """

2. 快照测试

自动创建和验证API响应快照：

# 创建或验证快照
我保存或验证快照 "channel/update_channel_name_response"

3. 表格式输入

支持表格式输入，增强可读性：

我设置查询参数表格数据
  | 字段名      | 值  |
  | pageNumber  | 1   |
  | pageSize    | 10  |

七、开发规范体系

为确保测试质量和团队协作，我们建立了完善的规范体系：

  1. Feature 文件生成规范：统一文件结构和命名
  2. 场景添加规范：定义场景类型和编写原则
  3. 数据生命周期规范：规范化测试数据管理
  4. 场景模式规范：支持Scenario Outline等高级模式

这些规范通过项目中的 .cursor/rules 目录下的规范文件进行管理，确保团队成员遵循统一标准。

八、测试命令与工作流

开发者通过简单的命令执行测试流程：

# 执行所有测试
/test

# 执行特定标签测试
/test channel update

# 生成特性文件
/add_feat -u API_URL 功能描述

# 添加测试场景
/add_scene 特性文件路径

这些命令极大简化了测试开发流程，提高了团队效率。

九、实际应用效果

该框架已在保利威直播API测试中得到实际应用，实现了以下成效：

  1. 测试编写效率提升：通过预定义步骤和自动生成，降低了测试编写门槛
  2. 覆盖率增加：系统化的测试场景设计，确保API功能全面覆盖
  3. 可维护性提升：统一的规范和组织方式，使测试代码易于维护
  4. 测试报告自动化：生成详细的测试报告，便于问题定位

十、总结与展望

本文介绍的BDD API测试框架实现了”用中文描述测试，用代码验证API”的目标，将业务语言和技术验证无缝结合。这种测试方式不仅提高了测试效率，还促进了业务人员对测试的理解和参与。

未来，我们计划进一步优化框架，增加更多特性：

  1. 支持多环境测试配置
  2. 增强跨API依赖测试
  3. 扩展自动化数据生成能力

希望本文对大家构建API测试框架有所启发，也欢迎交流与讨论！

开源地址

框架已开源，欢迎访问：
https://github.com/terryso/polyv-live-openapi-tests

comments powered by Disqus