Python+requests+unittest+Excel：打造数据驱动的接口自动化测试框架

做接口测试头两年，我一直在“脚本泥潭”里打转。今天这个接口的字段加了个必填项，明天那个服务的返回结构调整了，手工写的测试脚本跟着改一改没问题，但一旦用例上了几十条、几百条，脚本的维护成本直接冲上天。后来在某个业务系统的回归测试里，我把接口自动化方案收敛成了Python + requests + unittest + excel这套组合，磕磕绊绊跑了一年多，算是把“脚本难维护、数据难管理、结果难汇报”这几个老大难逐一按住了。

这篇文章就把这套框架从设计思路、用例表结构、核心代码到持续集成落地、还有踩过的坑，完整拆开讲清楚。适合已经从 postman 手工调试过渡到需要批量回归、但又不想一上来就上 pytest + yaml 那种重框架的测试同学，也适合想把自己的脚本整理成“数据驱动”形态的开发者参考。

1. 这套组合为什么值得选：requests+unittest+excel 的取舍逻辑

很多人一上来会问：现在网上铺天盖地都是 pytest + yaml 或者 pytest + allure 的方案，为什么还要用 unittest + excel？这不是开倒车吗？我自己用下来的体会是：技术选型没有绝对好坏，只有合不合适。这套组合在一个以功能测试为主、自动化基础薄弱的团队里，落地阻力最小，交付速度最快。

1.1 三个组件各自解决了什么问题

先把三个角色拆开看：

• requests解决的是“怎么发请求”。它的 API 设计简洁，session 会话保持、超时控制、重试策略、文件上传、代理配置这些常用能力都有现成实现，二三十行代码就能封装出一个好用的 HTTP 客户端。相比直接拿 Postman 导出的代码片段，requests 给了我们足够的自由度去统一处理请求头和认证信息。

• unittest解决的是“用例怎么组织、怎么执行、怎么汇总”。它是 Python 标准库自带的测试框架，不需要额外装包，天然支持测试固件（setUp/tearDown）、测试套件（TestSuite）、测试结果收集（TestResult）。虽然它的执行方式没有 pytest 那么花哨，但胜在稳定、零依赖、团队里随便一个会 Python 的人都能上手改。

• excel解决的是“测试数据放在哪里、由谁来维护”。对测试团队来说，excel 是几乎零学习成本的载体。产品经理、开发、测试之间传接口文档用的也是表格，把用例直接放在 excel 里，意味着用例的设计者和执行者可以是两拨人：懂业务的人填表，懂代码的人维护框架。这一点在团队协作里价值很大。

1.2 为什么不选 yaml，不选 pytest

我先说清楚，不是这些方案不好，而是它们对应的使用场景不同。yaml 的可读性确实好，但多级缩进和类型转换对不熟悉技术的人并不友好，测试人员填错一个缩进，整个文件解析就挂了，定位成本反而高。pytest 的 fixture 和插件生态非常强大，但它的灵活性也意味着更高的学习曲线，团队里大多数成员连装饰器都是现学现用的时候，pytest 的方案反而容易把框架写成一堆“只有作者看得懂”的代码。

我当时的取舍标准就三条：

1. 团队成员能在一天内理解用例编写规则；
2. 新增一个接口用例，不需要动框架代码；
3. 回归执行和结果输出，能在一条命令内完成。

unittest + excel 恰好能同时满足这三条。等团队整体水平上来了，再把执行层从 unittest 迁移到 pytest，用例数据层不用大动，这个演进路径也是顺的。

1.3 框架的目录结构与职责分层

最终搭出来的目录形如：

api_test_framework/ ├── config/ │ ├── config.py # 全局配置：域名、超时、重试次数 │ ├── log_config.py # 日志配置 ├── data/ │ ├── cases/ │ │ └── user_module.xlsx # 模块化用例文件 │ ├── config.xlsx # 环境变量表：token、id 等全局变量 ├── utils/ │ ├── excel_reader.py # 读取 Excel 用例 │ ├── http_client.py # requests 的会话封装 │ ├── assert_utils.py # 断言工具 │ └── variable_store.py # 依赖数据存储与替换 ├── testcases/ │ ├── base_case.py # 测试基类，封装通用执行流程 │ └── test_runner.py # 动态生成 unittest 用例并执行 ├── reports/ │ ├── html_report/ # HTML 测试报告 │ └── logs/ # 运行日志 └── main.py # 启动入口

