从零搭建Python接口自动化测试框架：Pytest+Requests实战指南

1. 项目概述与核心价值

最近在带团队新人，发现很多同学对接口自动化测试的理解还停留在“用Postman点点点”或者“写几个requests请求”的阶段。当项目迭代加快，接口数量膨胀到几百上千个时，这种零散的脚本维护成本会指数级上升，最终要么测试脚本烂尾，要么测试效率低下。这正是我们需要一个标准化、可维护、易扩展的自动化框架的根本原因。今天，我就结合自己多年在多个项目中落地自动化测试的经验，从零开始手把手搭建一个基于Python的接口自动化测试框架，并附上完整的源码。这个框架不是花架子，它集成了请求处理、数据驱动、测试报告、用例管理和持续集成等核心模块，目标是让你写出的自动化脚本像搭积木一样简单，同时又能支撑起中大型项目的测试需求。

无论你是刚接触自动化测试的新手，还是想优化现有测试体系的老手，这个框架都能给你提供一个清晰的、可直接落地的参考。我们会用到pytest作为测试执行引擎，requests处理HTTP请求，Allure或pytest-html生成漂亮报告，并通过YAML或JSON来管理测试数据。整个搭建过程我会拆解成几个核心模块，每个模块不仅告诉你“怎么做”，更会重点解释“为什么这么做”，以及我在实际项目中踩过的坑和总结的最佳实践。

2. 框架整体设计与核心思路拆解

在动手写代码之前，我们先花点时间把框架的设计思路理清楚。一个好的框架，其价值在于通过约定和规范，降低协作成本，提升脚本的复用性和可维护性。我们的目标不是发明轮子，而是合理地组装现有的优秀轮子。

2.1 为什么选择Pytest+Requests这个技术栈？

市面上Python的测试框架不少，比如unittest、nose2，还有新兴的pytest。我坚定地选择pytest作为核心，原因有几个：首先，它的语法极其简洁，不需要像unittest那样继承特定的类，用起来更符合Pythonic的风格；其次，它的插件生态非常繁荣，比如参数化(@pytest.mark.parametrize)、夹具(@pytest.fixture)、钩子函数等，能让我们以极低的成本实现复杂功能；最后，它与CI/CD工具（如Jenkins）的集成非常顺畅，报告格式丰富。

对于HTTP请求库，requests几乎是Python界的标准答案，它比原生的urllib更友好，功能也足够强大。虽然也有httpx这样的后起之秀支持异步，但对于大多数接口测试场景，同步的requests在简单性和稳定性上已经足够。我们的框架会在requests之上做一层薄薄的封装，目的是统一请求的预处理（如加签、加密）和响应处理（如状态码断言、JSON解析）。

2.2 框架的目录结构设计

清晰的目录结构是框架可维护性的基石。我推荐以下结构，这也是经过多个项目验证过的：

api_auto_framework/ ├── common/ # 公共模块 │ ├── __init__.py │ ├── logger.py # 日志模块 │ ├── request_client.py # 封装的请求客户端 │ └── config.py # 配置文件读取 ├── test_data/ # 测试数据 │ ├── __init__.py │ └── api_cases.yaml # 以YAML存储的用例数据 ├── test_cases/ # 测试用例 │ ├── __init__.py │ ├── conftest.py # pytest共享夹具 │ └── test_user_api.py # 具体的测试用例文件 ├── reports/ # 测试报告（.gitignore忽略） │ └── allure-results/ ├── outputs/ # 其他输出，如日志、临时文件 ├── utils/ # 工具函数 │ ├── __init__.py │ ├── data_handle.py # 数据处理工具 │ └── assert_utils.py # 自定义断言工具 ├── requirements.txt # 项目依赖 ├── pytest.ini # pytest配置文件 └── README.md # 项目说明

这样设计的好处：common放框架核心能力，test_cases只关心业务逻辑，test_data实现数据与代码分离，utils提供通用支持。各司其职，耦合度低。当你需要新增一个模块的业务测试时，只需要在test_cases下新建一个文件，并在test_data下补充对应的数据即可。

2.3 核心流程与数据驱动设计

框架的核心执行流程可以概括为：读取配置 -> 准备数据 -> 执行请求 -> 断言验证 -> 生成报告。其中，“数据驱动”是提升用例维护效率的关键。我们将测试用例的输入（请求参数）和预期输出（断言条件）从代码中剥离出来，存放在YAML或JSON文件中。

