← 返回首页

测试全绿但代码是坏的:unittest.mock 的 7 个静默失效

Python单元测试踩坑复盘

上周一个读者把工单发给我:CI 四十七个用例全绿,上线四小时,结算页每单少收三成。

代码回滚、日志翻遍、监控没动过。最后定位到一行,减号被写成了加号,折扣方向反了。可它上面明明挂着一条断言折扣金额的用例,那条用例确实绿着。

问题不在于写得少,在于写下的东西从没碰过那行代码。

unittest.mock 大概是我用过的标准库里最宽容的一个模块。宽容到它会替你补上任何你以为存在的东西:方法不存在,造一个;参数写错,收下;返回值没设,返回一个 Mock 对象。这些设计都是为了让测试先跑起来,代价是——测试全绿,可能说明一件事都没发生。

下面七条路径,我在 Windows 11 + CPython 3.13.14 上全部跑过一遍,每条给出可复现的最小代码和实测输出。引用的官方原文来自 docs.python.org/3.13/library/unittest.mock.html,行号指向本机 Lib/unittest/mock.py(3,189 行,与 3.13.14 对应)。

TL;DR:patch 打在定义处而非使用处,补丁打空但测试照绿;缺 autospec,参数写错也通过;spec 只挡属性名不挡签名;MagicMock 的 bool() 恒 True、len() 恒 0、比较运算直接崩;reset_mock() 不清 return_value 与 side_effect;assert_called_with 用等值比较参数,整数 1 能顶布尔 True;父对象的 assert_not_called() 不管子调用。七条都不报错。

先看一组数字:同一个 bug,两种写法

我做了一个最小的结算模块,Pricing.total() 按比例打折。再造一个变异体:把乘法前的减号改成加号,折扣方向反过来。同一个变异体,两套用例各跑一次。

用例套正确版变异体检出
A 全程 MagicMock 替身6 个用例全绿6 个用例仍全绿0/6
B 直接用真实 Pricing5 个用例全绿2 个转红2/5

A 套的六个断言是:返回 dict、含 amount 键、currency 是 CNY、total 被调用过、coupon 被正确转发、负金额被夹到 0。每一条都对,也确实都在测东西。测的全是 checkout() 的编排,没有一条碰过 total() 里的算术。

这就是 0/6 的来源:你 mock 掉的边界,画在了被测逻辑的里面。

判断边界只有一条规则:这段逻辑出 bug 你会不会心疼。会心疼就留真实实现,只替掉跨进程、跨网络、跨时间的那一层。

坑 1:patch 打在定义处,代码却从导入处读

官方文档原话是「The basic principle is that you patch where an object is looked up, which is not necessarily the same place as where it is defined.」翻过来:在你查找它的地方打补丁,不必是它定义的地方。

这条被引用了无数遍,我实测时还是得到了一个很干净的对照数字。被测代码写的是 from client import get_user,client.get_user 里埋了一个真实计数器。

patch("client.get_user")        -> mock 调用 0 次,真实函数执行 1 次
patch("service_from.get_user")  -> mock 调用 1 次,真实函数执行 0 次

第一行补丁完全没有生效,但测试照样能绿——只要你断言的返回值恰好真函数也给得出来。我第一次跑的时候把断言写成「返回的 name 等于 real」,真函数返回的就是 real,两行输出一模一样,唯一的区别是计数器从 0 变成了 1。

真实项目里那个 1 可能是:一次真实计费、一封真实邮件、一条真实订单。测试绿着,副作用已经发生。

修法是 from 导入的地方打补丁。实在记不住,把导入改成 import client 再写 client.get_user(...),补丁位置和使用位置就是同一处。顺带说,patch("client.get_usr") 这种拼错会直接抛 AttributeError,反而不静默,原文见下文第四条。

坑 2:没有 autospec,参数写错也通过

patch() 默认给你一个万能签名。实测同一个 mock:

m(1, None, "extra", nope=1)  -> 正常返回,call_count = 1
                                call_args = call(1, None, 'extra', nope=1)

真实函数只收一个位置参数。加上 autospec=True 之后,同一次调用报 TypeError: too many positional arguments;少传参数报 TypeError: missing a required argument: 'uid'。

第二种更常见,也更贵。生产代码里写过 n(user_id=1, chanel="sms"),channel 少一个 n。无 autospec 的测试把 chanel='sms' 原样记进 call_args,用例绿;真函数在线上抛 unexpected keyword argument。

官方对 autospec 的表述是「Methods and functions being mocked will have their arguments checked and will raise a TypeError if they are called with the wrong signature.」参数会被检查,签名不对就抛 TypeError。

unittest.mock.patch 的签名里 autospec 默认是 None,等于关闭。这个默认值有历史原因,打开会让一批老测试立刻变红。但新写的测试没有理由不开。

坑 3:spec 只挡属性名,不挡签名

这一条最容易混淆,因为 spec 和 autospec 名字太像,很多人以为前者包含后者。实测三门对照,目标类 Repo 只有一个 save(self, o, force=False):