整个框架从职责上划分为四层：数据层（excel 用例、配置文件）、核心层（requests 封装、断言工具、变量存储）、执行层（unittest 基类与用例生成器）、展示层（测试报告与日志）。每一层在自己的边界内做事，互不越界，这也是后续维护时改动范围可控的根本原因。

2. Excel 用例表设计：字段拆分、场景表达与数据驱动规则

数据驱动框架的灵魂不在代码，而在用例表的结构设计。一个设计良好的用例表，应该能让一个完全不懂代码的功能测试同事，看着表头就能写出可执行的接口用例。这块我反复调整过几版，最终沉淀下来的字段和规则如下。

2.1 用例表字段说明与设计理由

几个容易被忽略的细节：

• headers 和 json 用 JSON 字符串存，读取时统一json.loads解析。这样单元格里能直接粘请求体片段，比拆成多个字段灵活得多。
• expected_code 必填但允许填多个值，比如200,201，框架会按逗号切分后判断，适配“创建类接口返回 201，部分服务又返回 200”这种差异场景。
• extract 字段的格式我用的是变量名 = JSONPath表达式，用等号分隔。注意这里不要用空格作为分隔符，否则变量名里一掺特殊字符，解析代码会写得很痛苦。

2.2 单接口用例与链路用例的两种表达方式

很多接口不是孤立的，B 接口需要 A 接口返回的 token，C 接口又要用到 B 接口产生的订单号。在 excel 里怎么表达这种依赖关系？我最终采用了“depends_on + extract + 占位符”三种机制配合。

单接口用例是最简单的情况，只需要在表格里把请求参数、期望断言填好即可。链路用例则多出三步：

1. 在depends_on里填上前置用例 ID，执行引擎会先跑前置用例；
2. 在前置用例的extract里把需要传递的字段提取为变量；
3. 在后置用例的json或其他字段里，用{{变量名}}占位符引用。

例如注册到登录再到查询用户信息这条链路：

case_id: user_register_001 method: POST url: /api/v1/register json: {"username": "{{global.username}}", "password": "{{global.password}}"} extract: user_id = $.data.id expected_code: 200 case_id: user_login_001 depends_on: user_register_001 method: POST url: /api/v1/login json: {"username": "{{global.username}}", "password": "{{global.password}}"} extract: token = $.data.token expected_code: 200 case_id: user_info_001 depends_on: user_login_001 method: GET url: /api/v1/user/{{user_id}} headers: {"Authorization": "Bearer {{token}}"} expected_code: 200 expected_jsonpath: $.data.user_id assert_type: equal expected_value: "{{user_id}}"

注意第三个用例，url 里的{{user_id}}引用的不是 global 变量，而是user_register_001里 extract 出来的变量。变量名在整个执行上下文里保持全局可用，但depends_on保证了变量产生的时序：先跑前置用例，再执行当前用例，所以引用顺序不会乱。

2.3 断言设计的几种常用场景

断言不能只停留在“状态码对不对”，否则接口返回 200 但内部报错的“假绿”会坑死人。这套框架里我实现了四种断言类型，基本覆盖了日常接口测试的绝大多数场景：

更复杂的断言，比如“数组里的每个元素都包含某字段”“响应时间小于 500ms”，excel 里表达会变得别扭。遇到这种复杂断言，我的处理方式是在assert_type里留一个custom值，框架会去调用代码里预先注册的钩子函数。也就是说，常规断言数据驱动，特殊断言代码兜底，两条路都通。

3. 核心代码骨架：读表、动态生成用例、请求封装与断言实现

这一章上代码。因为框架的所有执行逻辑都集中在几个文件里，我把它们分别拆开讲，并说明每一段的用意。

3.1 读取 Excel：用 openpyxl 还是 xlrd

读取 excel 我一共试过两轮。第一轮用的 xlrd，发现新版 xlrd 对 .xlsx 格式支持有限，后来又切到 openpyxl，稳定至今。openpyxl 我用下来有三个好处：支持.xlsx格式、读取公式结果时开启data_only=True可以直接拿单元格缓存值、行和列的操作 API 比较顺手。