例如，一个登录接口的测试数据在YAML中可能这样组织：

test_login: - case_id: TC_LOGIN_001 title: “使用正确用户名密码登录成功” request: method: POST url: /api/v1/login json: username: “admin” password: “123456” validate: - eq: [status_code, 200] - eq: [$.code, 0] # 使用JsonPath提取响应中的code字段 - contains: [$.message, “成功”] - case_id: TC_LOGIN_002 title: “使用错误密码登录失败” request: method: POST url: /api/v1/login json: username: “admin” password: “wrong” validate: - eq: [status_code, 401]

在测试脚本中，我们通过pytest.mark.parametrize来读取这些数据，并驱动测试执行。这样做最大的好处是，产品经理或测试人员即使不懂代码，也能看懂并维护测试数据，实现了“低代码”的自动化。

3. 核心模块实现与封装细节

有了清晰的设计图，我们就可以开始动手搭建了。我们从最基础的请求客户端封装开始，这是所有接口调用的基石。

3.1 请求客户端的智能封装

直接使用requests发起请求当然可以，但缺乏统一处理。我们的封装目标是为所有请求自动添加通用头（如Content-Type）、处理身份认证（如自动注入Token）、记录日志、并提供一个更友好的异常处理和响应解析接口。

在common/request_client.py中，我们创建一个ApiClient类：

import requests import allure from common.logger import logger from common.config import Config class ApiClient: def __init__(self, base_url=None): self.session = requests.Session() self.base_url = base_url or Config.BASE_URL # 设置默认请求头 self.session.headers.update({ ‘Content-Type’: ‘application/json; charset=utf-8’, ‘User-Agent’: ‘ApiAutoTestFramework/1.0’ }) # 可以在这里加载全局认证信息，如从环境变量读取token self._load_auth() def _load_auth(self): """加载认证信息，例如从文件或环境变量读取token并设置到session.headers中""" token = Config.TOKEN if token: self.session.headers.update({‘Authorization’: f‘Bearer {token}’}) def _send_request(self, method, endpoint, **kwargs): """发送请求的核心方法，统一处理日志、异常和响应""" url = f‘{self.base_url.rstrip(“/”)}/{endpoint.lstrip(“/”)}’ # 记录请求日志 logger.info(f‘Request: {method.upper()} {url}’) logger.debug(f‘Request kwargs: {kwargs}’) try: response = self.session.request(method, url, **kwargs) # 记录响应日志 logger.info(f‘Response Status: {response.status_code}’) logger.debug(f‘Response Body: {response.text}’) # 将请求响应信息附加到Allure报告，便于排查 allure.attach(f‘{method} {url}\n\n{kwargs}’, ‘Request’, allure.attachment_type.TEXT) allure.attach(response.text, ‘Response’, allure.attachment_type.TEXT) return response except requests.exceptions.RequestException as e: logger.error(f‘Request failed: {e}’) raise # 提供便捷的GET/POST等方法 def get(self, endpoint, params=None, **kwargs): return self._send_request(‘GET’, endpoint, params=params, **kwargs) def post(self, endpoint, json=None, data=None, **kwargs): return self._send_request(‘POST’, endpoint, json=json, data=data, **kwargs) # 可以继续封装put, delete, patch等方法...

封装要点与避坑指南：

1. 使用Session对象：requests.Session()可以自动保持cookies，在一次会话中复用TCP连接，提升性能。对于需要登录的接口测试场景，这是必须的。
2. 统一的日志记录：使用Python标准库的logging模块，为框架配置独立的logger。日志级别要合理，INFO级别记录关键步骤（如请求URL和状态码），DEBUG级别记录详细数据（如请求体和响应体），便于线上问题排查。
3. 与Allure报告集成：通过allure.attach将请求和响应的详细信息附加到测试报告中。当用例失败时，无需查看日志文件，直接在报告里就能看到当时的请求参数和服务器返回，极大提升调试效率。
4. 异常处理：不要简单地except Exception然后吞掉。这里我们只捕获requests.exceptions.RequestException网络相关异常，并记录错误日志后重新抛出。这样上层用例可以捕获并标记测试失败，而不是让框架静默地“吞掉”错误，导致误判为测试通过。

