我见过太多 Python 项目上线前跑得欢一上线就出幺蛾子。原因大多不是功能没写对而是没人敢保证改 A 模块不会弄坏 B 模块。今天聊的 Python 官方自带测试框架 unittest就是帮你把基础功能钉死的那颗钉子。它是标准库成员不用装额外的包也不用学新的语法写起来就是“定义一个类、写几个方法、加几个断言”的事但威力一点都不小。这篇指南不打算把它当说明书念我会从实际项目里的痛点出发按“搞清楚为什么写”“怎么写”“怎么组织”“怎么跑”的顺序把 unittest 的完整玩法过一遍还要把我踩过的坑都摊开说。这套内容适合谁用刚入门的 Python 学习者想给脚本加一层安全网的开发以及被老板要求“补一下测试”但不知道从哪儿下手的同学。我会从一个可运行的购物车案例开始慢慢展开 setUp、断言、mock、参数化、覆盖率这些必会环节让你看完能直接在自己项目里落地。1. 先把 unittest 的定位和设计思路吃透1.1 它不是“新语言”就是标准库很多人一听“测试框架”就觉得门槛高其实 unittest 从 Python 2.1 时代就有了演进到现在非常成熟。你不需要先学 pytest 那套更花哨的插件体系只要 Python 装好了命令窗口敲一句python -m unittest测试就能跑起来。unittest 的核心设计思路很朴素把“测试”看作一个可发现、可组织的代码结构。它提供了四个基础件TestCase测试用例的容器、TestSuite多个用例的集合、TestRunner负责执行和输出结果、TestLoader负责自动发现测试类和方法。用好这几个件你就能从“写几个临时脚本验证一下”升级为“有一套可以反复执行、自动回归的测试工程”。从设计上看它借鉴了 xUnit 系列框架的经典模型。每个测试类继承unittest.TestCase类里以test_开头的方法会被识别为具体用例。执行时框架会自动帮你完成三件事准备环境、执行断言、清理现场。这种“三段式”模型最大价值是隔离性每个测试用例跑完现场就还原不会因为上一个用例改了全局变量导致下一个用例误报。1.2 三个关键优势和一个真问题先说优势不然你不会想往下看。零依赖是最大的优点。用 pytest 你得装插件、配 conftest用 nose 你得忍受老古董的维护状态。unittest 全在标准库里离线环境、内网服务器、客户现场只要机器能跑 Python就能跑测试。我帮一个金融机构做过内部工具那环境连 pip 源都受限unittest 就是唯一的体面选择。第二个优势是它和标准库的生态咬合紧密。比如unittest.mock、unittest.skip、unittest.subTest这些增强功能不是第三方补丁而是语言官方维护和你的 Python 版本同步升级。后文会逐个讲到。第三个优势是它能让 CI持续集成配置变得极简单。所有主流 CI 平台都内置了python -m unittest的执行能力不用额外安装依赖写配置文件时少踩很多坑。真问题是什么unittest 的样板代码确实比 pytest 多一点。pytest 可以用裸函数加assert 1 1unittest 必须继承类和调用self.assertEqual。但样板代码换来的是结构的统一性团队协作时每个人都按同一套规矩写review 起来反而更省心。对于要长期维护的项目这种“死板”其实是优点。2. 先搭一个真实的测试对象购物车计价类2.1 被测代码长什么样理论说再多不如直接写。假设我们有一个电商项目里的价格计算模块里面有个Cart类负责维护商品列表、计算总价、应用折扣和运费。这类代码是单元测试最典型的靶子纯业务逻辑、依赖少、边界情况多。# cart.py from dataclasses import dataclass dataclass class CartItem: sku: str name: str price: float quantity: int class Cart: def __init__(self): self._items: list[CartItem] [] def add_item(self, item: CartItem) - None: if item.quantity 0: raise ValueError(商品数量必须大于0) self._items.append(item) def item_count(self) - int: return sum(i.quantity for i in self._items) property def total(self) - float: return round(sum(i.price * i.quantity for i in self._items), 2) def apply_discount(self, rate: float) - float: if not 0 rate 1: raise ValueError(折扣率必须在0和1之间) return round(self.total * (1 - rate), 2) def shipping_fee(self) - float: if self.total 0: return 0.0 if self.item_count() 0: return 0.0 # 满99包邮否则收8元 return 0.0 if self.total 99 else 8.0这个类足够的简单但测试点并不少空购物车总额是否为 0添加商品后数量与总额是否正确数量为 0 或负数时是否抛出ValueError折扣率为 0、1、0.5、负数、大于 1 时的表现运费边界总额刚好 99 和 98.99 的区别。我在真实项目中看到的测试通病是只测“正常路径”把所有可能炸掉的情况全放给用户去踩。单元测试的意义恰恰在于把异常路径、边界值、特殊值都提前暴露出来。2.2 第一个测试用例的完整生命周期新建test_cart.py内容如下import unittest from cart import Cart, CartItem class TestCartTotal(unittest.TestCase): def setUp(self): self.cart Cart() def test_empty_cart_total_is_zero(self): self.assertEqual(self.cart.total, 0.0) def test_add_two_items_total(self): self.cart.add_item(CartItem(A1, 苹果, 3.5, 4)) self.cart.add_item(CartItem(B2, 香蕉, 2.0, 3)) self.assertEqual(self.cart.item_count(), 7) self.assertEqual(self.cart.total, 20.0) def test_negative_quantity_raises(self): with self.assertRaises(ValueError): self.cart.add_item(CartItem(A1, 苹果, 3.5, -1)) def test_discount_rate_invalid(self): with self.assertRaises(ValueError): self.cart.apply_discount(1.5) if __name__ __main__: unittest.main()说几个关键点。setUp是每个测试运行前都会调用的。这里每跑一个用例就会新建一个空购物车避免用例之间数据残留。tearDown相对用得少但如果你开了临时文件、数据库连接、网络端口就必须在tearDown里关掉。assertEqual是值比较不是对象身份比较。对浮点数别直接assertEqual(self.cart.total, 0.1)会因为浮点精度问题翻车要改用assertAlmostEqual。assertRaises是检查异常的。用with块包住要执行的操作块内如果没抛异常测试直接失败。这个模式比try...except自己捕获要干净得多。运行方式也很直接python test_cart.py如果你看到OK字样表示全部通过看到FAILED (failures1)就说明有断言不满足看到ERROR说明用例本身在执行中抛了未捕获的异常这两者的排查方向完全不同。3. 断言体系让测试替你“找茬”3.1 常用断言方法速查断言是单元测试的检查武器unittest.TestCase提供的断言方法覆盖率很高。我把最常用的一批整理成表方便你写用例时快速确认断言方法验证内容等价的否定写法assertEqual(a, b)a 等于 bassertNotEqualassertTrue(x)x 为真assertFalseassertIs(a, b)a 是 b 同一个对象assertIsNotassertIsNone(x)x 是 NoneassertIsNotNoneassertIn(item, container)item 在容器里assertNotInassertAlmostEqual(a, b, places2)a 约等于 b保留小数位assertNotAlmostEqualassertRaises(ExceptionType, func)调用会抛指定异常assertRaisesRegexassertIsInstance(obj, cls)obj 是 cls 的实例assertNotIsInstanceassertGreater(a, b)a 大于 bassertLess/assertGreaterEqualassertRegex(text, regex)文本匹配正则assertNotRegex这些方法都不难记关键是选对。我见过有人为了验证一个列表为空写assertTrue(len(items) 0)功能没错但失败提示只有False is not true排查非常抓狂。用assertEqual(items, [])或者assertFalse(items)失败时能看到具体内容。好的断言让你在报错信息里三秒定位问题差的断言让你看一眼报错还得回去加日志。3.2 装饰器与上下文管理器的用法unittest 的进阶用法大多藏在装饰器里。跳过测试import sys import unittest unittest.skip(还没有实现先跳过) class TestPlaceholder(unittest.TestCase): pass class TestPlatform(unittest.TestCase): unittest.skipIf(sys.platform win32, Windows下不需要这个测试) def test_unix_only(self): pass unittest.skipUnless(hasattr(self, feature), 当前版本没有feature属性) def test_optional_feature(self): passskip是永久跳过skipIf是条件跳过skipUnless是不满足条件就跳过。用它们处理“依赖特定平台、特定 Python 版本、特定数据库”的测试非常舒服。有些项目为了跑通所有环境写一堆if分支来跳过逻辑其实用装饰器更直观。子测试subTest也是一种容易被忽略的好功能。当你要对一组数据跑同一套断言时不要写多个 test 方法用subTest循环即可def test_multi_price_rules(self): test_data [ (0.0, 100.0, 100.0), # 折扣率0原价 (0.5, 100.0, 50.0), # 五折 (1.0, 100.0, 0.0), # 免费 ] for rate, total, expected in test_data: with self.subTest(raterate, totaltotal): self.assertEqual(apply_discount(total, rate), expected)如果没有subTest只要有一组数据失败整个循环就中断你只能看到失败的那一组其他组的正确性完全不知道。用subTest后所有组都会被跑完报告里会精确提示哪一组失败。预期的失败unittest.expectedFailure def test_known_bug(self): # 这个bug还没修先标记为“预期失败” ...这个用法比较特殊适合记录已知缺陷避免 bug 没修的时候整个测试套件红着不好看。但注意它只是打标记不改变真实行为。如果你发现某个用例标了 expectedFailure 却意外通过说明 bug 已修复可以把这个装饰器去掉了。4. 测试组织和运行从单文件到整个项目4.1 setUp/tearDown 的坑与正确用法前面我用了一个简单的setUp建购物车那是常规操作。但实际项目里setUp和tearDown有几个要注意的细节。第一每个测试方法都会重新执行 setUp/tearDown不是整个测试类只跑一次。这个设计的目的是隔离但也带来成本。如果setUp里要连接数据库、启动服务、读取大文件那测试用例越多耗时越长。这时候你要区分两类资源一类是每个用例都需要独立环境的比如清空购物车另一类是可以共享只读数据的比如一个配置文件内容、一段从磁盘加载的模板。后者建议放在类级别class TestCartWithSharedResource(unittest.TestCase): classmethod def setUpClass(cls): # 整个测试类只执行一次 cls.shared_data {exchange_rate: 7.1} classmethod def tearDownClass(cls): # 整个测试类结束后执行一次 cls.shared_data None类级别的setUpClass和tearDownClass是共享资源的正确归宿。我省过一个大坑在一个测试里改了类属性下一个测试立刻看到了被改后的值。所以共享数据一律只读如果要修改一定要用setUp重新拷贝。第二tearDown 里不要放过异常。有人习惯在tearDown里加一些“确认现场被恢复”的断言一旦这里抛异常测试报告会非常混乱你以为某个用例过了其实它根本没正常结束。我的原则是 tearDown 只做清理不做断言。4.2 用 test discovery 自动收集所有测试项目大了以后你不可能还手动python test_cart.py一个个跑。unittest 提供了自动发现机制python -m unittest discover -s tests -p test_*.py参数解释-s指定起始目录默认是当前目录-p指定匹配文件名模式默认匹配test*.py-t指定项目根目录影响包的导入路径。它会把匹配到的所有测试文件里的所有 TestCase 类全都收集起来并执行。这就是为什么你要严格遵循命名约定文件名test_xxx.py类名继承TestCase方法名以test_开头。框架就是靠这些命名规则找你代码的别自作聪明换成check_或verify_不然跑的时候一无所获。要让 discover 顺利工作项目结构最好长这样project/ ├── cart.py └── tests/ ├── test_cart.py ├── test_order.py └── __init__.pytests目录下放一个空的__init__.py必不可少。没有它Python 不会把tests当作包从项目根目录导入cart模块时经常会报ModuleNotFoundError。4.3 TestSuite 手动编排测试执行顺序大多数时候 test discovery 就够用了。但有些场景你必须手动控制执行顺序比如集成测试里要验证“先注册用户再下单再支付”这种有依赖关系的流程。这时可以用 TestSuiteimport unittest from tests.test_cart import TestCartTotal from tests.test_order import TestOrderFlow def suite(): s unittest.TestSuite() s.addTest(TestCartTotal(test_empty_cart_total_is_zero)) s.addTest(TestOrderFlow(test_create_order)) return s if __name__ __main__: runner unittest.TextTestRunner(verbosity2) runner.run(suite())不过我强烈建议你别把单元测试做成交织式的依赖流程。单元测试讲究的是“每个用例独立成军”如果你某天弄出一个“必须先跑 A 再跑 B”的测试套件那后面所有人在调试时都会非常痛苦。真要测多步骤流程应该用 unittest 之外的集成测试体系或者在单个用例内部按步骤执行。5. 用 mock 模拟外部依赖测试不再“看人脸色”5.1 最简单实用的两个 mock 用法单元测试的边界条件是“只测当前模块内部逻辑不碰外部真实依赖”。真实依赖包括数据库、第三方 API、文件系统、时间函数等。如果你不 mock测试结果会被网络波动、数据库脏数据、系统时间等因素干扰根本无法稳定复现。unittest.mock提供了强大的打桩工具最常用的是patch和MagicMock。第一种用法用装饰器 patch 替换某个对象的属性from unittest import mock from services import PriceService mock.patch(services.PriceService.get_price) def test_cart_total_with_mock(mock_get_price): mock_get_price.return_value 10.0 cart Cart() cart.add_item(CartItem(A1, 苹果, mock_get_price(A1), 2)) self.assertEqual(cart.total, 20.0)测试时不走真实的 HTTP 请求而是让get_price返回固定值 10.0。这样测试的速度和稳定性都大幅提升。第二种用法是patch.object更适合替换实例方法class TestCartWithPriceService(unittest.TestCase): def test_get_price_called(self): cart Cart(price_servicePriceService()) with mock.patch.object(PriceService, get_price, return_value5.0): cart.add_item_from_sku(A1, 3) self.assertEqual(cart.total, 15.0)这里的with上下文管理器会自动完成“进入时替换退出时还原”比手动mock.start()和mock.stop()更不容易漏。5.2 写一个依赖外部 API 的价格接口测试真实场景里购物车的价格不总是写死在商品对象里的更多是调用价格中心获取当前实时价格。我们模拟一下# services.py import requests class PriceService: def get_price(self, sku: str) - float: resp requests.get(fhttps://api.example.com/prices/{sku}) resp.raise_for_status() return resp.json()[price]这个类一上测试就会发网络请求CI 环境没有外网时候必挂。我们用 mock 把它替换掉from unittest import mock from services import PriceService class TestCartWithRemotePrice(unittest.TestCase): def setUp(self): self.cart Cart(price_servicePriceService()) mock.patch(services.PriceService.get_price) def test_add_sku_uses_mocked_price(self, mock_get_price): mock_get_price.return_value 7.99 self.cart.add_item_from_sku(SKU-001, 2) self.assertEqual(self.cart.total, 15.98) mock_get_price.assert_called_once_with(SKU-001)注意两个细节assert_called_once_with用来验证调用参数。很多 bug 出在你传对了 mock 返回值但调用方传错 sku 参数。这行断言能精准抓住这类问题。mock_get_price.return_value是设置固定返回如果想依次返回不同值用side_effectmock_get_price.side_effect [7.99, 8.99]。如果你要模拟异常mock_get_price.side_effect TimeoutError(price service timeout)那么被测代码如果有except TimeoutError的逻辑就能被覆盖到。6. 常见问题与排查技巧实录6.1 测试之间互相污染到底防不防得住我最早写单元测试时为了图省事把某些变量定义成模块级共享结果测试一多就出现诡异现象单独跑test_cart.py全绿整个测试套件一起跑就红。查了半天原来是某个用例改了模块级变量另一个用例依赖这个变量被改后的值形成了隐式依赖。解决方案很简单模块级变量能不用就不用必须共享的用setUpClass并在tearDownClass里还原。另外还可以借助 CI 的随机执行顺序排查python -m unittest discover -s tests -p test_*.py默认按文件名字典序跑一两次没问题并不代表稳定。你可以手动打乱执行顺序测试一下隔离性。还有一个常见坑是时区。如果你的代码依赖本地时区测试机器和 CI 机器时区不一样某些用例就会出现“在本地过了在 CI 挂了”。处理办法是不要依赖系统时区尽量在测试里 mock 时间函数或者显式设置TZ环境变量。6.2 覆盖率看着漂亮但功能 bugs 一堆很多团队的误区是“覆盖率 90% 就万事大吉”。实际上覆盖率只能证明“哪些代码行被执行了”不能证明“这些代码行被正确地验证了”。我接过一个历史项目测试覆盖率 85%但核心业务模块照样炸。原因是测试全在断言“函数返回类型是 int”而不是“函数返回数值符合业务规则”。所以我在项目里会给覆盖率工具比如coverage.py设两个指标行覆盖率不低于 80%关键分支覆盖率不低于 70%。更重要的是在 code review 时检查断言质量只追求行号覆盖率的 PR 一律打回。6.3 unittest 与 pytest 的取舍经验很多人问我既然 pytest 那么流行为什么还写 unittest。我的回答是看团队和项目阶段。如果你做的是开源库、长期维护的企业应用用 pytest 的fixture和parametrize确实更省事但如果你追求零额外依赖、环境经常受限、团队成员基础参差不齐unittest 是下限更稳的选择。而且这两个框架不互斥。pytest 能直接运行 unittest 写的测试用例所以你可以先用 unittest 把基础打牢未来想迁移到 pytest旧测试基本不用推翻重写。反过来 pytest 里写坏的东西想迁回 unittest 就麻烦得多因为它大量依赖插件机制。6.4 几个你迟早会踩的边界条件浮点数比较必须用assertAlmostEqual不用就会翻车。比如0.1 0.2在 Python 里是0.30000000000000004直接assertEqual必挂。临时文件测试记得用tempfile.TemporaryDirectory别自己在代码里拼路径然后 tearDown 里删。用了 TemporaryDirectory上下文退出时自动清理省心不少。环境变量的 mock用完必须还原。正确的姿势是with mock.patch.dict(os.environ, {ENABLE_DISCOUNT: true}): ...这个上下文管理器会在退出时自动恢复原环境变量不会污染其他用例。数据库测试首选内存数据库不要连开发库。连了开发库你的测试数据可能被同事清掉也可能把脏数据带到线上非常危险。7. 把单元测试嵌进日常开发流程写测试不是“项目做完以后的事”而是和写功能代码同步进行的。我个人习惯是每写一个公共函数立刻补对应的测试而不是攒到周五一次性补。攒到最后的结果通常是你自己都忘了当时函数为什么这样设计了。如果你想让这套测试真正跑出价值还要把它接到 CI 里。拿 GitHub Actions 举例配置大概长这样name: Python tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - run: | python -m unittest discover -s tests -p test_*.py这样每次提交代码CI 都会自动跑一遍所有单元测试。有任何一个用例失败合并请求就会被拦截住。这一层保护网的价值等你某次把大模块重构翻车时才能充分体会到。如果你一个人做小项目也建议至少加个 Git 钩子在git push前跑一遍测试。写脚本的思路很简单#!/bin/sh python -m unittest discover -s tests -p test_*.py if [ $? -ne 0 ]; then echo 测试未通过禁止提交 exit 1 fi放在.git/hooks/pre-push并加上执行权限即可。8. 一篇实战总结里最值得带走的几点我在实际使用 unittest 的过程中最深的体会是测试的价值不在一开始就完美而在于给你一个可以随时回归的安全网。今天聊了断言体系、setUp 和 tearDown、test discovery、mock、覆盖率、CI 集成其实每一点都能展开成更细的内容。但如果你只是想快速用起来建议从最小闭环开始拿一个现有模块写三个测试用例一个测正常情况一个测边界值一个测异常路径然后把它交给脚本自动执行。最后再分享一个小技巧测试文件里最好把业务模块通过 import 的方式引进来而不是直接复制粘贴业务代码。有些同学为了“省事”把业务函数原样贴进测试文件结果业务代码改了一个字段名测试还傻乎乎地通过。你测的是副本不是真身这种测试等于没写。踩过几次坑之后我现在写任何有点逻辑复杂度的函数都会顺手写两个断言。等函数多了再慢慢把测试结构补全。这是一个值得长期养成的习惯不是应付领导的面子工程。
我见过太多 Python 项目上线前跑得欢一上线就出幺蛾子。原因大多不是功能没写对而是没人敢保证改 A 模块不会弄坏 B 模块。今天聊的 Python 官方自带测试框架 unittest就是帮你把基础功能钉死的那颗钉子。它是标准库成员不用装额外的包也不用学新的语法写起来就是“定义一个类、写几个方法、加几个断言”的事但威力一点都不小。这篇指南不打算把它当说明书念我会从实际项目里的痛点出发按“搞清楚为什么写”“怎么写”“怎么组织”“怎么跑”的顺序把 unittest 的完整玩法过一遍还要把我踩过的坑都摊开说。这套内容适合谁用刚入门的 Python 学习者想给脚本加一层安全网的开发以及被老板要求“补一下测试”但不知道从哪儿下手的同学。我会从一个可运行的购物车案例开始慢慢展开 setUp、断言、mock、参数化、覆盖率这些必会环节让你看完能直接在自己项目里落地。1. 先把 unittest 的定位和设计思路吃透1.1 它不是“新语言”就是标准库很多人一听“测试框架”就觉得门槛高其实 unittest 从 Python 2.1 时代就有了演进到现在非常成熟。你不需要先学 pytest 那套更花哨的插件体系只要 Python 装好了命令窗口敲一句python -m unittest测试就能跑起来。unittest 的核心设计思路很朴素把“测试”看作一个可发现、可组织的代码结构。它提供了四个基础件TestCase测试用例的容器、TestSuite多个用例的集合、TestRunner负责执行和输出结果、TestLoader负责自动发现测试类和方法。用好这几个件你就能从“写几个临时脚本验证一下”升级为“有一套可以反复执行、自动回归的测试工程”。从设计上看它借鉴了 xUnit 系列框架的经典模型。每个测试类继承unittest.TestCase类里以test_开头的方法会被识别为具体用例。执行时框架会自动帮你完成三件事准备环境、执行断言、清理现场。这种“三段式”模型最大价值是隔离性每个测试用例跑完现场就还原不会因为上一个用例改了全局变量导致下一个用例误报。1.2 三个关键优势和一个真问题先说优势不然你不会想往下看。零依赖是最大的优点。用 pytest 你得装插件、配 conftest用 nose 你得忍受老古董的维护状态。unittest 全在标准库里离线环境、内网服务器、客户现场只要机器能跑 Python就能跑测试。我帮一个金融机构做过内部工具那环境连 pip 源都受限unittest 就是唯一的体面选择。第二个优势是它和标准库的生态咬合紧密。比如unittest.mock、unittest.skip、unittest.subTest这些增强功能不是第三方补丁而是语言官方维护和你的 Python 版本同步升级。后文会逐个讲到。第三个优势是它能让 CI持续集成配置变得极简单。所有主流 CI 平台都内置了python -m unittest的执行能力不用额外安装依赖写配置文件时少踩很多坑。真问题是什么unittest 的样板代码确实比 pytest 多一点。pytest 可以用裸函数加assert 1 1unittest 必须继承类和调用self.assertEqual。但样板代码换来的是结构的统一性团队协作时每个人都按同一套规矩写review 起来反而更省心。对于要长期维护的项目这种“死板”其实是优点。2. 先搭一个真实的测试对象购物车计价类2.1 被测代码长什么样理论说再多不如直接写。假设我们有一个电商项目里的价格计算模块里面有个Cart类负责维护商品列表、计算总价、应用折扣和运费。这类代码是单元测试最典型的靶子纯业务逻辑、依赖少、边界情况多。# cart.py from dataclasses import dataclass dataclass class CartItem: sku: str name: str price: float quantity: int class Cart: def __init__(self): self._items: list[CartItem] [] def add_item(self, item: CartItem) - None: if item.quantity 0: raise ValueError(商品数量必须大于0) self._items.append(item) def item_count(self) - int: return sum(i.quantity for i in self._items) property def total(self) - float: return round(sum(i.price * i.quantity for i in self._items), 2) def apply_discount(self, rate: float) - float: if not 0 rate 1: raise ValueError(折扣率必须在0和1之间) return round(self.total * (1 - rate), 2) def shipping_fee(self) - float: if self.total 0: return 0.0 if self.item_count() 0: return 0.0 # 满99包邮否则收8元 return 0.0 if self.total 99 else 8.0这个类足够的简单但测试点并不少空购物车总额是否为 0添加商品后数量与总额是否正确数量为 0 或负数时是否抛出ValueError折扣率为 0、1、0.5、负数、大于 1 时的表现运费边界总额刚好 99 和 98.99 的区别。我在真实项目中看到的测试通病是只测“正常路径”把所有可能炸掉的情况全放给用户去踩。单元测试的意义恰恰在于把异常路径、边界值、特殊值都提前暴露出来。2.2 第一个测试用例的完整生命周期新建test_cart.py内容如下import unittest from cart import Cart, CartItem class TestCartTotal(unittest.TestCase): def setUp(self): self.cart Cart() def test_empty_cart_total_is_zero(self): self.assertEqual(self.cart.total, 0.0) def test_add_two_items_total(self): self.cart.add_item(CartItem(A1, 苹果, 3.5, 4)) self.cart.add_item(CartItem(B2, 香蕉, 2.0, 3)) self.assertEqual(self.cart.item_count(), 7) self.assertEqual(self.cart.total, 20.0) def test_negative_quantity_raises(self): with self.assertRaises(ValueError): self.cart.add_item(CartItem(A1, 苹果, 3.5, -1)) def test_discount_rate_invalid(self): with self.assertRaises(ValueError): self.cart.apply_discount(1.5) if __name__ __main__: unittest.main()说几个关键点。setUp是每个测试运行前都会调用的。这里每跑一个用例就会新建一个空购物车避免用例之间数据残留。tearDown相对用得少但如果你开了临时文件、数据库连接、网络端口就必须在tearDown里关掉。assertEqual是值比较不是对象身份比较。对浮点数别直接assertEqual(self.cart.total, 0.1)会因为浮点精度问题翻车要改用assertAlmostEqual。assertRaises是检查异常的。用with块包住要执行的操作块内如果没抛异常测试直接失败。这个模式比try...except自己捕获要干净得多。运行方式也很直接python test_cart.py如果你看到OK字样表示全部通过看到FAILED (failures1)就说明有断言不满足看到ERROR说明用例本身在执行中抛了未捕获的异常这两者的排查方向完全不同。3. 断言体系让测试替你“找茬”3.1 常用断言方法速查断言是单元测试的检查武器unittest.TestCase提供的断言方法覆盖率很高。我把最常用的一批整理成表方便你写用例时快速确认断言方法验证内容等价的否定写法assertEqual(a, b)a 等于 bassertNotEqualassertTrue(x)x 为真assertFalseassertIs(a, b)a 是 b 同一个对象assertIsNotassertIsNone(x)x 是 NoneassertIsNotNoneassertIn(item, container)item 在容器里assertNotInassertAlmostEqual(a, b, places2)a 约等于 b保留小数位assertNotAlmostEqualassertRaises(ExceptionType, func)调用会抛指定异常assertRaisesRegexassertIsInstance(obj, cls)obj 是 cls 的实例assertNotIsInstanceassertGreater(a, b)a 大于 bassertLess/assertGreaterEqualassertRegex(text, regex)文本匹配正则assertNotRegex这些方法都不难记关键是选对。我见过有人为了验证一个列表为空写assertTrue(len(items) 0)功能没错但失败提示只有False is not true排查非常抓狂。用assertEqual(items, [])或者assertFalse(items)失败时能看到具体内容。好的断言让你在报错信息里三秒定位问题差的断言让你看一眼报错还得回去加日志。3.2 装饰器与上下文管理器的用法unittest 的进阶用法大多藏在装饰器里。跳过测试import sys import unittest unittest.skip(还没有实现先跳过) class TestPlaceholder(unittest.TestCase): pass class TestPlatform(unittest.TestCase): unittest.skipIf(sys.platform win32, Windows下不需要这个测试) def test_unix_only(self): pass unittest.skipUnless(hasattr(self, feature), 当前版本没有feature属性) def test_optional_feature(self): passskip是永久跳过skipIf是条件跳过skipUnless是不满足条件就跳过。用它们处理“依赖特定平台、特定 Python 版本、特定数据库”的测试非常舒服。有些项目为了跑通所有环境写一堆if分支来跳过逻辑其实用装饰器更直观。子测试subTest也是一种容易被忽略的好功能。当你要对一组数据跑同一套断言时不要写多个 test 方法用subTest循环即可def test_multi_price_rules(self): test_data [ (0.0, 100.0, 100.0), # 折扣率0原价 (0.5, 100.0, 50.0), # 五折 (1.0, 100.0, 0.0), # 免费 ] for rate, total, expected in test_data: with self.subTest(raterate, totaltotal): self.assertEqual(apply_discount(total, rate), expected)如果没有subTest只要有一组数据失败整个循环就中断你只能看到失败的那一组其他组的正确性完全不知道。用subTest后所有组都会被跑完报告里会精确提示哪一组失败。预期的失败unittest.expectedFailure def test_known_bug(self): # 这个bug还没修先标记为“预期失败” ...这个用法比较特殊适合记录已知缺陷避免 bug 没修的时候整个测试套件红着不好看。但注意它只是打标记不改变真实行为。如果你发现某个用例标了 expectedFailure 却意外通过说明 bug 已修复可以把这个装饰器去掉了。4. 测试组织和运行从单文件到整个项目4.1 setUp/tearDown 的坑与正确用法前面我用了一个简单的setUp建购物车那是常规操作。但实际项目里setUp和tearDown有几个要注意的细节。第一每个测试方法都会重新执行 setUp/tearDown不是整个测试类只跑一次。这个设计的目的是隔离但也带来成本。如果setUp里要连接数据库、启动服务、读取大文件那测试用例越多耗时越长。这时候你要区分两类资源一类是每个用例都需要独立环境的比如清空购物车另一类是可以共享只读数据的比如一个配置文件内容、一段从磁盘加载的模板。后者建议放在类级别class TestCartWithSharedResource(unittest.TestCase): classmethod def setUpClass(cls): # 整个测试类只执行一次 cls.shared_data {exchange_rate: 7.1} classmethod def tearDownClass(cls): # 整个测试类结束后执行一次 cls.shared_data None类级别的setUpClass和tearDownClass是共享资源的正确归宿。我省过一个大坑在一个测试里改了类属性下一个测试立刻看到了被改后的值。所以共享数据一律只读如果要修改一定要用setUp重新拷贝。第二tearDown 里不要放过异常。有人习惯在tearDown里加一些“确认现场被恢复”的断言一旦这里抛异常测试报告会非常混乱你以为某个用例过了其实它根本没正常结束。我的原则是 tearDown 只做清理不做断言。4.2 用 test discovery 自动收集所有测试项目大了以后你不可能还手动python test_cart.py一个个跑。unittest 提供了自动发现机制python -m unittest discover -s tests -p test_*.py参数解释-s指定起始目录默认是当前目录-p指定匹配文件名模式默认匹配test*.py-t指定项目根目录影响包的导入路径。它会把匹配到的所有测试文件里的所有 TestCase 类全都收集起来并执行。这就是为什么你要严格遵循命名约定文件名test_xxx.py类名继承TestCase方法名以test_开头。框架就是靠这些命名规则找你代码的别自作聪明换成check_或verify_不然跑的时候一无所获。要让 discover 顺利工作项目结构最好长这样project/ ├── cart.py └── tests/ ├── test_cart.py ├── test_order.py └── __init__.pytests目录下放一个空的__init__.py必不可少。没有它Python 不会把tests当作包从项目根目录导入cart模块时经常会报ModuleNotFoundError。4.3 TestSuite 手动编排测试执行顺序大多数时候 test discovery 就够用了。但有些场景你必须手动控制执行顺序比如集成测试里要验证“先注册用户再下单再支付”这种有依赖关系的流程。这时可以用 TestSuiteimport unittest from tests.test_cart import TestCartTotal from tests.test_order import TestOrderFlow def suite(): s unittest.TestSuite() s.addTest(TestCartTotal(test_empty_cart_total_is_zero)) s.addTest(TestOrderFlow(test_create_order)) return s if __name__ __main__: runner unittest.TextTestRunner(verbosity2) runner.run(suite())不过我强烈建议你别把单元测试做成交织式的依赖流程。单元测试讲究的是“每个用例独立成军”如果你某天弄出一个“必须先跑 A 再跑 B”的测试套件那后面所有人在调试时都会非常痛苦。真要测多步骤流程应该用 unittest 之外的集成测试体系或者在单个用例内部按步骤执行。5. 用 mock 模拟外部依赖测试不再“看人脸色”5.1 最简单实用的两个 mock 用法单元测试的边界条件是“只测当前模块内部逻辑不碰外部真实依赖”。真实依赖包括数据库、第三方 API、文件系统、时间函数等。如果你不 mock测试结果会被网络波动、数据库脏数据、系统时间等因素干扰根本无法稳定复现。unittest.mock提供了强大的打桩工具最常用的是patch和MagicMock。第一种用法用装饰器 patch 替换某个对象的属性from unittest import mock from services import PriceService mock.patch(services.PriceService.get_price) def test_cart_total_with_mock(mock_get_price): mock_get_price.return_value 10.0 cart Cart() cart.add_item(CartItem(A1, 苹果, mock_get_price(A1), 2)) self.assertEqual(cart.total, 20.0)测试时不走真实的 HTTP 请求而是让get_price返回固定值 10.0。这样测试的速度和稳定性都大幅提升。第二种用法是patch.object更适合替换实例方法class TestCartWithPriceService(unittest.TestCase): def test_get_price_called(self): cart Cart(price_servicePriceService()) with mock.patch.object(PriceService, get_price, return_value5.0): cart.add_item_from_sku(A1, 3) self.assertEqual(cart.total, 15.0)这里的with上下文管理器会自动完成“进入时替换退出时还原”比手动mock.start()和mock.stop()更不容易漏。5.2 写一个依赖外部 API 的价格接口测试真实场景里购物车的价格不总是写死在商品对象里的更多是调用价格中心获取当前实时价格。我们模拟一下# services.py import requests class PriceService: def get_price(self, sku: str) - float: resp requests.get(fhttps://api.example.com/prices/{sku}) resp.raise_for_status() return resp.json()[price]这个类一上测试就会发网络请求CI 环境没有外网时候必挂。我们用 mock 把它替换掉from unittest import mock from services import PriceService class TestCartWithRemotePrice(unittest.TestCase): def setUp(self): self.cart Cart(price_servicePriceService()) mock.patch(services.PriceService.get_price) def test_add_sku_uses_mocked_price(self, mock_get_price): mock_get_price.return_value 7.99 self.cart.add_item_from_sku(SKU-001, 2) self.assertEqual(self.cart.total, 15.98) mock_get_price.assert_called_once_with(SKU-001)注意两个细节assert_called_once_with用来验证调用参数。很多 bug 出在你传对了 mock 返回值但调用方传错 sku 参数。这行断言能精准抓住这类问题。mock_get_price.return_value是设置固定返回如果想依次返回不同值用side_effectmock_get_price.side_effect [7.99, 8.99]。如果你要模拟异常mock_get_price.side_effect TimeoutError(price service timeout)那么被测代码如果有except TimeoutError的逻辑就能被覆盖到。6. 常见问题与排查技巧实录6.1 测试之间互相污染到底防不防得住我最早写单元测试时为了图省事把某些变量定义成模块级共享结果测试一多就出现诡异现象单独跑test_cart.py全绿整个测试套件一起跑就红。查了半天原来是某个用例改了模块级变量另一个用例依赖这个变量被改后的值形成了隐式依赖。解决方案很简单模块级变量能不用就不用必须共享的用setUpClass并在tearDownClass里还原。另外还可以借助 CI 的随机执行顺序排查python -m unittest discover -s tests -p test_*.py默认按文件名字典序跑一两次没问题并不代表稳定。你可以手动打乱执行顺序测试一下隔离性。还有一个常见坑是时区。如果你的代码依赖本地时区测试机器和 CI 机器时区不一样某些用例就会出现“在本地过了在 CI 挂了”。处理办法是不要依赖系统时区尽量在测试里 mock 时间函数或者显式设置TZ环境变量。6.2 覆盖率看着漂亮但功能 bugs 一堆很多团队的误区是“覆盖率 90% 就万事大吉”。实际上覆盖率只能证明“哪些代码行被执行了”不能证明“这些代码行被正确地验证了”。我接过一个历史项目测试覆盖率 85%但核心业务模块照样炸。原因是测试全在断言“函数返回类型是 int”而不是“函数返回数值符合业务规则”。所以我在项目里会给覆盖率工具比如coverage.py设两个指标行覆盖率不低于 80%关键分支覆盖率不低于 70%。更重要的是在 code review 时检查断言质量只追求行号覆盖率的 PR 一律打回。6.3 unittest 与 pytest 的取舍经验很多人问我既然 pytest 那么流行为什么还写 unittest。我的回答是看团队和项目阶段。如果你做的是开源库、长期维护的企业应用用 pytest 的fixture和parametrize确实更省事但如果你追求零额外依赖、环境经常受限、团队成员基础参差不齐unittest 是下限更稳的选择。而且这两个框架不互斥。pytest 能直接运行 unittest 写的测试用例所以你可以先用 unittest 把基础打牢未来想迁移到 pytest旧测试基本不用推翻重写。反过来 pytest 里写坏的东西想迁回 unittest 就麻烦得多因为它大量依赖插件机制。6.4 几个你迟早会踩的边界条件浮点数比较必须用assertAlmostEqual不用就会翻车。比如0.1 0.2在 Python 里是0.30000000000000004直接assertEqual必挂。临时文件测试记得用tempfile.TemporaryDirectory别自己在代码里拼路径然后 tearDown 里删。用了 TemporaryDirectory上下文退出时自动清理省心不少。环境变量的 mock用完必须还原。正确的姿势是with mock.patch.dict(os.environ, {ENABLE_DISCOUNT: true}): ...这个上下文管理器会在退出时自动恢复原环境变量不会污染其他用例。数据库测试首选内存数据库不要连开发库。连了开发库你的测试数据可能被同事清掉也可能把脏数据带到线上非常危险。7. 把单元测试嵌进日常开发流程写测试不是“项目做完以后的事”而是和写功能代码同步进行的。我个人习惯是每写一个公共函数立刻补对应的测试而不是攒到周五一次性补。攒到最后的结果通常是你自己都忘了当时函数为什么这样设计了。如果你想让这套测试真正跑出价值还要把它接到 CI 里。拿 GitHub Actions 举例配置大概长这样name: Python tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - run: | python -m unittest discover -s tests -p test_*.py这样每次提交代码CI 都会自动跑一遍所有单元测试。有任何一个用例失败合并请求就会被拦截住。这一层保护网的价值等你某次把大模块重构翻车时才能充分体会到。如果你一个人做小项目也建议至少加个 Git 钩子在git push前跑一遍测试。写脚本的思路很简单#!/bin/sh python -m unittest discover -s tests -p test_*.py if [ $? -ne 0 ]; then echo 测试未通过禁止提交 exit 1 fi放在.git/hooks/pre-push并加上执行权限即可。8. 一篇实战总结里最值得带走的几点我在实际使用 unittest 的过程中最深的体会是测试的价值不在一开始就完美而在于给你一个可以随时回归的安全网。今天聊了断言体系、setUp 和 tearDown、test discovery、mock、覆盖率、CI 集成其实每一点都能展开成更细的内容。但如果你只是想快速用起来建议从最小闭环开始拿一个现有模块写三个测试用例一个测正常情况一个测边界值一个测异常路径然后把它交给脚本自动执行。最后再分享一个小技巧测试文件里最好把业务模块通过 import 的方式引进来而不是直接复制粘贴业务代码。有些同学为了“省事”把业务函数原样贴进测试文件结果业务代码改了一个字段名测试还傻乎乎地通过。你测的是副本不是真身这种测试等于没写。踩过几次坑之后我现在写任何有点逻辑复杂度的函数都会顺手写两个断言。等函数多了再慢慢把测试结构补全。这是一个值得长期养成的习惯不是应付领导的面子工程。
