Back to Details

python-pytest

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Python Pytest

Python Pytest

Guidelines for writing and reviewing pytest suites. 15 rules across 5 categories, prioritized by impact.
A rule match is a signal, not a verdict. Most rules are design preferences for new tests — check the rule's impact level before flagging in review or churning a stable suite.
Quick-reference lines are triggers, not licenses: before applying a rule as a review finding or a transformation, open the rule file and check its counter-signal — the marker-opened paragraph (
**When ...**
/ 
**Scope:**
/ 
**Exception ...**
) saying when NOT to apply it.
编写和审查 pytest 测试套件的指南。包含 5 个类别中的 15 条规则，并按影响程度排序。
命中规则只是一个信号，而不是结论。大多数规则都是针对新测试的设计偏好——在审查中将其标记为问题或对稳定的测试套件进行大范围改动之前，应先检查相应规则的影响级别。
快速参考条目只是触发条件，并不表示可以无条件应用：在将某条规则作为审查发现或执行转换之前，请打开对应的规则文件，并检查其反向提示——即以相应标记开头、说明何时不应应用该规则的段落（
**When ...**
/ 
**Scope:**
/ 
**Exception ...**
）。

When to Apply

何时应用

  • Writing new tests or fixtures
  • Reviewing test files for value, isolation, or determinism
  • Debugging flaky, order-dependent, or falsely-green tests
  • Configuring pytest and its plugin surface
The unit of judgment is the contract a test defends — every rule here traces back to whether a failure would mean something.
  • 编写新测试或 fixture
  • 审查测试文件的价值、隔离性或确定性
  • 调试 flaky、顺序依赖或虚假通过的测试
  • 配置 pytest 及其插件范围
判断的基本单位是测试所守护的契约——这里的每条规则最终都指向同一个问题：失败是否意味着确实存在问题。

Impact Levels

影响级别

  • HIGH
    — the test defends nothing or lies (probes, self-oracles, timing bets, masked flakes). Fix when found.
  • MEDIUM-HIGH
    — isolation and mocking failures that surface as order-dependence or tautology.
  • MEDIUM
    — structure and granularity; apply to new tests.
  • LOW-MEDIUM
    — suite-level hygiene; apply when configuring or composing suites.
  • HIGH
    — 测试没有守护任何内容，或测试结果具有欺骗性（执行探针、self-oracle、时序赌注、被掩盖的 flaky 问题）。发现后应修复。
  • MEDIUM-HIGH
    — 隔离或 mocking 方面的失败，表现为顺序依赖或同义反复。
  • MEDIUM
    — 结构与粒度；应用于新测试。
  • LOW-MEDIUM
    — 测试套件级卫生；配置或组合测试套件时应用。

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryImpactPrefix
1Test ValueHIGH
value-
2DeterminismHIGH
determinism-
3Fixtures & IsolationMEDIUM-HIGH
fixtures-
4MockingMEDIUM-HIGH
mock-
5Structure & ExecutionMEDIUM
structure-
优先级类别影响级别前缀
1测试价值HIGH
value-
2确定性HIGH
determinism-
3Fixture 与隔离MEDIUM-HIGH
fixtures-
4MockingMEDIUM-HIGH
mock-
5结构与执行MEDIUM
structure-

Quick Reference

快速参考

Test Value (
value-
)

测试价值（
value-
）

  • value-observable-contracts
    — A committed test protects a named behavior; delete execution probes
  • value-independent-oracles
    — Expected values derived independently, never by re-running the implementation's formula
  • value-one-behavior-per-test
    — Split independently-failing phases; merge duplicate coverage
  • value-observable-contracts
    — 纳入版本控制的测试应守护一项明确命名的行为；删除执行探针
  • value-independent-oracles
    — 预期值应独立推导，绝不能通过重新运行被测实现的计算公式得到
  • value-one-behavior-per-test
    — 拆分可能独立失败的阶段；合并重复覆盖