# utils/excel_reader.py from openpyxl import load_workbook def read_excel_cases(file_path, sheet_name=None): """ 读取 Excel 用例文件，返回用例字典列表 :param file_path: excel 文件路径 :param sheet_name: 工作表名，默认取第一个 sheet """ wb = load_workbook(file_path, data_only=True) ws = wb[sheet_name] if sheet_name else wb.active headers = [cell.value for cell in ws[1]] case_list = [] for row in ws.iter_rows(min_row=2, values_only=True): # 跳过完全为空的行 if not any(row): continue case = dict(zip(headers, row)) # 去掉值为 None 的字段，避免后续读取时报错 case = {k: v for k, v in case.items() if v is not None} case_list.append(case) return case_list

这里有个细节：第一行表头里如果有多余空格，比如“ case_id”和“case_id”，会让字典 key 不一致。我处理的办法是在读取后统一做一次strip：

headers = [str(cell.value).strip() if cell.value else "" for cell in ws[1]]

很多诡异的问题，最后查出来都是表头多了一个空格，这属于经验教训了。

3.2 requests 封装：会话保持、重试与超时统一处理

requests 用法简单，但直接在各处裸写 requests.get、requests.post 不行——一旦需要调整超时时间、加日志、加认证信息，你会改到怀疑人生。所以必须封装一个全局唯一的 HTTP 客户端。

# utils/http_client.py import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry from utils.log_utils import get_logger logger = get_logger("http_client") class HttpClient: """基于 requests.Session 的封装，全局共用同一个 session""" def __init__(self, base_url, timeout=10, retry_times=2): self.timeout = timeout self.base_url = base_url self.session = requests.Session() # 配置重试策略：针对连接错误和部分 5xx 状态码自动重试 retry_strategy = Retry( total=retry_times, backoff_factor=1, # 第一次重试等待 1s，之后指数递增 status_forcelist=[500, 502, 503, 504], allowed_methods=["GET", "POST", "PUT", "DELETE", "PATCH"], ) adapter = HTTPAdapter(max_retries=retry_strategy) self.session.mount("http://", adapter) self.session.mount("https://", adapter) def _log_request(self, method, url, **kwargs): logger.info(f"[REQ] {method} {url} params={kwargs.get('params')} " f"headers={kwargs.get('headers')} body={kwargs.get('json') or kwargs.get('data')}") def _log_response(self, resp, cost_ms): logger.info(f"[RESP] status={resp.status_code} cost_ms={cost_ms} " f"body={resp.text[:500]}") def request(self, method, path, **kwargs): url = path if path.startswith("http") else self.base_url + path kwargs.setdefault("timeout", self.timeout) self._log_request(method, url, **kwargs) start = time.time() resp = self.session.request(method, url, **kwargs) cost_ms = int((time.time() - start) * 1000) resp.cost_ms = cost_ms self._log_response(resp, cost_ms) return resp def get(self, path, **kwargs): return self.request("GET", path, **kwargs) def post(self, path, **kwargs): return self.request("POST", path, **kwargs) # put / delete / patch 方法同理

重试这一层很容易被忽略。我在实际回归里碰到过运维发布期间偶发 502 的情况，如果没有重试，一个非功能性的瞬断就能让整个自动化任务失败。加了重试之后，case 还是那个 case，稳定性提升非常明显。不过要注意，重试只适合幂等接口，如果接口本身会产生订单、扣减库存等不可重复操作，要避免自动重试。

3.3 动态生成 unittest 用例：绕过手工写测试方法的限制

unittest 的常规写法是在类里写test_xxx方法，但用例都在 excel 里，总不能靠代码生成器把每个 excel 行写成一段 test 方法。这里核心技巧是用 Python 的type()函数和setattr动态构造测试类。

# testcases/base_case.py import unittest from utils.http_client import HttpClient from utils.excel_reader import read_excel_cases from utils.assert_utils import AssertionUtils from utils.variable_store import VariableStore class BaseApiCase(unittest.TestCase): """所有用例的基类，封装公共执行流程""" def __init__(self, case: dict, *args, **kwargs): self.case = case self.http_client = None self.assert_util = AssertionUtils() self.variable_store = None super().__init__(*args, **kwargs) def setUp(self): config = self._get_config() self.http_client = HttpClient(config["base_url"], timeout=config.get("timeout", 10)) self.variable_store = VariableStore(config.get("global_vars", {})) # 先执行依赖用例，保证数据就绪 self._run_dependencies() def execute_case(self): case = self.case # 替换占位符、发送请求、断言、提取变量 ...