MagicMock()            -> repo.archive(o) 静默成功,archive.call_count = 1
MagicMock(spec=Repo)   -> AttributeError: Mock object has no attribute 'archive'
MagicMock(spec=Repo)   -> save(1, 2, 3, 4) 依然通过,签名错不管
create_autospec(Repo)  -> save(1, 2, 3, 4) -> TypeError: too many positional arguments

三者的边界很清楚:裸 MagicMock() 什么都收;spec= 只管属性名是否存在;create_autospec 或 autospec=True 才连签名一起管。

spec 挡属性这条本身很值钱。生产代码重构时把 save 改名成 persist,漏改一处调用,裸 MagicMock 会替你造出一个 persist(),返回一个 Mock,测试绿,线上 AttributeError。换成 spec=Repo,测试当场红。

官方原文两句:

"Accessing any attribute not in this list will raise an AttributeError."
"It is off by default because it can be dangerous. With it switched on you can write passing tests against APIs that don't actually exist!"

第二句讲的是 patch(create=True),但道理完全一样。任何允许你对着不存在的 API 写出绿灯的开关,都是把 bug 从今天挪到了明天。

坑 4:MagicMock 的默认值只覆盖一半魔法方法

MagicMock 会预创建「大部分有用的」魔法方法,于是它们有默认返回值:

bool(MagicMock())   -> True
len(MagicMock())    -> 0
int(MagicMock())    -> 1
float(MagicMock())  -> 1.0

这组默认值在两条常见分支上互相矛盾。写 if not cache.get(key):,若 cache.get() 是 MagicMock,bool 是 True,取反得 False,「没命中」的分支永远不进。写 if len(rows) == 0:,len 是 0,「空结果」分支每次都进。同一个替身,两个分支一个永不执行、一个永远执行,覆盖率报告上它们都显示已覆盖。

而比较运算压根没有默认值:

MagicMock() 小于 0   -> TypeError: '<' not supported between instances of 'MagicMock' and 'int'
MagicMock() 等于 0   -> False
MagicMock() 加 1     -> 返回一个新的 MagicMock

所以我第一版演示脚本直接崩了——if amount 小于 0: 里的 amount 是 MagicMock 的返回值,五个用例当场 TypeError。这个失败是好事,它至少报错。真正难查的是上面那两条分支。

顺带对照一下 Mock(非 Magic):它只预创建少量魔法方法,bool(Mock()) 也是 True,但 len(Mock()) 和 int(Mock()) 直接抛 TypeError: object of type 'Mock' has no len()。所以「Mock 比 MagicMock 安全」这句话只在魔法方法上成立,在属性自动创建上两者一样危险。

坑 5:reset_mock 之后 stub 还在

类级共享 mock 是性能优化,也是污染源。实测:

用例 A:m.fetch.return_value = "STUB-A",m.fetch() 得到 STUB-A
reset_mock() 之后:call_count = 0,return_value 仍是 STUB-A,再调仍得 STUB-A

side_effect 同理。用例 A 设了 RuntimeError("upstream down"),reset_mock() 之后用例 B 再调,照样抛 RuntimeError。

官方文档把这件事写得很直白:「Note that reset_mock() doesn't clear the return_value, side_effect or any child attributes you have set using normal assignment by default.」

源码也对得上。Lib/unittest/mock.py 第 631 行的签名是 reset_mock(self, visited=None, *, return_value: bool = False, side_effect: bool = False)。第 641 到 646 行只清 called、call_args、call_count、mock_calls、call_args_list、method_calls 六个字段;return_value 与 side_effect 只有在对应关键字为 True 时(第 648 到 651 行)才复位。

修法两个:reset_mock(return_value=True, side_effect=True),或者干脆别共享 mock——每个用例在 setUp 里新建一个,成本是几微秒。

坑 6:assert_called_with 用等值比较参数

assert_called_with 比对的是等值,不是身份、不是类型。三个实测结果:

m.f(1) 之后 assert_called_with(True)  -> 通过(1 等于 True)
m.g(1.0) 之后 assert_called_with(1)   -> 通过(1.0 等于 1)
可变参数事后被改 -> AssertionError: expected call not found.

前两条说明断言比想象的松:一个本该传布尔的开关传成整数 1 也判过,一个浮点 1.0 传成整数 1 也判过。如果你的函数按类型分派,先判 isinstance(x, bool) 再走分支,断言就漏掉了真实差异。

第三条反过来,比想象的严。payload = {"id": 1} 传进去,后面代码往里塞了一个键,断言时快照已经被改:

expected call not found.
Expected: send({'id': 1})
  Actual: send({'id': 1, 'extra': 'later-mutation'})

这段措辞来自 mock.py 第 968 行。它暴露了一个更根本的问题:mock 记的是引用,不是当时的副本。 所以断言可变参数要么先深拷贝再传,要么改成断言关键字而非全量字典。

顺手记一条:call_args 只保留最后一次调用。两次调用 f("first")、f("second") 之后 call_args 是 call('second'),全量在 call_args_list 里。想断言调用发生,父对象上的 call_args_list 和子对象上的计数要分开看。

