做接口自动化测试这几年无论团队大小我最后都会把方案收敛到一套组合上Pytest Allure Excel。Pytest负责用例组织、用例过滤和测试夹具Allure把执行结果变成直观的测试报告Excel则用来维护接口地址、请求参数和预期结果。这套方案几乎不需要额外成本前两者是开源工具Excel是大家都熟悉的办公软件又解决了接口自动化里面最头疼的数据管理问题。这篇文章我不会给你普及基础概念而是直接讲一套可以落地的框架该怎么搭、代码怎么写、数据怎么管、报告怎么出包括我实际踩过的坑和排查思路希望你看完能直接抄作业。1. 项目思路与选型逻辑1.1 接口自动化要解决的三个核心问题接口自动化测试的本质不是“把手工用例变成代码”而是用机器执行来代替人肉回归。我见过太多团队一上来就写几百个测试函数最后用例是跑起来了但没人维护没人看报告也没人敢信这个结果。这套方案首先要解决的其实是三个问题第一是回归效率。接口改动频繁时手工回归一遍几十个接口可能要半天自动化可以在几分钟内跑完一遍并告诉你是哪里挂了。第二是数据维护。如果接口的URL、请求参数、预期结果散落在代码里那改一条数据就得改代码、提 PR、重新部署业务同学也帮不上忙。把测试数据抽到 Excel 之后普通同事也能看懂、能修改。第三是结果反馈。Pytest 跑完如果只是黑屏上一堆滚动日志根本没有意义。Allure 报告把每一步请求、返回、断言结果整理成可视化页面拿给开发看也有理有据。用生活里的例子理解接口是待体检的身体Excel 是体检项目清单Pytest 是体检中心执行流程的护士Allure 就是最后拿到的体检报告单。体检报告单好不好看、能不能一眼看出哪里出了问题直接决定了这套自动化能不能在团队里用起来。1.2 为什么选 Pytest Allure Excel而不是其他组合市面上做接口自动化的工具不少Postman Newman、JMeter、Python 自带的 unittest甚至一些测试平台产品都能干这事。但我为什么还是选 Pytest因为它把“灵活”和“功能”平衡得最好。unittest 虽然不用额外装但写起来啰嗦fixture测试夹具体系也远不如 Pytest 强大。Pytest 的pytest.mark.parametrize参数化可以很容易地和 Excel 行数据一一对应而conftest.py里的 fixture 可以统一管理登录态、数据库清理、环境切换这些准备工作这些能力对接口自动化来说是刚需。选 Allure 的理由更简单它能展示测试步骤、请求体、响应体、附件还能生成历史趋势、缺陷分类和 Flaky 测试信息。Pytest 原生输出只是一个文本终端Logging 或者 HTML 报告插件也可以但视觉和交互远不如 Allure。只需要在 pytest 命令行加一个--alluredir参数再执行一次allure generate就能得到一份适合发给团队看的 Web 报告。它也比 Jenkins 里的 HTML Publisher 插件更直观因为 Allure 本身就是按标准移动端和 Web 端报告习惯设计的。至于 Excel我知道很多技术朋友觉得它“土”但正是因为土业务人员才愿意维护。很多企业的接口测试数据就保存在 Excel 表格里需求评审的时候产品经理可以直接在旁边改。用openpyxl读取 Excel 也足够轻量不依赖 Office 环境。相比 YAML、JSON 文件Excel 最大的优势是表格结构清晰、筛选方便、任何人都能快速定位到某条用例去修改。而且现在也有pandas、pytest-excel这类库可以辅助但我觉得没必要过度封装直接用openpyxl读取反而更可控。2. 框架结构设计与数据流2.1 分层目录设计我搭这套框架时习惯按职责分成四层数据层、核心层、用例层、报告层。目录结构大致是这样的api_test_framework/ ├── data/ # 测试数据 │ ├── login_cases.xlsx │ ├── order_cases.xlsx │ └── config.yaml # 环境地址、账号等配置 ├── utils/ # 公共工具方法 │ ├── excel_reader.py # Excel 读取封装 │ ├── http_client.py # 请求封装 │ └── assertions.py # 断言工具 ├── testcases/ # 测试用例 │ ├── conftest.py # 本目录的 fixture │ ├── test_login.py │ └── test_order.py ├── report/ # Allure 报告输出目录 ├── allure-results/ # Pytest 执行生成的中间结果 ├── conftest.py # 全局 fixture ├── pytest.ini # Pytest 配置 └── requirements.txt为什么这么分层因为接口用例有一个很重要的特点测试步骤基本是雷同的无非是发送请求、拿响应、做断言。如果你每个测试函数都从头写一遍requests.get/post那后面改个公共请求头都会改到怀疑人生。所以要把请求封装起来把数据抽离出来用例层只剩薄薄一层逻辑。data目录放 Excel 文件和全局配置文件utils里放读取和请求工具testcases里放测试用例conftest.py控制测试环境准备。report和allure-results是生成时自动创建的一般会加进.gitignore不然每次跑完都会产生一堆临时文件污染仓库。2.2 用例数据流Excel - 用例 - 报告为什么很多教程里的 Pytest 接口自动化框架跑不起来因为他们只是把代码写出来了没有把数据流理清楚。我理解的这套框架数据流是这样的openpyxl从data/xxx.xlsx读取每一行用例每行代表一条完整用例字段包括用例编号、用例名称、接口路径、请求方法、请求头模板、请求参数、预期状态码、预期结果。pytest通过parametrize把每条数据变成一条测试用例用例名通常会拼接上编号这样在报告里能清楚看到是哪一行数据出了问题。用例执行时http_client负责发起请求并返回响应对象断言工具根据 Excel 里配置的预期值进行校验。执行完成后Pytest 把结果写入allure-results通过allure generate生成最终的 HTML 报告。这套数据流的好处是接口新增时只需要在 Excel 里加一行接口字段变了也只需要改 Excel 的某个单元格代码一行都不用动。最重要的是数据和代码分离之后Python 代码的复杂度和接口数量解耦了不管你加多少用例代码体积基本不变。3. 核心细节解析与实操要点3.1 pytest 配置与用例收集很多新手习惯在代码里写if __name__ __main__: pytest.main(),这样能用但团队协作时往往需要统一配置。我更推荐在项目根目录放一个pytest.ini把常用参数写死这样就可以直接敲pytest执行不用每次带参数[pytest] addopts -vs --alluredir./allure-results --clean-alluredir testpaths testcases python_files test_*.py python_classes Test* python_functions test_* log_cli true log_cli_level INFO这里面有几个参数值得说透。--alluredir./allure-results是让 Pytest 把执行结果写到allure-results目录--clean-alluredir是每次执行前清空上一次的结果避免报告里出现脏数据。testpaths指定扫描哪个目录python_files、python_classes、python_functions决定了 Pytest 识别哪些文件、类、函数才算测试用例。很多时候用例收集不到就是命名不符合这个规则。还有一个细节是log_cli true我建议在框架搭建阶段开起来。这样跑用例时你可以在控制台直接看到每个用例的执行过程排查问题比打开 Allure 报告快很多。等到真正接入 CI 稳定了再把这个关掉也不迟。conftest.py是 Pytest 的“主心骨”。全局conftest.py里放所有测试用例共用的 fixture例如登录后获取 token。如果你直接在每个测试用例里调用登录接口那几十条用例就会打几十次登录请求既浪费流量又影响执行速度。正确的做法是在conftest.py里定义一个session级别的 fixtureimport pytest import requests pytest.fixture(scopesession, autouseTrue) def get_token(): resp requests.post(https://api.example.com/login, json{username: admin, password: 123456}) assert resp.status_code 200 token resp.json()[data][token] print(f获取到 token: {token}) return {Authorization: fBearer {token}}这个 fixture 会在整个会话开始时执行一次然后测试函数通过参数名get_token自动获取返回值。如果你不想每个用例都手动声明这个参数可以设置autouseTrue,但要注意如果你在用例里又显式依赖了它作用域的逻辑一定要理清不然会出现 fixture 找不到的情况。3.2 Excel 数据读取与参数化Excel 驱动是整个框架里看似简单、实际最容易出问题的环节。核心思路是用openpyxl读取 Excel 的每一行转换成列表字典再丢给parametrize。Excel 用例表我一般先按模块拆分成多个 Sheet每个 Sheet 放同一业务线的接口。列结构大概是这样用例编号用例名称接口路径请求方法请求头请求参数预期状态码预期断言TC001正常登录/api/loginPOST{}{username:admin,password:123456}200{code:0}TC002密码错误/api/loginPOST{}{username:admin,password:wrong}200{code:1001}注意请求头和请求参数在 Excel 里最好存成 JSON 字符串。因为openpyxl读出来的是字符串直接丢给请求函数还需要解析。初始阶段你可以在读取时直接json.loads转换这样用例可读性最好。如果你非要把参数拆成很多列也可以但那样读取逻辑会更复杂而且 Excel 里多列合并成一个 dict 的代码写起来很啰嗦。下面是一个经过生产验证的读取函数import json from openpyxl import load_workbook def read_excel_cases(file_path, sheet_name): wb load_workbook(file_path, data_onlyTrue) ws wb[sheet_name] rows list(ws.iter_rows(values_onlyTrue)) # 第一行是表头 headers rows[0] cases [] for row in rows[1:]: # 跳过空行 if row[0] is None: continue row_dict dict(zip(headers, row)) # 把 JSON 字符串解析成 Python 对象 for col in (请求头, 请求参数, 预期断言): if col in row_dict and isinstance(row_dict[col], str): try: row_dict[col] json.loads(row_dict[col]) except json.JSONDecodeError: raise ValueError(f用例 {row_dict.get(用例编号)} 的 {col} 列不是合法 JSON) cases.append(row_dict) return cases这里有一个关键点load_workbook要带data_onlyTrue否则如果有单元格是用公式计算的读出来的是公式字符串而不是值。另一个容易踩的坑是 Excel 日期格式。如果你的用例里包含日期参数openpyxl默认会把它转成datetime对象或字符串这时建议统一在表头里写清楚格式读取时再str()或格式化。然后是在测试用例里使用参数化import json import pytest from utils.http_client import send_request from utils.excel_reader import read_excel_cases case_data read_excel_cases(data/login_cases.xlsx, login) pytest.mark.parametrize(case, case_data, ids[c[用例编号] for c in case_data]) def test_login_case(case, get_token): response send_request(case) assert response.status_code case[预期状态码] assert response.json().get(code) case[预期断言].get(code)ids参数很重要。如果不设置Allure 报告里显示的是case0、case1这种无意义的名字设置了之后报告里直接显示TC001,定位失败用例非常高效。3.3 Allure 报告集成与优化Allure 不是直接作为一个 Python 模块就能输出报告的。它分两部分一部分是 Pytest 插件allure-pytest负责把测试结果序列化成 JSON 文件另一部分是 Allure 命令行的可执行程序负责把 JSON 文件渲染成 HTML 页面。很多人都卡在第二步以为pip install allure-pytest就够了结果执行完发现没有allure命令。安装顺序建议是这样的pip install pytest allure-pytest requests openpyxl然后安装 Allure 命令行。你可以去 GitHub 官方 Releases 下载最新版压缩包解压后将bin目录加入系统 PATH。也可以用系统包管理器安装macOS 上是brew install allure,Windows 上用scoop install allure。注意 Allure 是基于 Java 的工具即使你已经能运行allure --version,也要确保本机有 JRE 1.8 以上环境否则生成报告时可能会直接报错。在测试函数上添加一些 Allure 装饰器可以让报告更专业import allure allure.feature(登录模块) allure.story(正确密码登录) allure.title(用例 TC001正常登录) def test_login_case(case, get_token): with allure.step(发送登录请求): response send_request(case) with allure.step(校验状态码和业务码): assert response.status_code case[预期状态码]还可以把请求内容贴在报告里allure.attach(json.dumps(case, ensure_asciiFalse), name请求详情, attachment_typeallure.attachment_type.JSON)这样开发人员看到失败用例时不需要自己去翻日志报告里就有完整请求和返回。这个细节在很多团队里是“报告有没有人看”的分水岭。4. 实操过程与关键环节实现4.1 环境准备我建议所有项目都使用虚拟环境不要全局装依赖否则版本冲突会搞到你怀疑人生。在项目根目录执行python -m venv venv source venv/bin/activate # Windows 是 venv\Scripts\activate pip install -r requirements.txtrequirements.txt给出固定版本方便同事一键复现环境pytest8.3.2 allure-pytest2.13.5 requests2.32.3 openpyxl3.1.5这里的版本号只是参考实际安装时建议用pip freeze把你验证通过的版本锁下来。版本这东西有时候升级一个小版本就会引入行为变化尤其是pytest和allure-pytest之间的兼容性特别值得注意。安装完成后先验证两个命令正常pytest --version allure --version如果allure命令无法识别不要急着改代码大概率是 PATH 没配置好或者没装命令行工具。这一步通了后面才顺。4.2 框架代码实现我用一个最简单的登录接口来演示整个代码链路。首先是utils/http_client.py,把requests库再包一层统一处理超时、请求头拼接、日志输出import json import requests def send_request(case, token): url fhttps://api.example.com{case[接口路径]} method case[请求方法].upper() headers {} if 请求头 in case and case[请求头]: headers.update(case[请求头]) if token: headers.update(token) kwargs { headers: headers, timeout: 10, } if method GET: kwargs[params] case[请求参数] else: kwargs[json] case[请求参数] response requests.request(method, url, **kwargs) print(f[HTTP] {method} {url} - {response.status_code}) try: print([RESP] json.dumps(response.json(), ensure_asciiFalse)) except Exception: print([RESP] response.text) return response为什么要手工封装一层而不是直接用requests因为在接口自动化里你可能需要统一加日志、统一加签名、统一处理重试和 token 过期。如果每个用例都直接调用requests.post,那后期这些公共逻辑就没有地方可以插进去了。封装之后所有用例都走同一个出口改造的成本最低。然后是testcases/test_login.pyimport json import allure import pytest from utils.excel_reader import read_excel_cases from utils.http_client import send_request case_data read_excel_cases(data/login_cases.xlsx, login) allure.feature(登录模块) pytest.mark.parametrize(case, case_data, ids[c[用例编号] for c in case_data]) def test_login(case, get_token): allure.dynamic.title(f{case[用例编号]} {case[用例名称]}) with allure.step(发送请求): response send_request(case, get_token) with allure.step(断言状态码): assert response.status_code int(case[预期状态码]) resp_json response.json() with allure.step(断言业务码): assert resp_json.get(code) case[预期断言].get(code) allure.attach( json.dumps(resp_json, ensure_asciiFalse, indent2), name响应内容, attachment_typeallure.attachment_type.JSON )这里注意一个细节parametrize在模块导入时就已经把 Excel 读取执行了一次。如果你在测试执行前临时改了 Excel 数据需要重启 Pytest 进程才会生效这是正常现象不是代码 bug。4.3 执行与生成报告代码写好后执行pytestPytest 会自动读取pytest.ini,然后扫描testcases目录下的测试文件。执行结束后你会看到allure-results目录下生成了一堆 JSON 文件。这些 JSON 文件是 Allure 报告的“原材料”不要手动改动它们。接下来生成可视化报告allure generate allure-results -o report --clean allure open report-o report指定输出目录--clean是在生成前先清空旧的输出目录避免每次叠加产生混乱。allure open report会启动一个本地 Web 服务然后自动打开浏览器端口默认是 36888 附近如果被占用它会自动换一个。在 Jenkins 或者命令行环境里你只需要执行generate然后让 CI 把report目录作为 Artifact 保存下来这就和本地打开效果一样。执行完一次后你会发现pytest.ini里已经指定了--alluredir,所以生成命令可以简化成allure generate allure-results -o report --clean5. 常见问题排查与技巧实录5.1 pytest 相关用例收集不到是最常见的问题。你先检查文件名是不是test_*.py,测试函数是不是test_*,或者pytest.ini里的testpaths指向的目录不对。也许你在testcases目录下加了__init__.py,有时候它反而会限制测试文件被发现如果没有特殊需求就直接删掉。fixture 找不到也很常见。如果你在testcases下建了子目录而子目录下没有conftest.py那这个子目录里的用例是看不到全局 fixture 的。Pytest 的 fixture 查找顺序是从测试文件所在目录往上找所以全局conftest.py一般放在项目根目录子目录如果需要特殊 fixture就在子目录下再建一个conftest.py。不要在一个文件里堆一堆 fixture按模块拆分会更清晰。参数化用例名称中文乱码的问题我推荐测试报告里显示英文或编号。如果用例名称是中文搭配pytest4.0 以上版本在ids中传入中文其实问题不大但旧版本或 Windows 控制台编码不对时很可能乱码。真乱码了可以设置环境变量PYTHONIOENCODINGutf-8,或者在pytest.ini中加disable_test_id_escaping_and_forfeit_all_rights_to_committee_symmetry true这个参数有点绕一般用-vv也能看到被转义的中文本质上不影响执行。为了省事我的ids直接用英文或编号。5.2 Excel 数据驱动的坑Excel 文件格式兼容性。openpyxl只支持.xlsx不支持老式的.xls。很多人从旧系统里导出的用例表是.xls,直接脚本读取会报错或读到空内容。处理方式有两种用xlrd库配套读取.xls或者要求对方把文件另存为.xlsx我建议后者因为.xls终究是过去式。长数字被科学计数法。比如接口里有个很长的手机号或单号你打开 Excel 看到的是1.38018E10用openpyxl读出来也可能是一个科学计数法字符串或者被截断的数字。这需要你在写 Excel 时就规范把这类列设置成“文本”格式。如果已经坏了可以在read_excel_cases时单独处理比如检测到是 float 且位数很长就用格式化字符串恢复原来的值。但这个逻辑比较复杂最好还是治源头。Excel加载项被禁用、CtrlV 失效这些其实是办公软件环境问题如果你用openpyxl直接读取 Excel 文件和 Office 程序无关基本不会遇到。但如果你用了pywin32调用 Excel COM 去操作文件就可能触发加载项弹窗、粘贴失效等问题。我的建议是数据驱动场景里不要用 COM用openpyxl就够了它不依赖本机安装 Office在 Linux CI 上也毫发无损。公式和函数问题。还有人在 Excel 里写VLOOKUP、SUMIFS之类的函数来动态计算预期结果这虽然方便业务人员但openpyxl默认不会计算公式data_onlyTrue读取时如果文件没有缓存计算结果读出来的可能是None。所以我的原则是测试数据表格里尽量只放原始值不要用复杂公式。如果一定要用就确保文件用 Excel 打开保存过一次产生缓存值再让脚本读取。空行和合并单元格。Excel 里经常有空行或合并单元格。空行要跳过否则parametrize会把一堆None当成用例传进去。合并单元格在openpyxl里读合并区域时只有左上角有值其他单元格是None。所以我不会在用例表里用合并单元格如果非要展示分组可以在表头行用颜色而不是合并单元格。5.3 Allure 报告相关报告生成后是空白页。这种情况大部分是因为没有执行allure generate,或者打开的是allure-results目录里的 JSON 文件而不是report目录下的index.html。注意区分allure-results只是原始结果report才是最终页面。报告中没有用例详情。检查 pytest 执行时是否使用了allure-pytest插件。你可以用pytest --help看一眼有没有包含--alluredir如果没有说明插件没生效。很多时候是因为你全局装有多个 Python 环境pip install装到了一个环境执行pytest用的却是另一个环境的入口。解决办法是在虚拟环境里重新安装并确认which pytest指向的是venv下的路径。Allure 命令找不到或版本太低。Allure 命令行和allure-pytest插件是两码事插件负责生成 JSON命令行负责渲染 HTML。如果allure命令找不到参考前面环境搭建部分重新安装如果版本太低一些新的报告功能会缺失。检查allure --version即可。报告跑一次历史趋势里全是旧数据。那是因为allure-results没有清理干净。我在pytest.ini里加了--clean-alluredir执行 pytest 时就会先把目录清空再写新结果。如果你在pytest命令中手动传了--alluredir那就要记得也传--clean-alluredir,或者在allure generate时使用--clean总之二选一。6. 框架扩展与个人经验收尾这个框架虽然以 Excel 为核心但它并不死板。我在实际项目里后续主要扩展了这几个方向一是用例结果回写。执行完后用openpyxl把每条用例的执行状态、响应码、实际结果写回 Excel 的几列这样测试负责人打开 Excel 就能看到哪些用例挂了不需要去翻报告。只需要在pytest_sessionfinish钩子里读取记录结果并写入文件。二是对接 Jenkins 定时任务。在服务器上建一个测试任务定时执行pytest和allure generate再用 Jenkins 的 Allure 插件把report目录发布出去。开发每天早上到办公室打开 Jenkins 就能看到昨天的回归结果。这里要注意 Jenkins 工作目录下同样要安装 Python 依赖和 Allure 命令行排查问题时别在本地环境能跑、服务器上跑不了这种老坑里浪费时间。三是多环境切换。我习惯在config.yaml里配置 dev、test、pre 三套环境地址然后在conftest.py里通过一个环境变量比如TEST_ENVdev来决定用哪套地址。这样在跑不同环境回归时只需要改一个环境变量不需要改代码和 Excel。最后再分享一个个人心得Excel 驱动这套方案最舒服的阶段是 200 条用例以内。用例一旦超过几百条各种数据维护成本会快速上涨Excel 打开慢、多人同时改冲突、版本管理混乱的问题都会暴露。真到那一步可以考虑把数据迁移到 YAML 或数据库但整体框架的骨架不用变Pytest 和 Allure 依然是核心。我们团队从最开始 80 多条 Excel 用例一路跑到后面 900 多条用例这套框架从没因为数据量上去而推翻重来。所以说别迷信复杂工具先把手里的接口跑起来、报告看起来才是接口自动化最有价值的第一步。
做接口自动化测试这几年无论团队大小我最后都会把方案收敛到一套组合上Pytest Allure Excel。Pytest负责用例组织、用例过滤和测试夹具Allure把执行结果变成直观的测试报告Excel则用来维护接口地址、请求参数和预期结果。这套方案几乎不需要额外成本前两者是开源工具Excel是大家都熟悉的办公软件又解决了接口自动化里面最头疼的数据管理问题。这篇文章我不会给你普及基础概念而是直接讲一套可以落地的框架该怎么搭、代码怎么写、数据怎么管、报告怎么出包括我实际踩过的坑和排查思路希望你看完能直接抄作业。1. 项目思路与选型逻辑1.1 接口自动化要解决的三个核心问题接口自动化测试的本质不是“把手工用例变成代码”而是用机器执行来代替人肉回归。我见过太多团队一上来就写几百个测试函数最后用例是跑起来了但没人维护没人看报告也没人敢信这个结果。这套方案首先要解决的其实是三个问题第一是回归效率。接口改动频繁时手工回归一遍几十个接口可能要半天自动化可以在几分钟内跑完一遍并告诉你是哪里挂了。第二是数据维护。如果接口的URL、请求参数、预期结果散落在代码里那改一条数据就得改代码、提 PR、重新部署业务同学也帮不上忙。把测试数据抽到 Excel 之后普通同事也能看懂、能修改。第三是结果反馈。Pytest 跑完如果只是黑屏上一堆滚动日志根本没有意义。Allure 报告把每一步请求、返回、断言结果整理成可视化页面拿给开发看也有理有据。用生活里的例子理解接口是待体检的身体Excel 是体检项目清单Pytest 是体检中心执行流程的护士Allure 就是最后拿到的体检报告单。体检报告单好不好看、能不能一眼看出哪里出了问题直接决定了这套自动化能不能在团队里用起来。1.2 为什么选 Pytest Allure Excel而不是其他组合市面上做接口自动化的工具不少Postman Newman、JMeter、Python 自带的 unittest甚至一些测试平台产品都能干这事。但我为什么还是选 Pytest因为它把“灵活”和“功能”平衡得最好。unittest 虽然不用额外装但写起来啰嗦fixture测试夹具体系也远不如 Pytest 强大。Pytest 的pytest.mark.parametrize参数化可以很容易地和 Excel 行数据一一对应而conftest.py里的 fixture 可以统一管理登录态、数据库清理、环境切换这些准备工作这些能力对接口自动化来说是刚需。选 Allure 的理由更简单它能展示测试步骤、请求体、响应体、附件还能生成历史趋势、缺陷分类和 Flaky 测试信息。Pytest 原生输出只是一个文本终端Logging 或者 HTML 报告插件也可以但视觉和交互远不如 Allure。只需要在 pytest 命令行加一个--alluredir参数再执行一次allure generate就能得到一份适合发给团队看的 Web 报告。它也比 Jenkins 里的 HTML Publisher 插件更直观因为 Allure 本身就是按标准移动端和 Web 端报告习惯设计的。至于 Excel我知道很多技术朋友觉得它“土”但正是因为土业务人员才愿意维护。很多企业的接口测试数据就保存在 Excel 表格里需求评审的时候产品经理可以直接在旁边改。用openpyxl读取 Excel 也足够轻量不依赖 Office 环境。相比 YAML、JSON 文件Excel 最大的优势是表格结构清晰、筛选方便、任何人都能快速定位到某条用例去修改。而且现在也有pandas、pytest-excel这类库可以辅助但我觉得没必要过度封装直接用openpyxl读取反而更可控。2. 框架结构设计与数据流2.1 分层目录设计我搭这套框架时习惯按职责分成四层数据层、核心层、用例层、报告层。目录结构大致是这样的api_test_framework/ ├── data/ # 测试数据 │ ├── login_cases.xlsx │ ├── order_cases.xlsx │ └── config.yaml # 环境地址、账号等配置 ├── utils/ # 公共工具方法 │ ├── excel_reader.py # Excel 读取封装 │ ├── http_client.py # 请求封装 │ └── assertions.py # 断言工具 ├── testcases/ # 测试用例 │ ├── conftest.py # 本目录的 fixture │ ├── test_login.py │ └── test_order.py ├── report/ # Allure 报告输出目录 ├── allure-results/ # Pytest 执行生成的中间结果 ├── conftest.py # 全局 fixture ├── pytest.ini # Pytest 配置 └── requirements.txt为什么这么分层因为接口用例有一个很重要的特点测试步骤基本是雷同的无非是发送请求、拿响应、做断言。如果你每个测试函数都从头写一遍requests.get/post那后面改个公共请求头都会改到怀疑人生。所以要把请求封装起来把数据抽离出来用例层只剩薄薄一层逻辑。data目录放 Excel 文件和全局配置文件utils里放读取和请求工具testcases里放测试用例conftest.py控制测试环境准备。report和allure-results是生成时自动创建的一般会加进.gitignore不然每次跑完都会产生一堆临时文件污染仓库。2.2 用例数据流Excel - 用例 - 报告为什么很多教程里的 Pytest 接口自动化框架跑不起来因为他们只是把代码写出来了没有把数据流理清楚。我理解的这套框架数据流是这样的openpyxl从data/xxx.xlsx读取每一行用例每行代表一条完整用例字段包括用例编号、用例名称、接口路径、请求方法、请求头模板、请求参数、预期状态码、预期结果。pytest通过parametrize把每条数据变成一条测试用例用例名通常会拼接上编号这样在报告里能清楚看到是哪一行数据出了问题。用例执行时http_client负责发起请求并返回响应对象断言工具根据 Excel 里配置的预期值进行校验。执行完成后Pytest 把结果写入allure-results通过allure generate生成最终的 HTML 报告。这套数据流的好处是接口新增时只需要在 Excel 里加一行接口字段变了也只需要改 Excel 的某个单元格代码一行都不用动。最重要的是数据和代码分离之后Python 代码的复杂度和接口数量解耦了不管你加多少用例代码体积基本不变。3. 核心细节解析与实操要点3.1 pytest 配置与用例收集很多新手习惯在代码里写if __name__ __main__: pytest.main(),这样能用但团队协作时往往需要统一配置。我更推荐在项目根目录放一个pytest.ini把常用参数写死这样就可以直接敲pytest执行不用每次带参数[pytest] addopts -vs --alluredir./allure-results --clean-alluredir testpaths testcases python_files test_*.py python_classes Test* python_functions test_* log_cli true log_cli_level INFO这里面有几个参数值得说透。--alluredir./allure-results是让 Pytest 把执行结果写到allure-results目录--clean-alluredir是每次执行前清空上一次的结果避免报告里出现脏数据。testpaths指定扫描哪个目录python_files、python_classes、python_functions决定了 Pytest 识别哪些文件、类、函数才算测试用例。很多时候用例收集不到就是命名不符合这个规则。还有一个细节是log_cli true我建议在框架搭建阶段开起来。这样跑用例时你可以在控制台直接看到每个用例的执行过程排查问题比打开 Allure 报告快很多。等到真正接入 CI 稳定了再把这个关掉也不迟。conftest.py是 Pytest 的“主心骨”。全局conftest.py里放所有测试用例共用的 fixture例如登录后获取 token。如果你直接在每个测试用例里调用登录接口那几十条用例就会打几十次登录请求既浪费流量又影响执行速度。正确的做法是在conftest.py里定义一个session级别的 fixtureimport pytest import requests pytest.fixture(scopesession, autouseTrue) def get_token(): resp requests.post(https://api.example.com/login, json{username: admin, password: 123456}) assert resp.status_code 200 token resp.json()[data][token] print(f获取到 token: {token}) return {Authorization: fBearer {token}}这个 fixture 会在整个会话开始时执行一次然后测试函数通过参数名get_token自动获取返回值。如果你不想每个用例都手动声明这个参数可以设置autouseTrue,但要注意如果你在用例里又显式依赖了它作用域的逻辑一定要理清不然会出现 fixture 找不到的情况。3.2 Excel 数据读取与参数化Excel 驱动是整个框架里看似简单、实际最容易出问题的环节。核心思路是用openpyxl读取 Excel 的每一行转换成列表字典再丢给parametrize。Excel 用例表我一般先按模块拆分成多个 Sheet每个 Sheet 放同一业务线的接口。列结构大概是这样用例编号用例名称接口路径请求方法请求头请求参数预期状态码预期断言TC001正常登录/api/loginPOST{}{username:admin,password:123456}200{code:0}TC002密码错误/api/loginPOST{}{username:admin,password:wrong}200{code:1001}注意请求头和请求参数在 Excel 里最好存成 JSON 字符串。因为openpyxl读出来的是字符串直接丢给请求函数还需要解析。初始阶段你可以在读取时直接json.loads转换这样用例可读性最好。如果你非要把参数拆成很多列也可以但那样读取逻辑会更复杂而且 Excel 里多列合并成一个 dict 的代码写起来很啰嗦。下面是一个经过生产验证的读取函数import json from openpyxl import load_workbook def read_excel_cases(file_path, sheet_name): wb load_workbook(file_path, data_onlyTrue) ws wb[sheet_name] rows list(ws.iter_rows(values_onlyTrue)) # 第一行是表头 headers rows[0] cases [] for row in rows[1:]: # 跳过空行 if row[0] is None: continue row_dict dict(zip(headers, row)) # 把 JSON 字符串解析成 Python 对象 for col in (请求头, 请求参数, 预期断言): if col in row_dict and isinstance(row_dict[col], str): try: row_dict[col] json.loads(row_dict[col]) except json.JSONDecodeError: raise ValueError(f用例 {row_dict.get(用例编号)} 的 {col} 列不是合法 JSON) cases.append(row_dict) return cases这里有一个关键点load_workbook要带data_onlyTrue否则如果有单元格是用公式计算的读出来的是公式字符串而不是值。另一个容易踩的坑是 Excel 日期格式。如果你的用例里包含日期参数openpyxl默认会把它转成datetime对象或字符串这时建议统一在表头里写清楚格式读取时再str()或格式化。然后是在测试用例里使用参数化import json import pytest from utils.http_client import send_request from utils.excel_reader import read_excel_cases case_data read_excel_cases(data/login_cases.xlsx, login) pytest.mark.parametrize(case, case_data, ids[c[用例编号] for c in case_data]) def test_login_case(case, get_token): response send_request(case) assert response.status_code case[预期状态码] assert response.json().get(code) case[预期断言].get(code)ids参数很重要。如果不设置Allure 报告里显示的是case0、case1这种无意义的名字设置了之后报告里直接显示TC001,定位失败用例非常高效。3.3 Allure 报告集成与优化Allure 不是直接作为一个 Python 模块就能输出报告的。它分两部分一部分是 Pytest 插件allure-pytest负责把测试结果序列化成 JSON 文件另一部分是 Allure 命令行的可执行程序负责把 JSON 文件渲染成 HTML 页面。很多人都卡在第二步以为pip install allure-pytest就够了结果执行完发现没有allure命令。安装顺序建议是这样的pip install pytest allure-pytest requests openpyxl然后安装 Allure 命令行。你可以去 GitHub 官方 Releases 下载最新版压缩包解压后将bin目录加入系统 PATH。也可以用系统包管理器安装macOS 上是brew install allure,Windows 上用scoop install allure。注意 Allure 是基于 Java 的工具即使你已经能运行allure --version,也要确保本机有 JRE 1.8 以上环境否则生成报告时可能会直接报错。在测试函数上添加一些 Allure 装饰器可以让报告更专业import allure allure.feature(登录模块) allure.story(正确密码登录) allure.title(用例 TC001正常登录) def test_login_case(case, get_token): with allure.step(发送登录请求): response send_request(case) with allure.step(校验状态码和业务码): assert response.status_code case[预期状态码]还可以把请求内容贴在报告里allure.attach(json.dumps(case, ensure_asciiFalse), name请求详情, attachment_typeallure.attachment_type.JSON)这样开发人员看到失败用例时不需要自己去翻日志报告里就有完整请求和返回。这个细节在很多团队里是“报告有没有人看”的分水岭。4. 实操过程与关键环节实现4.1 环境准备我建议所有项目都使用虚拟环境不要全局装依赖否则版本冲突会搞到你怀疑人生。在项目根目录执行python -m venv venv source venv/bin/activate # Windows 是 venv\Scripts\activate pip install -r requirements.txtrequirements.txt给出固定版本方便同事一键复现环境pytest8.3.2 allure-pytest2.13.5 requests2.32.3 openpyxl3.1.5这里的版本号只是参考实际安装时建议用pip freeze把你验证通过的版本锁下来。版本这东西有时候升级一个小版本就会引入行为变化尤其是pytest和allure-pytest之间的兼容性特别值得注意。安装完成后先验证两个命令正常pytest --version allure --version如果allure命令无法识别不要急着改代码大概率是 PATH 没配置好或者没装命令行工具。这一步通了后面才顺。4.2 框架代码实现我用一个最简单的登录接口来演示整个代码链路。首先是utils/http_client.py,把requests库再包一层统一处理超时、请求头拼接、日志输出import json import requests def send_request(case, token): url fhttps://api.example.com{case[接口路径]} method case[请求方法].upper() headers {} if 请求头 in case and case[请求头]: headers.update(case[请求头]) if token: headers.update(token) kwargs { headers: headers, timeout: 10, } if method GET: kwargs[params] case[请求参数] else: kwargs[json] case[请求参数] response requests.request(method, url, **kwargs) print(f[HTTP] {method} {url} - {response.status_code}) try: print([RESP] json.dumps(response.json(), ensure_asciiFalse)) except Exception: print([RESP] response.text) return response为什么要手工封装一层而不是直接用requests因为在接口自动化里你可能需要统一加日志、统一加签名、统一处理重试和 token 过期。如果每个用例都直接调用requests.post,那后期这些公共逻辑就没有地方可以插进去了。封装之后所有用例都走同一个出口改造的成本最低。然后是testcases/test_login.pyimport json import allure import pytest from utils.excel_reader import read_excel_cases from utils.http_client import send_request case_data read_excel_cases(data/login_cases.xlsx, login) allure.feature(登录模块) pytest.mark.parametrize(case, case_data, ids[c[用例编号] for c in case_data]) def test_login(case, get_token): allure.dynamic.title(f{case[用例编号]} {case[用例名称]}) with allure.step(发送请求): response send_request(case, get_token) with allure.step(断言状态码): assert response.status_code int(case[预期状态码]) resp_json response.json() with allure.step(断言业务码): assert resp_json.get(code) case[预期断言].get(code) allure.attach( json.dumps(resp_json, ensure_asciiFalse, indent2), name响应内容, attachment_typeallure.attachment_type.JSON )这里注意一个细节parametrize在模块导入时就已经把 Excel 读取执行了一次。如果你在测试执行前临时改了 Excel 数据需要重启 Pytest 进程才会生效这是正常现象不是代码 bug。4.3 执行与生成报告代码写好后执行pytestPytest 会自动读取pytest.ini,然后扫描testcases目录下的测试文件。执行结束后你会看到allure-results目录下生成了一堆 JSON 文件。这些 JSON 文件是 Allure 报告的“原材料”不要手动改动它们。接下来生成可视化报告allure generate allure-results -o report --clean allure open report-o report指定输出目录--clean是在生成前先清空旧的输出目录避免每次叠加产生混乱。allure open report会启动一个本地 Web 服务然后自动打开浏览器端口默认是 36888 附近如果被占用它会自动换一个。在 Jenkins 或者命令行环境里你只需要执行generate然后让 CI 把report目录作为 Artifact 保存下来这就和本地打开效果一样。执行完一次后你会发现pytest.ini里已经指定了--alluredir,所以生成命令可以简化成allure generate allure-results -o report --clean5. 常见问题排查与技巧实录5.1 pytest 相关用例收集不到是最常见的问题。你先检查文件名是不是test_*.py,测试函数是不是test_*,或者pytest.ini里的testpaths指向的目录不对。也许你在testcases目录下加了__init__.py,有时候它反而会限制测试文件被发现如果没有特殊需求就直接删掉。fixture 找不到也很常见。如果你在testcases下建了子目录而子目录下没有conftest.py那这个子目录里的用例是看不到全局 fixture 的。Pytest 的 fixture 查找顺序是从测试文件所在目录往上找所以全局conftest.py一般放在项目根目录子目录如果需要特殊 fixture就在子目录下再建一个conftest.py。不要在一个文件里堆一堆 fixture按模块拆分会更清晰。参数化用例名称中文乱码的问题我推荐测试报告里显示英文或编号。如果用例名称是中文搭配pytest4.0 以上版本在ids中传入中文其实问题不大但旧版本或 Windows 控制台编码不对时很可能乱码。真乱码了可以设置环境变量PYTHONIOENCODINGutf-8,或者在pytest.ini中加disable_test_id_escaping_and_forfeit_all_rights_to_committee_symmetry true这个参数有点绕一般用-vv也能看到被转义的中文本质上不影响执行。为了省事我的ids直接用英文或编号。5.2 Excel 数据驱动的坑Excel 文件格式兼容性。openpyxl只支持.xlsx不支持老式的.xls。很多人从旧系统里导出的用例表是.xls,直接脚本读取会报错或读到空内容。处理方式有两种用xlrd库配套读取.xls或者要求对方把文件另存为.xlsx我建议后者因为.xls终究是过去式。长数字被科学计数法。比如接口里有个很长的手机号或单号你打开 Excel 看到的是1.38018E10用openpyxl读出来也可能是一个科学计数法字符串或者被截断的数字。这需要你在写 Excel 时就规范把这类列设置成“文本”格式。如果已经坏了可以在read_excel_cases时单独处理比如检测到是 float 且位数很长就用格式化字符串恢复原来的值。但这个逻辑比较复杂最好还是治源头。Excel加载项被禁用、CtrlV 失效这些其实是办公软件环境问题如果你用openpyxl直接读取 Excel 文件和 Office 程序无关基本不会遇到。但如果你用了pywin32调用 Excel COM 去操作文件就可能触发加载项弹窗、粘贴失效等问题。我的建议是数据驱动场景里不要用 COM用openpyxl就够了它不依赖本机安装 Office在 Linux CI 上也毫发无损。公式和函数问题。还有人在 Excel 里写VLOOKUP、SUMIFS之类的函数来动态计算预期结果这虽然方便业务人员但openpyxl默认不会计算公式data_onlyTrue读取时如果文件没有缓存计算结果读出来的可能是None。所以我的原则是测试数据表格里尽量只放原始值不要用复杂公式。如果一定要用就确保文件用 Excel 打开保存过一次产生缓存值再让脚本读取。空行和合并单元格。Excel 里经常有空行或合并单元格。空行要跳过否则parametrize会把一堆None当成用例传进去。合并单元格在openpyxl里读合并区域时只有左上角有值其他单元格是None。所以我不会在用例表里用合并单元格如果非要展示分组可以在表头行用颜色而不是合并单元格。5.3 Allure 报告相关报告生成后是空白页。这种情况大部分是因为没有执行allure generate,或者打开的是allure-results目录里的 JSON 文件而不是report目录下的index.html。注意区分allure-results只是原始结果report才是最终页面。报告中没有用例详情。检查 pytest 执行时是否使用了allure-pytest插件。你可以用pytest --help看一眼有没有包含--alluredir如果没有说明插件没生效。很多时候是因为你全局装有多个 Python 环境pip install装到了一个环境执行pytest用的却是另一个环境的入口。解决办法是在虚拟环境里重新安装并确认which pytest指向的是venv下的路径。Allure 命令找不到或版本太低。Allure 命令行和allure-pytest插件是两码事插件负责生成 JSON命令行负责渲染 HTML。如果allure命令找不到参考前面环境搭建部分重新安装如果版本太低一些新的报告功能会缺失。检查allure --version即可。报告跑一次历史趋势里全是旧数据。那是因为allure-results没有清理干净。我在pytest.ini里加了--clean-alluredir执行 pytest 时就会先把目录清空再写新结果。如果你在pytest命令中手动传了--alluredir那就要记得也传--clean-alluredir,或者在allure generate时使用--clean总之二选一。6. 框架扩展与个人经验收尾这个框架虽然以 Excel 为核心但它并不死板。我在实际项目里后续主要扩展了这几个方向一是用例结果回写。执行完后用openpyxl把每条用例的执行状态、响应码、实际结果写回 Excel 的几列这样测试负责人打开 Excel 就能看到哪些用例挂了不需要去翻报告。只需要在pytest_sessionfinish钩子里读取记录结果并写入文件。二是对接 Jenkins 定时任务。在服务器上建一个测试任务定时执行pytest和allure generate再用 Jenkins 的 Allure 插件把report目录发布出去。开发每天早上到办公室打开 Jenkins 就能看到昨天的回归结果。这里要注意 Jenkins 工作目录下同样要安装 Python 依赖和 Allure 命令行排查问题时别在本地环境能跑、服务器上跑不了这种老坑里浪费时间。三是多环境切换。我习惯在config.yaml里配置 dev、test、pre 三套环境地址然后在conftest.py里通过一个环境变量比如TEST_ENVdev来决定用哪套地址。这样在跑不同环境回归时只需要改一个环境变量不需要改代码和 Excel。最后再分享一个个人心得Excel 驱动这套方案最舒服的阶段是 200 条用例以内。用例一旦超过几百条各种数据维护成本会快速上涨Excel 打开慢、多人同时改冲突、版本管理混乱的问题都会暴露。真到那一步可以考虑把数据迁移到 YAML 或数据库但整体框架的骨架不用变Pytest 和 Allure 依然是核心。我们团队从最开始 80 多条 Excel 用例一路跑到后面 900 多条用例这套框架从没因为数据量上去而推翻重来。所以说别迷信复杂工具先把手里的接口跑起来、报告看起来才是接口自动化最有价值的第一步。