基类里真正跑用例的逻辑长这样：

def _execute(self): case = self.case # 1. 变量替换：把 json/url/headers 里的 {{xx}} 替换成运行时值 method = case["method"] url = self.variable_store.replace(str(case["url"])) headers = self.variable_store.replace_json_str(case.get("headers", "{}")) params = self.variable_store.replace_json_str(case.get("params", "{}")) body = self.variable_store.replace_json_str(case.get("json", "{}")) # 2. 发送请求 resp = self.http_client.request(method, url, params=params, json=body, headers=headers) # 3. 断言 self._do_assert(case, resp) # 4. 提取变量：供同一会话后续用例使用 self._do_extract(case, resp)

接下来是关键的一步——根据 excel 行生成 unittest 测试类。

# testcases/test_runner.py import unittest from testcases.base_case import BaseApiCase def build_test_class(suite_name, cases): """根据用例数据动态构建一个 unittest.TestCase 子类""" attrs = {"_suite_name": suite_name} for index, case in enumerate(cases): if case.get("is_run") == 0: continue def _make_test_case(c): def test_case(self): self.case = c self._execute() test_case.__doc__ = f"{c.get('case_id')} {c.get('case_name')}" return test_case # 动态生成 test_case_001_xxx 方法名 test_method_name = f"test_case_{index + 1:03d}_{_safe_name(case.get('case_name', 'case'))}" attrs[test_method_name] = _make_test_case(case) return type(suite_name, (BaseApiCase,), attrs)

动态生成后，直接塞进 unittest.TestSuite 就行：

def load_all_suites(excel_files): suite = unittest.TestSuite() for file_path in excel_files: cases = read_excel_cases(file_path) # 按 module 字段分组，一个 module 对应一个测试类 module_groups = {} for case in cases: module_groups.setdefault(case.get("module", "default"), []).append(case) for module_name, module_cases in module_groups.items(): test_class = build_test_class(f"Test{module_name.title()}", module_cases) # 注意：动态类不会在 import 时被 loader 发现，必须手动加载 suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(test_class)) return suite

这里有一个特别容易踩的坑：unittest 的默认加载器只扫描模块里 import 进来的 TestCase 子类，动态 type() 创建的类不会自动被发现，所以不能直接交给unittest.main()，而是要走loadTestsFromTestCase手动加载。我在第一次跑框架时，动态类明明生成了，测试结果却一直是 0 用例，问题就出在这里。

3.4 断言与变量提取：让用例之间真正“串”起来

断言的实现要支持前面表格里的四种类型，还要把失败信息打印到足够详细，方便定位。我见过太多断言失败但只给一句“断言失败”的报告，查问题全靠猜。我自己的 AssertionUtils 会同时打印“期望值、实际值、响应体、请求体”，把上下文信息一次拉满。

# utils/assert_utils.py import json class AssertionUtils: def do_assert(self, case, resp): expected_code = str(case.get("expected_code", "")).split(",") if expected_code and str(resp.status_code) not in expected_code: raise AssertionError( f"状态码不符 期望={expected_code} 实际={resp.status_code}\n" f"响应内容={resp.text[:1000]}" ) assert_type = case.get("assert_type", "") if not assert_type: return if assert_type == "equals": actual = self._extract_value(resp, case["expected_jsonpath"]) expected = self.variable_store.replace(str(case["expected_value"])) if str(actual) != str(expected): raise AssertionError( f"值断言失败 jsonpath={case['expected_jsonpath']} " f"期望={expected} 实际={actual}\n响应={resp.text[:1000]}" ) elif assert_type == "contains": if case["expected_keyword"] not in resp.text: raise AssertionError( f"关键字断言失败 期望包含={case['expected_keyword']}\n响应={resp.text[:1000]}" ) # 其他类型同理省略

变量提取的代码要注意区分 JSONPath 和正则。我主要用 JSONPath 提取接口返回字段，偶尔也用正则提取响应头里的值。