注意：关于认证信息（如Token）的维护，一个常见的坑是硬编码在代码或配置里。更佳实践是设计一个TokenManager类，它负责登录接口的调用、Token的获取、刷新和过期判断，并在ApiClient的_load_auth中调用。这样能实现Token的自动管理。

3.2 灵活可配置的环境管理

一个框架至少要能区分测试、预发布和生产环境。我们将环境配置抽象出来，放在common/config.py中，支持多种方式读取（环境变量 > 配置文件 > 默认值）。

import os import yaml from pathlib import Path class Config: # 基础路径 BASE_DIR = Path(__file__).parent.parent # 默认配置 _default_config = { ‘base_url’: ‘http://localhost:8080’, ‘log_level’: ‘INFO’, ‘report_type’: ‘allure’, # allure 或 html ‘timeout’: 10 } @classmethod def load_config(cls): """加载配置，优先级：环境变量 > config.yaml > 默认配置""" config_file = cls.BASE_DIR / ‘config.yaml’ user_config = {} if config_file.exists(): with open(config_file, ‘r’, encoding=‘utf-8’) as f: user_config = yaml.safe_load(f) or {} # 合并配置，环境变量优先级最高（用于CI/CD） for key, default_value in cls._default_config.items(): env_value = os.getenv(key.upper()) if env_value is not None: setattr(cls, key.upper(), env_value) else: setattr(cls, key.upper(), user_config.get(key, default_value)) # 在模块加载时初始化配置 Config.load_config()

对应的config.yaml文件可以这样写：

# 测试环境配置 base_url: “https://test-api.yourdomain.com” log_level: “DEBUG” timeout: 15 # 数据库配置（如需） # database: # host: “localhost” # name: “test_db”

这样设计的好处：在本地开发时，我们修改config.yaml；在Jenkins等CI/CD环境中，我们通过设置环境变量（如export BASE_URL=https://prod-api.com）来覆盖配置，无需修改代码，实现了环境隔离。

3.3 测试数据的读取与驱动

数据驱动测试的核心是将pytest.mark.parametrize与外部数据文件结合起来。我们在utils/data_handle.py中创建一个数据加载器。

import yaml import json import pytest from pathlib import Path class DataLoader: @staticmethod def load_yaml(file_path): with open(file_path, ‘r’, encoding=‘utf-8’) as f: return yaml.safe_load(f) @staticmethod def load_json(file_path): with open(file_path, ‘r’, encoding=‘utf-8’) as f: return json.load(f) @classmethod def load_test_cases(cls, data_file, key=None): """从数据文件加载测试用例，支持按key筛选""" file_path = Path(__file__).parent.parent / ‘test_data’ / data_file if file_path.suffix == ‘.yaml’: data = cls.load_yaml(file_path) elif file_path.suffix == ‘.json’: data = cls.load_json(file_path) else: raise ValueError(f‘Unsupported file format: {file_path.suffix}’) if key: data = data.get(key, []) # 确保返回的是列表格式，便于parametrize if isinstance(data, dict): # 如果数据是字典，将其值转换为列表（适用于按模块组织用例的场景） cases = [] for k, v in data.items(): if isinstance(v, list): cases.extend(v) else: v[‘case_id’] = k # 将字典的key作为case_id注入 cases.append(v) return cases elif isinstance(data, list): return data else: return [data]

在测试用例中，我们可以这样使用：

import pytest from utils.data_handle import DataLoader class TestUserApi: # 加载test_data/api_cases.yaml中‘test_login’下的所有用例 @pytest.mark.parametrize(‘case_data’, DataLoader.load_test_cases(‘api_cases.yaml’, ‘test_login’)) def test_login(self, case_data, api_client): # case_data 就是YAML中定义的一个用例字典 response = api_client.request( method=case_data[‘request’][‘method’], endpoint=case_data[‘request’][‘url’], json=case_data[‘request’].get(‘json’) ) # 下一步：进行断言验证

数据驱动的高级技巧：有时用例参数需要动态生成，比如时间戳、随机字符串。我们可以在YAML中使用特殊标记，并在数据加载时进行渲染。例如，在YAML中写username: “user_${random_string(6)}”，然后在DataLoader中解析${}，调用对应的函数生成值。这能让你的测试数据“活”起来。