Determinism (
determinism-
)

确定性（
determinism-
）

  • determinism-sync-not-sleep
    — Events/barriers with failure-bound timeouts; never sleeps or elapsed-time thresholds
  • determinism-no-flake-masking
    — No rerun plugins, widened timeouts, or intermittent xfail; fix the race
  • determinism-strict-xfail
    — 
    xfail(strict=True)
    so an unexpected pass fails the run
  • determinism-sync-not-sleep
    — 使用 Event/barrier 同步，并设置超时上限以保证失败可判定；绝不使用 sleep 或耗时阈值
  • determinism-no-flake-masking
    — 不使用重跑插件、放宽超时或间歇性 xfail 来掩盖 flaky 问题；应修复竞态
  • determinism-strict-xfail
    — 使用 
    xfail(strict=True)
    ，使意外通过导致测试运行失败

Fixtures & Isolation (
fixtures-
)

Fixture 与隔离（
fixtures-
）

  • fixtures-narrowest-scope
    — Function scope by default; widen only expensive immutable setup
  • fixtures-restore-global-state
    — 
    monkeypatch
    env/cwd/attrs; restore absent vars too; cleanup runs on failure
  • fixtures-canonical-objects
    — Production constructors for fixtures, not hand-guessed dicts; raw inputs when the constructor is under test
  • fixtures-narrowest-scope
    — 默认采用 function scope；仅当初始化开销高且不可变时才扩大作用域
  • fixtures-restore-global-state
    — 使用 
    monkeypatch
    处理环境变量/cwd/属性；也要恢复原本不存在的变量；即使失败，清理仍会执行
  • fixtures-canonical-objects
    — 为 fixture 使用生产代码中的构造器，而不是手工猜测的 dict；若构造器本身是被测对象，则使用原始输入

Mocking (
mock-
)

Mocking（
mock-
）

  • mock-stable-boundaries
    — Fake the transport you don't own; run the code you do; no mock tautologies
  • mock-patch-where-used
    — Patch the namespace where the name is looked up, not where it's defined
  • mock-assert-wire-format
    — Assert serialized bytes/strings at compatibility boundaries, not Python intent
  • mock-stable-boundaries
    — 对不归你所有的 transport 使用 fake；真实运行归你所有的代码；避免 mock 同义反复
  • mock-patch-where-used
    — 在查找名称的命名空间处进行 patch，而不是名称的定义处
  • mock-assert-wire-format
    — 在兼容性边界断言序列化后的 bytes/strings，而不是 Python 层面的意图

Structure & Execution (
structure-
)

结构与执行（
structure-
）

  • structure-parametrize-partitions
    — Cases are contract-distinct partitions with independent expecteds; guard generated case sets
  • structure-unique-module-names
    — Collision-free test module import identities across composed suites
  • structure-plugin-hygiene
    — Autoload is a fine default; on observed plugin drift, make the surface explicit
  • structure-parametrize-partitions
    — 用例应是契约上不同的分区，并具有独立的预期值；需校验生成的用例集
  • structure-unique-module-names
    — 组合测试套件中的测试模块导入标识不得冲突
  • structure-plugin-hygiene
    — autoload 是合理的默认值；观察到插件漂移后，应显式限定插件范围

How to Use

如何使用

Read individual rule files for detail:
rules/value-observable-contracts.md
rules/mock-patch-where-used.md
Each rule has:
  • Impact level in frontmatter
  • Brief explanation
  • Incorrect example
  • Correct example
  • Optional note on edge cases
For the full compiled guide with all rules expanded: 
AGENTS.md
.
阅读各个规则文件以了解详细信息：
rules/value-observable-contracts.md
rules/mock-patch-where-used.md
每条规则包含：
  • frontmatter 中的影响级别
  • 简要说明
  • 错误示例
  • 正确示例
  • 关于边界情况的可选说明
如需查看所有规则完整展开后的汇编指南：
AGENTS.md
。