# utils/variable_store.py import re import json class VariableStore: def __init__(self, global_vars=None): self._store = dict(global_vars or {}) def set(self, name, value): self._store[name] = value def get(self, name): return self._store.get(name) def replace(self, text): """把 {{变量名}} 替换成变量值""" if not text: return text def repl(match): var_name = match.group(1) if var_name in self._store: return str(self._store[var_name]) return match.group(0) return re.sub(r"\{\{(\w+)\}\}", repl, text) def replace_json_str(self, json_str): """先替换占位符，再解析 JSON，同时兼容空字符串""" if not json_str: return {} replaced = self.replace(json_str) return json.loads(replaced)

这里有个设计细节：replace_json_str是先替换占位符再json.loads，还是先 loads 再遍历替换？我选的先替换再 loads，因为占位符会出现在字符串值里，如果先 loads，{{user_id}}在原始 JSON 里就是一个普通字符串，替换时反而要递归遍历字典，代码会更绕。先替换的坏处是，如果某个变量值是特殊字符，比如包含双引号，替换后会导致 JSON 解析失败。实际项目中我给变量值做了一层转义，用json.dumps(value)[1:-1]处理后再插入，能避免大多数问题。

4. 测试报告、日志归档和持续集成接入

框架能跑通只是第一步，真正让测试工作“可交付”的，是报告和日志这两块。一个晚上自动跑完的接口回归，第二天早上团队需要的是一份“哪些接口挂、为什么挂、挂之前发生了什么”的清晰记录，而不是一个黑盒。

4.1 我整理 HTML 报告时踩过的坑

unittest 内置的 TextTestRunner 输出的纯文本报告太简陋，也不方便给非技术同事看。为了出 HTML 报告，我试过引入第三方 HTMLTestRunner，但它对 Python 3 的支持有些年代感，动态生成的用例名称一长，报告就显示得歪歪扭扭。最后我改用了自己生成的 HTML 模板，只保留四块核心信息：

• 用例执行汇总：总用例数、通过数、失败数、错误数、耗时；
• 失败用例详情：展开后能看到请求方法、URL、请求头、请求体、响应体、断言期望值；
• 每个模块的执行时间条形图；
• 按用例 ID 排序，方便和缺陷管理系统里的编号对应。

报告生成逻辑不复杂，核心就是遍历 unittest 的 TestResult，把每个用例的通过/失败信息收集起来，渲染成 HTML。如果团队已经在用 Allure，也可以把执行结果转成 Allure 数据结构，但我自己更偏向轻量的 HTML 报告，因为不需要额外部署服务，开箱即用。

4.2 日志怎么打才能快速定位问题

日志是排查问题的重要依据。我的日志库配置里，默认同时输出到控制台和文件，文件按天滚动，保留最近 15 天。

一个值得分享的经验是：请求日志和响应日志必须成对出现，并且要带上同一个关联 ID。我在 HttpClient 里给每次请求生成一个简短的request_id，格式类似于req_20250114_152030_abc，日志里请求和响应都带上这个 ID。当某个用例失败时，直接搜索这个 ID，就能把“请求发出的参数、服务端返回的内容、耗时多久”完整串起来。如果没有这个关联 ID，多线程跑用例时日志混在一起，找一条请求的上下文能把人折磨死。

失败用例的明细我还会额外输出到一个 markdown 文件里，方便直接粘贴到缺陷单。这个动作看似简单，但团队提缺陷的效率提高了一大截，因为开发同学拿到的信息足够完整，不会再出现“请提供原始请求”这种来回拉扯。

4.3 定时任务与持续集成接入

框架本身提供了 main.py 入口，单机环境下用系统自带的任务计划程序定时执行即可。但真正的可持续运行，一般还是要挂到 CI 平台上去。我的做法是：

• 用一条命令触发：python main.py --env production
• CI 流水线里设两步：先执行测试，再上传 HTML 报告；
• 失败状态与消息通知联动，比如飞书/钉钉群里推送失败摘要；
• 失败策略分为两种：如果失败率小于阈值（比如 2%），任务标为“不稳定”，不阻塞流水线；如果超过阈值，标记为失败并触发告警。