4. 测试用例编写、断言与报告生成

框架的基础设施搭好后，写测试用例就变成了一件愉快而高效的事情。这一部分我们聚焦于如何写出清晰、健壮、易于维护的测试用例。

4.1 使用Pytest Fixture进行测试准备与清理

pytest的夹具（Fixture）是管理测试依赖和生命周期的神器。我们会在test_cases/conftest.py中定义一些全局或模块级的夹具。

import pytest from common.request_client import ApiClient from common.logger import logger @pytest.fixture(scope=“session”) def api_client(): """返回一个全局共享的API客户端实例，整个测试会话只初始化一次""" client = ApiClient() yield client # 测试会话结束后，可以在这里执行清理工作，如关闭session client.session.close() logger.info(“API client session closed.”) @pytest.fixture(scope=“function”) def login_user(api_client): """一个需要登录的测试夹具示例：先登录，返回token或用户信息""" login_data = {“username”: “test_user”, “password”: “test_pass”} resp = api_client.post(“/api/v1/login”, json=login_data) assert resp.status_code == 200 token = resp.json()[“data”][“token”] # 将token设置回api_client的session中，供后续请求使用 api_client.session.headers.update({‘Authorization’: f‘Bearer {token}’}) yield {“token”: token, “username”: “test_user”} # 测试函数结束后，可以执行登出操作（如果需要） # api_client.post(“/api/v1/logout”) # 清理header中的token，避免影响其他测试 api_client.session.headers.pop(‘Authorization’, None)

夹具使用心得：

• scope=“session”：适用于耗时较长的资源初始化，如数据库连接、全局API客户端。整个pytest执行过程只运行一次。
• scope=“module”：适用于模块级别的设置，比如某个模块的所有测试都需要一个特定的测试用户。
• scope=“function”：最常用的级别，每个测试函数都会重新执行一次，保证测试之间的独立性。像login_user夹具，每个需要登录的测试都会独立登录一次，避免用例间因共享登录状态而相互干扰。
• yield的妙用：yield之前是设置代码，yield之后是清理代码。这比传统的setup/teardown方法更清晰，资源清理更有保障。

4.2 强大而清晰的自定义断言

Python自带的assert语句在失败时提示信息不友好。我们封装一个断言工具类，集成常用的断言逻辑，并给出清晰的错误信息。

在utils/assert_utils.py中：

import jsonpath_rw_ext as jp from deepdiff import DeepDiff class AssertUtils: @staticmethod def assert_status_code(actual, expected, msg=“”): assert actual == expected, f‘状态码断言失败: 期望 {expected}, 实际 {actual}. {msg}’ @staticmethod def assert_json_equal(actual_json, expected_json, ignore_order=False, exclude_paths=None): """使用DeepDiff进行复杂的JSON对比，支持忽略顺序和特定路径""" diff = DeepDiff(actual_json, expected_json, ignore_order=ignore_order, exclude_paths=exclude_paths) assert not diff, f‘JSON对比不一致: {diff}’ @staticmethod def assert_json_path(json_data, json_path_expression, expected_value): """使用JsonPath提取并断言JSON中的某个值""" actual_values = jp.match(json_path_expression, json_data) if not actual_values: raise AssertionError(f‘JsonPath “{json_path_expression}” 在响应中未找到匹配项’) # 如果提取到多个值，默认取第一个进行断言。可根据需要调整逻辑。 actual_value = actual_values[0] assert actual_value == expected_value, \ f‘JsonPath断言失败: 路径“{json_path_expression}”期望值 {expected_value}, 实际值 {actual_value}’ @staticmethod def assert_response_time(response, max_time_ms): """断言响应时间在可接受范围内""" elapsed_ms = response.elapsed.total_seconds() * 1000 assert elapsed_ms <= max_time_ms, f‘响应时间过长: {elapsed_ms:.2f}ms > 限制 {max_time_ms}ms’

在测试用例中，断言可以写得非常直观：

def test_get_user_info(self, api_client, login_user): user_id = login_user[‘user_id’] resp = api_client.get(f“/api/v1/users/{user_id}”) # 使用自定义断言 AssertUtils.assert_status_code(resp.status_code, 200) AssertUtils.assert_json_path(resp.json(), ‘$.data.username’, ‘test_user’) AssertUtils.assert_response_time(resp, 500) # 响应时间应小于500ms