坑 7:父对象的 assert_not_called 不管子调用

调用了 mp.child.work()
mp.call_count            = 0
mp.child.call_count      = 0
mp.child.work.call_count = 1
mp.assert_not_called()   -> 通过

父对象的 assert_not_called() 只回答一个问题:这个对象本身有没有被括号调用过。子对象被调用不算,孙对象被调用更不算。所以「我断言了这个 service 没被用过」在代码里往往只断言了「没有直接调用 service 本身」。

同样道理,assert_called_once_with 只看最后一次调用,assert_called_once 才看次数。三个方法名字接近,语义差得很远。

还有一条更隐蔽的:拼错断言名。3.13 加了守卫,mock.py 第 694 行只拦五个前缀 assert、assret、asert、aseert、assrt,再加上第 1107 行那份「把 assert_ 去掉前缀」的白名单。于是:

assert_called_once_     -> AttributeError: is not a valid assertion
asert_called            -> AttributeError,被前缀拦住
assert_calledonce       -> AttributeError,在白名单里
verify_called           -> 静默返回一个 MagicMock
shoud_have_been_called  -> 静默返回一个 MagicMock

只要拼写错误不以 assert 形近变体开头,它就是一个永远不会失败的空断言。而 assert_not_called() 对着一个从未被调用过的新 mock,恒真。这两件事凑在一起,是最安静的假绿。

五个报错原文,逐条对照

下面五条都是本机跑出来的原文,可以直接拿去搜。

一、AttributeError: Mock object has no attribute 'archive' 来源是 MagicMock(spec=Repo) 访问类上不存在的方法,源码第 690 行 raise AttributeError("Mock object has no attribute %r" % name)。修法:给替身加 spec=,或者回头确认生产代码调的那个方法真的存在。

二、TypeError: missing a required argument: 'uid' 来源是 patch(..., autospec=True) 之后漏传参数。同族还有 TypeError: too many positional arguments。修法:开 autospec,然后按报错补参数——这正是它想要的。

三、AssertionError: expected call not found. 来源是 assert_called_with 参数对不上,正文里给出 Expected 与 Actual 两行。修法:先看 Actual 那行,八成是参数被后续代码改过,或者位置参数与关键字参数混用了。

四、AttributeError: module 'client' does not have the attribute 'get_usr' 来源是 patch() 目标拼错,且没有 create=True。这条会硬失败,属于幸运的一类。但它同时说明:如果目标存在、只是位置打错了,你什么提示都收不到,回到坑 1。

五、TypeError: object MagicMock can't be used in 'await' expression 来源是被测函数是 async,替身用了 MagicMock。修法:换 AsyncMock,或者对 async 函数开 autospec,它会自动挑对类型。这条也属于幸运的一类,因为它至少崩了。真正的坑是 MagicMock 替掉了 async 函数,而 await 写在另一个分支里,那个分支根本没被执行到。

再补一条不报错的:side_effect 传列表,用完第三次会抛 StopIteration: StopIteration()。它看起来像报错,实际是「你只准备了两次返回,代码调了三次」——这恰恰是你想要的信号,别去捕获它。

一份可以贴进 PR 模板的清单

最后一条最省时间。上面那张 0/6 与 2/5 的表就是这么来的,不需要装 mutmut 或 cosmic-ray,改一行、跑一次、看输出。我实际的用法是每次提 PR 前跑三个变异体,任何一个全绿,就去补那条用例。

什么时候不该用 mock

三个判断。

一是被测逻辑本身。Pricing.total() 那种纯函数,替身它等于不测。只有跨进程、跨网络、跨时间(datetime.now()、time.time())、跨文件系统的东西才值得替。

二是你要验证的正是调用顺序时。assert_has_calls 能验顺序,但 call_args_list 里混进子调用后就很难读,这种情况不如直接测副作用:写出的文件内容、发出的请求体。

三是替身比真实现更复杂时。要写八个 side_effect 才能模拟一个返回三行的接口,说明边界画错了,往上退一层,替掉更外面的东西。

结语

unittest.mock 的设计目标从来不是帮你发现 bug,而是帮你隔离依赖。它默认宽容,因为宽容能让你先把测试跑起来。代价是它不会替你做「这个断言有没有意义」的判断。

同类的问题我在别处也写过:正则的 八个静默错误 是模式匹配层的漏,subprocess 的 七个静默失败 是退出码层的漏,zoneinfo 的 六条 DST 规则 是时刻比较层的漏。加上这篇的测试替身层,共性是同一个:工具给了你一个看起来对的结果,而你没有验证它是不是那个结果。

本文不含任何联盟推广链接,文中所有库都是 CPython 3.13.14 自带的标准库,复现脚本只用 unittest.mock 与 unittest。

如果只想改一件事:把项目里所有裸 MagicMock() 换成带 spec 的,把所有 patch(...) 换成带 autospec=True 的。这两处改完先别管红了几条——那些红的,就是过去一直在装绿的。

👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务

👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页