- 测试
- 开发工具
【免费下载链接】hypothesis
The property-based testing library for Python
本指南聚焦 Hypothesis（Python 属性测试库）中一个看似简单实则微妙的问题：一个
@given测试究竟会被执行多少次？答案通常是“恰好max_examples次”，但搜索空间耗尽、assume/.filter()丢弃、超大测试用例重试以及失败后的缩减（shrinking）与解释（explain）阶段都会让实际次数偏离这一数字。读完本文，你将掌握max_examples的精确语义、每种偏离场景的触发条件，以及从源码层面理解 Hypothesis 执行引擎的计数逻辑。
简短答案：恰好max_examples次，但有四种例外
Hypothesis 默认情况下会运行你的测试函数恰好settings.max_examples次——这里的“次”指的是有效测试用例（valid test cases），即那些完整走完生成、执行、断言全流程的用例。该结论记录在 test-case-count.rst 中，同时存在以下例外：
| 场景 | 实际次数与max_examples的关系 |
|---|---|
| 搜索空间提前耗尽 | 少于max_examples次 |
用例未通过assume或.filter()条件 | 多于max_examples次（重试不计入上限） |
| 用例过大、生成所需的 choice 数量超限 | 多于max_examples次（重试不计入上限） |
| 发现失败用例 | 多于或少于max_examples次（生成提前停止，但 shrink/explain 及防抖动复跑会追加执行） |
下面逐项展开，并深入到执行引擎的源码细节。
max_examples是什么：默认值、校验与语义
max_examples是hypothesis.settings的核心参数之一。在 hypothesis/src/hypothesis/_settings.py 中，它作为settings.__init__的关键字参数存在，默认值为100（见 max_examples 属性文档）。
它的官方语义是（源码 docstring）：
一旦考虑过的满足条件的测试用例数量达到此值且未发现失败用例，Hypothesis 即停止搜索。
需要特别强调的是：这个设置名是历史遗留。Hypothesis 早期把测试用例称为“examples”，如今文档与代码库已统一改用“test cases”这一术语，但为了避免破坏下游生态，max_examples这个名字被保留了下来——概念上它应当理解为 “max test cases”（源码注释）。
配置方式有三种典型用法：
from hypothesis import given, settings, strategies as st # 方式一：装饰器局部覆盖 @given(st.integers()) @settings(max_examples=500) def test_something(n): ... # 方式二：全局默认（通过注册 profile） settings.register_profile("ci", settings(max_examples=1000)) settings.load_profile("ci")底层校验逻辑位于_validate_max_examples（hypothesis/src/hypothesis/_settings.py#L436-L443）：max_examples必须是int，且至少为 1，否则抛出InvalidArgument。
执行引擎中决定“何时停止”的核心判断在 engine.py 的 run 循环：
if self.valid_test_cases >= self.settings.max_examples: self.exit_with(ExitReason.max_examples)也就是说，计数以valid_test_cases为准——这正是下面各种“重试不计入上限”场景的根源。
例外一：搜索空间耗尽——少跑几次
如果 Hypothesis 检测到不再有任何新的测试用例可供尝试，它会在达到max_examples之前提前停止生成。
原文档给出了最直观的例子：
from hypothesis import given, strategies as st calls = 0 @given(st.integers(0, 19)) def test_function(n): global calls calls += 1 test_function() assert calls == 20st.integers(0, 19)的搜索空间只有 20 个互不相同的整数，因此test_function恰好被调用 20 次——而不是 100 次。
底层实现：choice sequence 与穷竭判定
搜索空间的“唯一性”是通过**choice sequence（选择序列）**来判定的：每次生成输入都对应一条由随机选择构成的序列，Hypothesis 据此判断两个输入是否相同。若两个测试用例由完全相同的选择序列产生，即视为重复。
穷竭检测的具体实现位于 datatree.py：
- 每个数据节点有一个
is_exhausted: bool = field(default=False, init=False)字段（datatree.py#L421）； - 树的根节点
root.is_exhausted表示整棵选择树是否已无可探索的分支（datatree.py#L695-L700）； - 节点进入“穷竭”状态的判定条件是：其所有子分支都已穷竭（datatree.py#L514-L519）。
引擎侧则通过__tree_is_exhausted()封装这一判断（engine.py#L434-L435）：
def __tree_is_exhausted(self) -> bool: return self.tree.is_exhausted and self.using_hypothesis_backend注意这里的using_hypothesis_backend限定条件——搜索空间追踪目前只在默认后端下启用。在 run 主循环 中，只要valid_test_cases >= max_examples或者树已穷竭，循环就会结束：
self.valid_test_cases >= self.settings.max_examples or self.__tree_is_exhausted()原文档同时强调：Hypothesis 的搜索空间追踪“很好，但并不完美”，官方把提前停止当作一种**额外红利（bonus）**而非承诺的保证——你的测试不应依赖“一定能跑满 N 次”或“一定能提前停止”中的任何一种。
例外二：assume与.filter()导致的丢弃重试——多跑几次
如果某个测试用例不满足assume()或.filter()条件，Hypothesis 会重新生成并重试该用例，且不计入max_examples上限。
原文档的例子：
from hypothesis import assume, given, strategies as st @given(st.integers()) def test_function(n): assume(n % 2 == 0)由于约一半的整数不满足“偶数”条件被丢弃，这个测试大约会运行200 次，才能凑齐 100 个有效用例。
assume()的公开 API 定义在 hypothesis/src/hypothesis/control.py，它接收一个条件表达式：条件为假时，当前测试用例被标记为“无效（invalid）”，引擎会终止本轮生成并重新抽取。
assume与.filter()的效率差异
原文档明确给出了一条实战要点：
assume失败：立即整条重试整个测试用例（整个 choice sequence 作废重来）；.filter()失败：Hypothesis 会在同一个测试用例内尝试多次以满足过滤条件（调整生成器内部的选择，让生成值更贴近过滤条件），只有多次尝试后仍失败才会整体丢弃。
因此，用.filter()表达同样的条件通常比assume更高效。例如下面两种写法语义等价，但.filter()版本更少触发整条重试：
from hypothesis import given, strategies as st # assume 版本：失败即整条重试 @given(st.integers()) def test_a(n): assume(n % 2 == 0) ... # filter 版本：生成器内部多次尝试满足条件 @given(st.integers().filter(lambda n: n % 2 == 0)) def test_b(n): ...内置策略也会悄悄引入重试
另一个容易忽略的事实：即使你的代码没有显式使用assume或.filter()，内置策略内部也可能用到它们，从而触发重试。例如st.text()、st.floats()等策略在实现某些约束（如排除 NaN、保证非空等）时会走过滤路径。Hypothesis 官方表示：凡是能直接构造满足条件的值（直接抽样而非拒绝抽样）的地方都会尽量避免依赖 rejection sampling，所以这类隐式重试“相对少见”——但你应当知道它的存在，而不是假设运行次数永远是精确的max_examples。
顺带一提，若丢弃比例过高（例如超过约 50%），Hypothesis 会触发HealthCheck.filter_too_much健康检查来警告测试效率问题（见 healthcheck 相关实现 中对健康检查“性能告警”定位的说明），提示你改用更精确的生成策略。
例外三：测试用例过大——重试并可能触发健康检查
出于性能考虑，Hypothesis 对单个测试用例生成所需的 choice 数量设有内部上限。如果一个用例超出了该限制（对应底层数据状态Status.OVERRUN，见 data.py#L122 与 data.py#L874-L875 中“hit max_choices”的越界判定），引擎会：
- 重新生成该用例；
- 重试不计入
max_examples上限； - 如果这类超大用例出现得过于频繁，会抛出
HealthCheck.data_too_large健康检查（除非通过settings.suppress_health_check显式抑制）。
对应源码层面的max_choices机制：ConjectureData构造时可传入max_choices限制（data.py#L689-L706），每次 draw 都会检查len(self.nodes) == self.max_choices并终止（data.py#L874），最终以conclude_test(Status.OVERRUN)收尾（data.py#L1501）。
原文档特别说明：这个大小上限的具体数值是“未文档化的实现细节”——绝大多数 Hypothesis 测试根本不会接近该阈值。实际中更容易碰到该限制的场景是生成了极其深层的递归结构或超长列表。如果你的测试确实需要大结构，可以显式抑制该健康检查：
from hypothesis import HealthCheck, given, settings, strategies as st @given(st.lists(st.integers(), max_size=10_000)) @settings(suppress_health_check=[HealthCheck.data_too_large]) def test_large_list(xs): ...suppress_health_check参数定义在 hypothesis/src/hypothesis/_settings.py#L675；HealthCheck.data_too_large枚举成员见 hypothesis/src/hypothesis/_settings.py#L298。当然，官方建议抑制前先评估：如果问题源于策略本身生成效率低下，更优解是收窄max_size或改用更紧凑的策略。
例外四：发现失败用例——生成停止，但 shrink/explain 追加调用
一旦 Hypothesis 发现失败用例，它就会提前停止生成（此后不会继续把用例补到max_examples个），转而在Phase.shrink（缩减）与Phase.explain（解释）阶段对失败用例做进一步处理——这两个阶段可能额外调用你的测试函数：
Phase.shrink：反复尝试将失败用例简化到最小的复现输入。每一次尝试简化都是一次新的测试执行；Phase.explain：尝试解释失败原因（例如定位到导致失败的最小前置条件）。同样是 best-effort——如果找不到有用解释，Hypothesis 会直接打印最小失败用例。
如果初始失败用例已经是最简形式，Phase.shrink可能不会产生额外执行（但Phase.explain仍可能运行）。
防抖动复跑：最小失败用例总是执行两次
一个关键且容易忽略的行为：无论 shrink 和 explain 阶段是否执行了额外调用，Hypothesis 总会把最小失败用例再运行一次，用于抖动（flakiness）检查——确保失败是确定性的，而不是偶发。
原文档给出了一个非常直观的例子——即使只启用Phase.generate（不启用 shrink 和 explain），n=0仍会被执行两次：
from hypothesis import Phase, given, settings, strategies as st @given(st.integers()) @settings(phases=[Phase.generate]) def test_function(n): print(f"called with {n}") assert n != 0 test_function()- 第一次执行：生成阶段发现
n=0导致断言失败，记录初始失败； - 第二次执行：重放
n=0确认失败可稳定复现（非 flaky）。
Phase枚举在 hypothesis/src/hypothesis/_settings.py#L142-L177 中定义，包含六个阶段，默认全部启用：
| 阶段 | 作用 |
|---|---|
Phase.explicit | 运行显式@example用例 |
Phase.reuse | 复用数据库中的历史用例 |
Phase.generate | 生成全新测试用例 |
Phase.target | 为目标函数定向变异用例 |
Phase.shrink | 缩减失败用例 |
Phase.explain | 解释失败原因 |
底层驱动这一切的是 ConjectureEngine 的 run 循环：生成阶段以valid_test_cases计数推进（max_examples判定），一旦状态变为“interesting”（即发现失败），引擎转入 shrink/explain 流程，其退出原因记录为ExitReason枚举——整个调度逻辑可在 engine.py 中追踪。
顺带说明：失败用例的复跑也解释了为什么max_examples并非“执行次数的硬性上限”——在失败场景下，总执行次数可能小于（生成提前停止）也可能大于（shrink/explain/复跑追加）max_examples。
一个易混淆的兄弟参数：stateful_step_count
如果你使用 Hypothesis 的状态机测试（RuleBasedStateMachine），注意不要与max_examples混淆：settings.stateful_step_count控制的是单个状态机测试用例内允许执行的步骤（rule 调用）数量，而max_examples控制的是状态机测试用例本身的个数。实现上，状态机通过settings.stateful_step_count读取步数上限（hypothesis/src/hypothesis/stateful.py#L143）。二者相乘大致决定了状态机测试的总步骤预算，但同样受上述“有效用例计数”语义影响。
如何观察实际执行次数
调试时想亲眼确认运行次数，可以使用Verbosity.verbose级别的输出，或简单地在测试函数内计数（如原文档示例那样用calls变量）。更正式的做法是结合 settings 的verbosity参数 打印每个用例的执行细节：
from hypothesis import given, settings, strategies as st, Verbosity @given(st.integers()) @settings(verbosity=Verbosity.verbose) def test_count(n): assert n != 0总结与实操建议
把全文要点浓缩为一张决策表，便于实际项目中使用：
| 你的目标 | 配置建议 | 注意点 |
|---|---|---|
| 常规 CI 回归测试 | 保持默认max_examples=100 | 平衡运行时长与漏检概率 |
| 一次性/深度探索测试 | max_examples=10_000+甚至更高 | 官方提到复杂代码在数百万用例后才可能发现新 bug；超过 100k 时考虑 coverage-guided fuzzing（fuzz_one_input） |
| 缩小搜索空间 | 用st.integers(a, b)等窄策略 | 可能提前穷竭，跑不满max_examples，这是特性而非 bug |
| 过滤条件多 | 优先.filter()而非assume | 减少整条重试；丢弃过多会触发HealthCheck.filter_too_much |
| 大结构输入 | 收窄max_size，必要时suppress_health_check=[HealthCheck.data_too_large] | 超大用例重试不计入上限，且可能触发健康检查 |
| 排查失败抖动 | 记住最小失败用例总会复跑一次 | 这也是Flaky错误（抖动检测失败）的判定基础 |
核心结论再强调一次：max_examples精确控制的是“有效测试用例”的个数，而不是测试函数的绝对调用次数。理解搜索空间耗尽、丢弃重试、超大用例与失败后各阶段的追加执行这四类偏离，你就能准确预判（并合理配置）Hypothesis 在你测试上的真实运行成本——这对控制 CI 时长、设计高质量策略以及正确解读“为什么跑了这么多次”的疑问都至关重要。
进一步阅读：测试用例数量官方文档（本文依据）、settings 完整参考、抑制健康检查指南。
- 测试
- 开发工具
【免费下载链接】hypothesis
The property-based testing library for Python
相关推荐
npm install-test 命令深度解析：一次执行安装与测试的完整指南
npm install test 命令深度解析：一次执行安装与测试的完整指南 导读 npm install test （别名 npm it ）是 npm 提供的
开发工具包管理器CLICPython C API 顶层执行层深度解析：PyRun_*、Py_CompileString 与 PyEval_EvalFrame 的完整实践
CPython C API 顶层执行层深度解析：PyRun_ 、Py_CompileString 与 PyEval_EvalFrame 的完整实践 本篇基于 C
编程语言语言运行时解释器标准库jest-circus 事件驱动测试运行器深度解析：从 Dispatch 机制到并发与重试的底层实现
jest circus 事件驱动测试运行器深度解析：从 Dispatch 机制到并发与重试的底层实现 本文以 packages/jest circus/CLAU
测试质量保障代码覆盖率开发工具
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