为什么不用assert resp.json()[‘code’] == 0？直接使用Python的assert在失败时只会显示AssertionError，你需要点开详情才能看到具体值。而我们的AssertUtils.assert_json_path在失败时会直接打印出期望值和实际值，以及是哪个JsonPath出的问题，调试效率天差地别。

4.3 生成专业美观的测试报告

测试报告是自动化测试价值的直观体现。我们集成Allure来生成交互式、信息丰富的报告。

首先，安装依赖：pip install allure-pytest。然后，在pytest.ini中配置：

[pytest] addopts = -v -s --alluredir=./reports/allure-results testpaths = test_cases python_files = test_*.py python_classes = Test* python_functions = test_*

运行测试：pytest。执行完毕后，会在./reports/allure-results目录下生成原始结果文件。要生成HTML报告，需要安装Allure命令行工具，然后执行：allure generate ./reports/allure-results -o ./reports/allure-report --clean，最后用allure open ./reports/allure-report打开。

让报告更出彩的技巧：

1. 使用@allure装饰器：在测试函数和类上添加@allure.title(“测试用户登录功能”)、@allure.story(“用户管理模块”)、@allure.severity(allure.severity_level.CRITICAL)等，可以在报告中更好地组织和筛选用例。
2. 添加步骤描述：在关键操作处使用with allure.step(“步骤1：发送登录请求”):，这样报告中会展示详细的测试步骤，便于回溯。
3. 附件：如前所述，我们在ApiClient中已经将请求和响应附加到了报告中。
4. 环境信息：创建一个environment.properties文件放在reports/allure-results目录下，内容如base_url=https://test.env，Allure报告会展示这些环境信息。

如果团队环境不允许安装Allure，pytest-html是一个不错的备选，它能生成一个独立的HTML文件，虽然交互性不如Allure，但胜在简单便携。

5. 框架的进阶优化与持续集成

一个基础的框架搭建完成后，我们可以从工程化和效率角度进行一系列优化，让它更强大、更智能。

5.1 测试用例的依赖管理与执行策略

随着用例增多，如何管理用例间的依赖和执行顺序成为问题。pytest不鼓励用例依赖，但通过夹具(fixture)可以巧妙地实现。

场景：测试“修改用户信息”前，必须先存在一个用户。我们可以创建一个create_user夹具，并让test_update_user依赖它。

import pytest @pytest.fixture def create_user(api_client): user_data = {“name”: “FixtureUser”} resp = api_client.post(“/api/v1/users”, json=user_data) user_id = resp.json()[‘id’] yield user_id # 测试后清理：删除用户 api_client.delete(f“/api/v1/users/{user_id}”) def test_update_user(api_client, create_user): user_id = create_user # 这里接收夹具返回的user_id update_data = {“name”: “UpdatedName”} resp = api_client.put(f“/api/v1/users/{user_id}”, json=update_data) assert resp.status_code == 200

通过yield，夹具不仅提供了前置条件（创建用户），还定义了后置清理（删除用户），保证了测试环境的干净。

对于执行策略，我们可以通过pytest的标记(mark)来分类用例，例如@pytest.mark.smoke（冒烟测试）、@pytest.mark.regression（回归测试）。然后在pytest.ini中配置：

[pytest] markers = smoke: 冒烟测试用例 regression: 回归测试用例

运行时可以指定只跑冒烟测试：pytest -m smoke。

5.2 集成CI/CD：让自动化测试自动运行

自动化测试只有集成到CI/CD流水线中，才能发挥最大价值。这里以Jenkins为例，展示一个简单的Jenkinsfile（声明式流水线）配置：

