1. 项目概述为什么我们需要一个自己的接口自动化框架干了这么多年测试从手工点点点到写脚本再到搭框架我最大的感触就是重复劳动是效率的杀手而混乱的脚本是维护的噩梦。很多团队在接口自动化初期可能就是几个测试同学各自为战用 Python 的requests库写几个脚本放在本地跑一跑。初期看着挺快但随着接口数量爆炸式增长你会发现一堆问题扑面而来用例怎么组织数据怎么管理依赖接口怎么处理报告怎么生成失败用例怎么重跑脚本一多改个域名都得全局搜索替换更别提多人协作时的冲突了。这时候一个结构清晰、易于维护和扩展的自动化测试框架就显得至关重要。它不是一个炫技的工具而是一个工程化的解决方案目的是把我们从繁琐的重复性工作中解放出来把精力集中在测试用例设计和业务逻辑验证上。今天要聊的就是用Pythonrequestspytest这套黄金组合从零开始搭建一个轻量级但五脏俱全的接口自动化测试框架。这套组合的优势在于Python语法简洁生态丰富requests是 HTTP 库的“瑞士军刀”人见人爱pytest则是测试框架中的“王者”插件化、功能强大到令人发指。把它们组合起来你就能得到一个既灵活又强大的测试基础设施。这个框架适合谁呢如果你是测试新手想系统学习接口自动化并落地实践或者你是团队骨干正为混乱的脚本而头疼希望引入规范亦或是你作为技术负责人需要评估和选型自动化方案那么接下来的内容应该能给你带来不少直接的启发和可以“抄作业”的代码。2. 框架核心设计与选型思路在动手写代码之前我们先得把架子搭好想清楚每个部分为什么要这么设计。一个健壮的框架核心在于解耦和可配置。我们不能把发送请求、检查结果、读取数据这些逻辑全都揉在一个脚本里。2.1 为什么是pytest而不是unittest这是第一个关键选择。虽然 Python 标准库自带了unittest但pytest在自动化测试领域几乎已成事实标准。原因很简单更简洁不需要继承特定的类写测试函数就行用assert语句做断言符合 Pythonic 风格。夹具Fixture强大pytest的fixture机制是管理测试前置和后置操作的利器比如准备测试数据、初始化数据库连接、登录获取 token 等可以定义作用域函数、类、模块、会话实现资源共享大幅减少冗余代码。插件生态丰富生成漂亮的 Allure 报告 (pytest-allure)、控制用例执行顺序 (pytest-ordering)、分布式执行 (pytest-xdist)、失败重试 (pytest-rerunfailures)几乎你能想到的需求都有现成的插件。参数化非常方便pytest.mark.parametrize装饰器可以轻松实现数据驱动测试这是接口自动化中验证不同输入对应输出的核心场景。所以用pytest能让我们站在巨人的肩膀上避免重复造轮子把精力集中在业务测试逻辑本身。2.2 分层架构设计让代码各司其职我们不能把所有代码都堆在一个文件里。一个清晰的分层架构是长期可维护性的基础。我推荐的核心分层如下Common公共层存放框架最底层的工具。比如封装requests的通用请求类处理日志的模块读取配置文件、Excel/YAML 测试数据的工具类。这一层是框架的基石追求稳定和通用。TestCases测试用例层这里存放真正的测试用例脚本。用例应该只关注测试逻辑即“调用哪个接口传入什么数据期望得到什么结果”。它不应该包含如何发送请求、如何解析响应、如何连接数据库等细节。这些细节由下层提供。TestData测试数据层接口测试离不开数据。我们将测试数据如请求参数、预期结果与测试脚本分离。可以使用 Excel、YAML、JSON 甚至数据库来存储。这样做的好处是当测试数据需要修改时无需改动代码非技术人员如产品经理也能参与维护部分数据。Config配置层存放整个项目的配置信息如不同环境测试、预发布、生产的域名、数据库连接信息、全局变量、日志级别等。通常用一个config.ini或config.py文件来管理方便一键切换测试环境。Reports报告层存放测试执行后生成的日志和测试报告。pytest自带简单报告但更推荐集成Allure生成直观、美观的 HTML 报告包含用例执行状态、步骤详情、请求响应数据甚至截图便于分析和归档。Logs日志层存放运行时日志用于调试和排查问题。框架需要记录关键步骤比如请求的 URL、参数响应的状态码、内容以及断言失败的信息。注意这里没有提到Page Object模型因为那是 UI 自动化的典型模式。在接口测试中我们更常谈论的是业务流封装或接口层封装即把一系列相关的接口调用封装成一个业务函数供测试用例调用。2.3 关键技术点与依赖库清单基于以上设计我们需要安装以下核心 Python 库pytest: 测试框架本体。requests: 用于发送 HTTP 请求。pytest-html: 生成简易 HTML 报告可选Allure 更强大。pytest-allure: 与 Allure 报告集成。allure-pytest: Allure 的 pytest 适配器。PyYAML: 如果使用 YAML 文件管理测试数据。openpyxl/xlrd: 如果使用 Excel 管理测试数据。pytest-rerunfailures: 失败用例重跑插件。pytest-xdist: 分布式并行执行插件提升执行速度。pytest-ordering: 控制用例执行顺序谨慎使用用例应尽量独立。此外还需要在系统上安装 Java 环境因为 Allure 是基于 Java 的和 Allure 命令行工具来生成报告。3. 框架搭建实操从零到一构建核心模块理论说再多不如动手做一遍。我们来一步步搭建这个框架的目录结构并实现核心模块。3.1 项目目录结构创建首先创建一个清晰的项目根目录例如api_auto_framework。在里面建立如下子目录和文件api_auto_framework/ ├── common/ # 公共层 │ ├── __init__.py │ ├── logger.py # 日志模块 │ ├── request_client.py # 封装的requests客户端 │ └── util.py # 其他工具函数如读取配置文件 ├── config/ # 配置层 │ ├── __init__.py │ ├── config.ini # 或 config.yaml/config.py │ └── setting.py # 读取配置的类 ├── testdata/ # 测试数据层 │ ├── __init__.py │ ├── api_data.yaml # YAML格式测试数据 │ └── excel_operator.py # Excel操作类 ├── testcases/ # 测试用例层 │ ├── __init__.py │ ├── conftest.py # pytest的fixture集中管理文件 │ ├── test_login.py # 具体的测试用例文件 │ └── test_user.py ├── reports/ # 报告层.gitignore忽略 │ ├── html/ # 存放pytest-html报告 │ └── allure-results/ # 存放Allure原始结果 ├── logs/ # 日志层.gitignore忽略 │ └── api_test.log ├── requirements.txt # 项目依赖库列表 └── pytest.ini # pytest配置文件这个结构一目了然每个目录职责明确。conftest.py是pytest的一个特殊文件用于存放整个项目或当前目录共享的fixture。3.2 核心模块代码实现1. 配置文件 (config/config.ini和config/setting.py)我们先通过config.ini来管理多环境配置。; config/config.ini [test] base_url https://test-api.example.com username testuser password testpass123 [pre] base_url https://pre-api.example.com username preuser password prepass123 [database] host localhost port 3306 user root password root db test_auto然后在setting.py中编写一个类来读取这些配置。# config/setting.py import os import configparser from pathlib import Path class Config: 配置管理类 def __init__(self, envtest): self.env env self.config configparser.ConfigParser() # 获取项目根目录 self.root_path Path(__file__).parent.parent config_file self.root_path / config / config.ini self.config.read(config_file, encodingutf-8) def get(self, section, option): 获取配置项 try: return self.config.get(section, option) except (configparser.NoSectionError, configparser.NoOptionError): return None property def base_url(self): return self.get(self.env, base_url) # 可以添加更多便捷属性... property def db_config(self): return { host: self.get(database, host), port: self.get(database, port), user: self.get(database, user), password: self.get(database, password), database: self.get(database, db), } # 创建一个全局配置实例默认使用test环境 config Config(envtest)2. 日志模块 (common/logger.py)良好的日志是调试的灯塔。我们使用 Python 标准的logging模块进行封装。# common/logger.py import logging import os from pathlib import Path from config.setting import config class Logger: 日志工具类 def __init__(self, name__name__): self.logger logging.getLogger(name) self.logger.setLevel(logging.DEBUG) # 日志器级别 # 避免重复添加handler if not self.logger.handlers: # 定义日志格式 formatter logging.Formatter( %(asctime)s - %(name)s - %(levelname)s - %(message)s, datefmt%Y-%m-%d %H:%M:%S ) # 控制台处理器 ch logging.StreamHandler() ch.setLevel(logging.INFO) ch.setFormatter(formatter) self.logger.addHandler(ch) # 文件处理器 log_dir config.root_path / logs log_dir.mkdir(exist_okTrue) # 目录不存在则创建 log_file log_dir / api_test.log fh logging.FileHandler(log_file, encodingutf-8) fh.setLevel(logging.DEBUG) fh.setFormatter(formatter) self.logger.addHandler(fh) def get_logger(self): return self.logger # 创建一个全局日志器实例 logger Logger(__name__).get_logger()3. 请求客户端封装 (common/request_client.py)这是框架的心脏。我们要对requests进行二次封装统一处理请求、日志记录、异常捕获和基础断言。# common/request_client.py import requests from common.logger import logger from config.setting import config class RequestClient: 封装的HTTP请求客户端 def __init__(self): self.session requests.Session() self.base_url config.base_url # 可以在这里设置session级别的通用headers如User-Agent self.session.headers.update({ User-Agent: ApiAutoTestFramework/1.0, Content-Type: application/json # 默认JSON实际请求可覆盖 }) def _send_request(self, method, url, **kwargs): 发送请求的核心方法统一添加日志和异常处理 # 拼接完整URL如果传入的不是完整URL if not url.startswith((http://, https://)): url f{self.base_url.rstrip(/)}/{url.lstrip(/)} # 记录请求日志 logger.info(f请求方法: {method}) logger.info(f请求URL: {url}) if kwargs.get(params): logger.info(f请求参数: {kwargs[params]}) if kwargs.get(json): logger.info(f请求体(JSON): {kwargs[json]}) if kwargs.get(data): logger.info(f请求体(Form): {kwargs[data]}) if kwargs.get(headers): logger.info(f请求头: {kwargs[headers]}) try: response self.session.request(method, url, **kwargs) # 记录响应日志 logger.info(f响应状态码: {response.status_code}) logger.info(f响应头: {dict(response.headers)}) # 注意响应体可能很大建议只在调试时记录或只记录前N个字符 logger.debug(f响应体: {response.text[:500]}...) if len(response.text) 500 else logger.debug(f响应体: {response.text}) return response except requests.exceptions.RequestException as e: logger.error(f请求发生异常: {e}) raise e # 定义便捷的请求方法 def get(self, url, **kwargs): return self._send_request(GET, url, **kwargs) def post(self, url, **kwargs): return self._send_request(POST, url, **kwargs) def put(self, url, **kwargs): return self._send_request(PUT, url, **kwargs) def delete(self, url, **kwargs): return self._send_request(DELETE, url, **kwargs) # 可以添加一些通用的断言方法 def assert_status_code(self, response, expected_code): 断言状态码 actual_code response.status_code assert actual_code expected_code, \ f状态码断言失败预期: {expected_code}, 实际: {actual_code}, 响应: {response.text} logger.info(f状态码断言成功: {expected_code}) def assert_json_value(self, response, json_path, expected_value): 使用jsonpath或简单字典键值对断言JSON响应中的值这里简化处理 # 实际项目中可以使用jsonpath-ng库进行复杂解析 resp_json response.json() # 这里假设json_path是简单的键如 data.token keys json_path.split(.) actual resp_json for key in keys: actual actual.get(key) if actual is None: break assert actual expected_value, \ fJSON值断言失败路径: {json_path}, 预期: {expected_value}, 实际: {actual} logger.info(fJSON值断言成功: {json_path} - {expected_value}) # 可以创建一个全局的请求客户端实例方便在fixture或用例中直接导入 # client RequestClient()实操心得在封装请求客户端时一定要把Session用起来。Session可以自动保持 Cookies对于需要登录态的接口测试至关重要避免了每个请求手动传递 Cookie 的麻烦。同时统一的日志记录能让问题排查效率提升数倍。4. 编写与组织测试用例有了强大的基础模块编写测试用例就变成了一件愉快的事情。用例脚本应该非常干净只关注业务逻辑。4.1 使用 Fixture 管理测试生命周期pytest的fixture是管理测试依赖的神器。我们把常用的fixture写在testcases/conftest.py里。# testcases/conftest.py import pytest from common.request_client import RequestClient from config.setting import config pytest.fixture(scopesession) def api_client(): 提供一个全局的API请求客户端整个测试会话只初始化一次 client RequestClient() yield client # 测试结束后可以做一些清理工作比如关闭sessionrequests Session的close方法 client.session.close() print(测试会话结束资源已清理。) pytest.fixture def login_token(api_client): 登录并获取token的fixture作用域为function每个用例执行一次 # 假设登录接口 login_url /auth/login login_data { username: config.get(config.env, username), password: config.get(config.env, password) } resp api_client.post(login_url, jsonlogin_data) # 断言登录成功 api_client.assert_status_code(resp, 200) token resp.json().get(data, {}).get(token) assert token, 登录失败未获取到token # 将token设置到client的session headers中后续请求自动携带 api_client.session.headers.update({Authorization: fBearer {token}}) return token4.2 编写一个具体的测试用例现在我们来写一个测试用户查询接口的用例。# testcases/test_user.py import pytest import allure allure.feature(用户管理模块) # Allure报告特性分类 class TestUserAPI: allure.story(查询用户列表) # Allure报告故事/场景 allure.title(正常查询用户列表) # Allure报告用例标题 def test_get_user_list_normal(self, api_client): 测试正常查询用户列表 with allure.step(步骤1: 发送查询用户列表请求): resp api_client.get(/users, params{page: 1, size: 10}) with allure.step(步骤2: 验证响应状态码为200): api_client.assert_status_code(resp, 200) with allure.step(步骤3: 验证响应体结构及关键字段): resp_json resp.json() # 断言响应包含data字段 assert data in resp_json # 断言data是列表 assert isinstance(resp_json[data], list) # 断言列表长度不超过请求的size assert len(resp_json[data]) 10 # 如果有用户检查第一个用户是否有id和name字段 if resp_json[data]: user resp_json[data][0] assert id in user assert name in user allure.attach(resp.text, name响应体, attachment_typeallure.attachment_type.TEXT) allure.story(查询用户详情) allure.title(查询存在的用户) pytest.mark.parametrize(user_id, expected_name, [ (1, 张三), (2, 李四), ]) def test_get_user_by_id_success(self, api_client, user_id, expected_name): 参数化测试查询指定ID的用户 resp api_client.get(f/users/{user_id}) api_client.assert_status_code(resp, 200) resp_json resp.json() # 使用封装的断言方法 api_client.assert_json_value(resp, data.name, expected_name) allure.story(查询用户详情) allure.title(查询不存在的用户) def test_get_user_by_id_not_found(self, api_client): 测试查询不存在的用户应返回404 resp api_client.get(/users/99999) # 这里我们预期是404使用封装的断言 api_client.assert_status_code(resp, 404) # 还可以断言错误信息 assert resp.json().get(code) 10004 # 假设业务错误码代码解读我们使用了allure装饰器来美化测试报告让报告更具可读性。测试类TestUserAPI继承了objectpytest不要求特定父类。测试方法以test_开头这是pytest的默认发现规则。测试方法接收api_client这个fixture作为参数这是依赖注入。第二个测试方法使用了pytest.mark.parametrize实现数据驱动只需写一个测试方法就能用多组数据运行多次。断言使用了 Python 原生的assert和我们自己封装的assert_status_code等方法。allure.step和allure.attach用于在报告中添加详细的步骤和附件这对调试复杂场景非常有帮助。4.3 数据驱动测试进阶对于更复杂的数据驱动比如测试用例和测试数据完全分离我们可以结合 YAML 或 Excel。这里以 YAML 为例。首先在testdata/api_data.yaml中定义数据# testdata/api_data.yaml create_user: - case_id: C001 title: 创建用户-正常流程 request: method: post url: /users json: name: 测试用户A email: test_aexample.com validate: status_code: 201 json: - eq: [$.code, 0] # 使用jsonpath表达式需要jsonpath-ng库支持 - eq: [$.data.name, 测试用户A] - case_id: C002 title: 创建用户-邮箱格式错误 request: method: post url: /users json: name: 测试用户B email: invalid-email validate: status_code: 400 json: - eq: [$.code, 10001]然后在common层创建一个数据加载器并在用例中读取# common/data_loader.py import yaml import os from pathlib import Path def load_yaml_test_data(file_name): 加载YAML测试数据文件 data_file Path(__file__).parent.parent / testdata / file_name with open(data_file, r, encodingutf-8) as f: data yaml.safe_load(f) return data # testcases/test_user_with_yaml.py import pytest import allure from common.data_loader import load_yaml_test_data test_data load_yaml_test_data(api_data.yaml).get(create_user, []) allure.feature(用户管理-YAML数据驱动) class TestUserWithYAML: pytest.mark.parametrize(case, test_data, ids[item[title] for item in test_data]) def test_create_user(self, api_client, case): allure.dynamic.title(case[title]) req case[request] resp api_client._send_request(req[method], req[url], jsonreq.get(json)) # 动态断言根据YAML中的validate部分进行验证 for validation in case[validate]: if status_code in validation: api_client.assert_status_code(resp, validation[status_code]) if json in validation: for json_val in validation[json]: # 这里需要实现一个更强大的jsonpath断言器 pass这种方式将测试逻辑和数据彻底分离维护性极高。5. 运行测试与生成报告框架搭好了用例写好了最后一步就是运行并产出可视化的结果。5.1 配置pytest.ini文件在项目根目录创建pytest.ini可以统一配置pytest的行为。; pytest.ini [pytest] ; 指定测试文件的位置和命名规则 testpaths testcases python_files test_*.py python_classes Test* python_functions test_* ; 添加命令行默认参数 addopts -v ; 详细输出 --tbshort ; 错误回溯信息简洁模式 --strict-markers ; 严格检查marker --alluredirreports/allure-results ; 指定Allure结果目录 ; --htmlreports/html/report.html --self-contained-html ; 生成pytest-html报告 ; 自定义markers用于标记用例如冒烟测试、回归测试 markers smoke: 冒烟测试用例 regression: 回归测试用例5.2 执行测试与生成 Allure 报告在终端中进入项目根目录执行以下命令运行所有测试pytest运行带有特定标记的测试如冒烟测试pytest -m smoke运行指定模块或类pytest testcases/test_user.py pytest testcases/test_user.py::TestUserAPI生成 Allure 报告 首先确保已安装 Allure 命令行工具。运行测试后--alluredir参数指定的目录reports/allure-results会生成一堆.json文件。然后使用 Allure 命令生成 HTML 报告。# 生成报告 allure generate reports/allure-results -o reports/allure-report --clean # 打开报告本地起一个服务 allure open reports/allure-report生成的报告是一个完整的 HTML 站点可以在浏览器中查看详尽的测试结果、趋势图、用例步骤等。5.3 集成失败重试与并行执行为了提高测试稳定性和效率我们可以在pytest.ini的addopts中增加插件参数addopts -v --tbshort --strict-markers --alluredirreports/allure-results --reruns 2 --reruns-delay 1 ; 失败重试2次每次间隔1秒 -n auto ; 使用所有CPU核心并行执行需要pytest-xdist--reruns: 来自pytest-rerunfailures插件对于网络不稳定或服务偶发异常的接口非常有用。-n auto: 来自pytest-xdist插件可以并行运行测试大幅缩短测试套件的总执行时间。6. 常见问题、排查技巧与进阶思考在实际搭建和使用过程中你肯定会遇到各种各样的问题。这里记录一些典型的“坑”和解决思路。6.1 接口依赖与 Token 管理问题测试用例 B 依赖于用例 A 产生的数据如用户ID或状态如登录Token。解决方案使用fixture如上面所示的login_tokenfixture确保在需要登录态的用例执行前先执行登录。可以通过fixture的scope参数如session控制登录次数避免每次用例都登录。封装业务流将一组连续的接口调用如注册-登录-创建订单封装成一个函数或fixture返回最终的结果如订单号。测试用例直接调用这个封装好的流程。数据准备与清理在fixture中通过调用初始化接口准备测试数据setup并在测试后调用清理接口删除数据teardown可以使用yield语法实现。6.2 测试数据隔离与清理问题并行测试时多个用例操作同一份数据导致相互干扰。解决方案使用随机数据在准备测试数据时使用随机生成的用户名、邮箱、手机号等如test_user_timestamp确保每次运行数据唯一。每个用例独立数据fixture的scope设置为function确保每个用例都有自己独立的数据集。数据库清理策略在测试套件开始前或结束后执行 SQL 脚本或调用清理接口将测试数据恢复到初始状态。可以使用pytest的session或module级别的fixture来做全局的setup和teardown。6.3 处理动态参数如时间戳、签名问题某些接口需要携带当前时间戳或对参数进行加密签名。解决方案在封装的RequestClient中通过请求钩子hooks或在发送请求前对参数进行预处理的方式动态添加。class RequestClient: def __init__(self): self.session requests.Session() self.session.hooks[request].append(self._add_timestamp_and_sign) def _add_timestamp_and_sign(self, request, **kwargs): 请求前钩子添加时间戳和签名 # 1. 添加时间戳 params request.params or {} params[timestamp] int(time.time()) request.prepare_url(request.url, params) # 2. 计算签名假设签名算法是md5(排序后的参数secret) # 这里需要根据实际签名规则实现 # secret config.get(api, secret) # sign calculate_sign(request, secret) # request.headers[Sign] sign return request6.4 断言复杂 JSON 响应问题响应 JSON 结构复杂嵌套深断言某个特定字段值很麻烦。解决方案使用jsonpath库如jsonpath-ng来定位和提取值。from jsonpath_ng import parse def assert_by_jsonpath(response, jsonpath_expr, expected_value): json_data response.json() jsonpath_expr parse(jsonpath_expr) matches [match.value for match in jsonpath_expr.find(json_data)] assert len(matches) 0, f在响应中未找到路径: {jsonpath_expr} # 假设我们只关心第一个匹配项 actual_value matches[0] assert actual_value expected_value, fJSONPath断言失败: {jsonpath_expr}, 预期: {expected_value}, 实际: {actual_value}6.5 框架的持续集成CI集成一个成熟的框架最终需要融入 CI/CD 流水线。通常做法是将代码提交到 Git 仓库。CI 工具如 Jenkins、GitLab CI、GitHub Actions监听代码变更。触发流水线拉取代码安装依赖 (pip install -r requirements.txt)。执行测试命令 (pytest)。生成 Allure 报告并归档或发布到内部网站。根据测试结果通过率决定是否继续后续的部署流程。你可以在项目根目录创建一个简单的 Jenkinsfile 或.gitlab-ci.yml来定义这些步骤。搭建一个接口自动化测试框架就像搭积木核心是理解每个模块的职责并将它们优雅地组合在一起。从最初的几个脚本到分层清晰、功能完备的框架这个过程本身也是对软件工程和测试体系化思维的很好锻炼。这个基于Pythonrequestspytest的框架只是一个起点你可以根据自己项目的实际情况不断扩展和优化它比如加入数据库校验、消息队列监听、性能基准测试等让它真正成为保障产品质量的得力助手。