这里我想提醒一个反直觉的点：定时任务里不要一失败就重跑整个套件。看上去重跑能避开偶发环境问题，但也会掩盖真实的稳定性缺陷。正确做法是保留失败现场（日志 + 响应），由人工判定是环境问题还是代码问题，再针对性处理。自动化测试的价值在于持续暴露问题，而不是制造一片大绿。

5. 实际踩过的坑：Excel 驱动框架的边界与常见问题

最后这部分聊几个我在这套框架上实打实踩过坑的地方，有的坑很蠢，但影响很隐蔽，希望能帮你省点排查时间。

5.1 Excel 本身带来的那几个经典坑

坑一：数字被自动转成其他类型。excel 单元格里如果填的是001，openpyxl 读出来可能是字符串"001"也可能是数字1，取决于单元格格式。这会导致传给接口的参数跟预期不一致。我的规避方式是在用例表里统一把 ID、数量这类字段格式化成文本，并在读取逻辑里对特定列做一次强转。

坑二：单元格里的换行和不可见字符。从网页上复制 JSON 片段进 excel，经常夹带连续空格、全角逗号、换行符。直接json.loads大概率报错。我在 excel_reader 里加了一步清洗函数：

import re def clean_cell(value): if isinstance(value, str): value = value.replace("\r", "").replace("\n", "").replace("\u00a0", " ") value = re.sub(r"[ \t]+", " ", value).strip() return value

全角逗号这种问题清洗不了，但至少排除了换行和不可见字符两大类。

坑三：用例顺序。excel 里行顺序就是执行顺序，但 unittest 执行顺序是按方法名排序的，动态生成的方法名里我加了index + 1的三位数字前缀，保证跟 excel 行顺序一致。如果不用前缀，测试方法会变成按字母序执行，依赖关系的用例顺序就会错乱。

5.2 数据驱动模式的边界：什么时候这套方案开始吃力

Excel 驱动的路由很清晰，但它不是银弹。当你的用例规模超过一定量级之后，问题会逐渐暴露：

• 用例文件体积过大：上万个用例放在一个 sheet 里，excel 本身会卡顿，读取也会变慢，需要拆成多个文件，维护成本随之上升。
• 复杂的加密签名逻辑：某些接口请求体需要先做 RSA 加签或时间戳签名，这种逻辑不适合放在 excel 里表达，只能在代码层写钩子。框架需要为这类用例留扩展点。
• 并发执行需求：Excel 驱动的用例天然是串行的。虽然可以用多线程按模块跑，但全局变量存储和依赖关系在并发场景下会互相干扰，需要重新设计。我目前只在模块内部串行、模块之间并行的级别上做过优化，再往上的并发就得切换框架形态了。

如果团队发展到需要原生支持优先级调度、标签筛选、多环境并行、海量用例管理，我会建议逐步迁移到 pytest + yaml 的方案，但用例数据本身从 excel 导出成 yaml 是可行的，代码执行层替换掉即可，重心还是业务用例设计。

5.3 一个小技巧：调试模式

最后分享一个让日常调试舒服很多的技巧。我在 main.py 里加了一个--debug参数。当这个参数被设置时，框架会跳过 unittest 的运行器，而是直接遍历用例，逐条执行并打印详细过程，遇到失败也不中断，相当于一个“带断点的纯手工模式”。

# main.py 片段 import argparse from testcases.test_runner import load_all_suites def main(): parser = argparse.ArgumentParser() parser.add_argument("--env", default="testing") parser.add_argument("--debug", action="store_true") args = parser.parse_args() if args.debug: run_debug_mode(args.env) else: run_standard_mode(args.env)

调试模式在开发新用例时特别有用，因为你可以不用等完整 unittest 的收集、执行、报告渲染流程，单条用例填错了马上就能看到是哪一步的问题。日常写用例我基本上都在这个模式下做验证，验证通过后再交到正式执行链路里。

这套框架我从最早的手工脚本演进到现在的形态，前前后后也重构过两三次。到现在我依然觉得 excel 驱动比不过更现代的测试框架，但在团队协作、交付效率和维护成本之间，它找到了一个很实用的平衡点。如果你也有类似的团队背景和项目量级，不妨照着我这个骨架搭一版，先把“数据驱动”这个概念跑起来，之后再逐步往更复杂的方案演进也不迟。