pipeline { agent any environment { // 通过环境变量注入配置，覆盖本地的config.yaml BASE_URL = ‘https://jenkins-test-api.company.com’ PYTHONPATH = ‘.‘ } stages { stage(‘Checkout’) { steps { git ‘https://your-git-repo.com/api-auto-framework.git’ } } stage(‘Install Dependencies’) { steps { sh ‘pip install -r requirements.txt’ } } stage(‘Run Tests’) { steps { // 运行测试并生成Allure原始数据 sh ‘pytest --alluredir=./reports/allure-results’ } } stage(‘Generate Report’) { steps { // 使用Allure命令行工具生成HTML报告 sh ‘allure generate ./reports/allure-results -o ./reports/allure-report --clean’ } } stage(‘Archive Report’) { steps { // 将报告归档，供Jenkins展示 allure([ includeProperties: false, jdk: ‘’, properties: [], reportBuildPolicy: ‘ALWAYS’, results: [[path: ‘reports/allure-results’]] ]) } } } post { always { // 无论成功失败，都清理可能残留的测试数据（如果有全局清理脚本） sh ‘echo “Cleaning up...”’ } } }

CI集成关键点：

1. 环境隔离：务必在CI环境中通过环境变量设置测试地址（如BASE_URL），确保测试指向正确的环境。
2. 依赖安装：使用requirements.txt精确控制依赖版本，避免因环境差异导致测试失败。
3. 报告归档：将Allure报告归档后，Jenkins的Allure插件会提供一个入口，团队成员可以直接在浏览器中查看交互式报告，包括历史趋势图。
4. 测试稳定性：在CI中，网络波动、服务重启都可能导致偶发性失败。可以考虑加入失败重试机制，pytest可以通过pytest-rerunfailures插件实现：pytest --reruns 3（失败后重试3次）。

5.3 常见问题排查与性能优化

在实际使用中，你可能会遇到以下典型问题：

问题1：测试用例执行速度慢。

• 排查：使用pytest -v --durations=10查看最耗时的10个测试用例。通常慢在：1) 网络请求；2) 复杂的数据库准备/清理；3) 单个用例测试数据过多。
• 优化：
  • 使用Session作用域的夹具：对于只读的、昂贵的资源（如数据库连接池、只登录一次的管理员账号），使用@pytest.fixture(scope=“session”)，整个测试会话只初始化一次。
  • 并行执行：使用pytest-xdist插件进行并行测试：pytest -n auto（auto会根据CPU核心数自动分配进程）。注意：并行时需确保用例间完全独立，不共享状态（如同一个测试用户）。
  • Mock外部依赖：对于调用第三方支付、短信等不稳定或收费的接口，使用unittest.mock或pytest-mock进行模拟，返回预设的响应，大幅提升执行速度并避免外部干扰。

问题2：接口依赖复杂，用例数据准备繁琐。

• 方案：建立测试数据工厂。可以编写一个DataFactory类，提供创建用户、创建订单等基础方法。在夹具或用例中调用，避免在YAML中编写冗长的嵌套JSON。对于清理，可以利用数据库操作或调用专门的测试环境清理接口，在setUp和tearDown（或fixture的yield后）中完成。

问题3：动态参数处理，如需要当前时间戳或唯一ID。

• 方案：在数据加载层进行“渲染”。如前所述，可以在YAML值中定义模板变量，如order_no: “ORDER_${timestamp()}”。在DataLoader.load_test_cases方法中，增加一个解析环节，识别${}并调用预定义的函数字典来替换为实际值。

import time import random import string FUNC_MAP = { ‘timestamp’: lambda: int(time.time() * 1000), ‘random_string’: lambda length=8: ‘’.join(random.choices(string.ascii_letters + string.digits, k=int(length))), } def _render_dynamic_value(raw_value): if isinstance(raw_value, str) and raw_value.startswith(‘${’) and raw_value.endswith(‘}’): func_expr = raw_value[2:-1] # 去掉 ${ 和 } func_name, *args = func_expr.split(‘_’) if func_name in FUNC_MAP: return FUNC_MAP[func_name](*args) return raw_value

问题4：Allure报告在CI服务器上无法打开。

• 方案：确保CI服务器上安装了Allure命令行工具。对于Jenkins，需要安装“Allure Jenkins Plugin”插件。报告生成路径配置正确后，Jenkins job页面会出现“Allure Report”图标，点击即可查看。

搭建和维护一个接口自动化框架是一个持续迭代的过程。从最初满足基本请求断言，到加入数据驱动、环境隔离、CI集成，再到优化执行效率、完善报告和问题排查能力，每一步都是为了让测试活动更可靠、更高效。这个框架的完整源码，我已经整理好放在了常用的代码托管平台上。最重要的是理解其设计思想和每个组件存在的理由，然后根据自己项目的实际情况进行裁剪和增强。记住，没有最好的框架，只有最适合你们团队和项目的框架。