PostHog 测试编写规范与实践指南:从价值门禁到测试金字塔的落地方法

原创2026-09-09 22:28:061,870 阅读
文章标签:数据分析数据可视化实时分析后端前端可观测性大数据数据仓库企业应用屏幕录制AI 应用

PostHog 测试编写规范与实践指南:从价值门禁到测试金字塔的落地方法

PostHog 是面向"自驱型产品"的一站式开发平台,涵盖 AI 可观测性、产品分析、会话回放、Feature Flags、A/B 实验、错误追踪与日志等模块,代码库横跨 Python(Django / pytest)、TypeScript(Jest / Playwright)与 Rust。在这样一个体量巨大的多语言单体仓库中,测试质量直接决定 CI 的稳定性与迭代速度。本篇技术指南以仓库中的 .claude/rules/writing-tests.md 规则文件及其配套技能 writing-tests SKILL、真实踩坑目录 为主体,完整讲解 PostHog 的测试价值门禁(value gate)、决策树、测试金字塔分层、确定性隔离原则,并给出可直接复用的 pytest / Jest 代码模式。读完你将掌握一套可迁移到任何大型工程的"少而准"测试方法论,并能在 PostHog 测试目录 与 frontend 测试目录 中快速定位相关源码与测试佐证。

背景:为什么 PostHog 需要一套测试编写规则

PostHog 仓库存在一个现实问题:Agent 与人类开发者不断向测试代码中注入低价值"测试膨胀"(test bloat)——change-detector 断言、近乎重复的用例、充满 sleep 的等待、以及零断言的 mock 编排。规则文件 开篇直接点名了这四类问题:

  • change-detector 断言:测试只是镜像实现细节,重构必挂,却抓不住真实缺陷;
  • 冗余近似重复(redundant near-duplicates):同一路径换数据写十遍;
  • sleep 等待:用固定睡眠等待异步完成,是 flaky 的温床;
  • 零断言的 mock 编排:mock 了一堆边界,却从不验证任何可观测结果。

因此该规则规定了一个强制门槛(front-matter 中的 paths 声明):

paths:
  - '**/test_*.py'
  - '**/*_test.py'
  - '**/tests.py'
  - '**/*.test.ts'
  - '**/*.test.tsx'
  - '**/*.spec.ts'
  - '**/*.spec.tsx'

只要改动触及测试文件的断言或 setup——哪怕只是往现有测试块里加一个 fixture、一个断言——就必须先调用 /writing-tests 技能走完价值门禁。规则明确:没有规模阈值。这一点在 SKILL.md 中被反复强调:"The gate covers added coverage, not new test functions. One fixture and one assertion added to an existing block goes through the same two questions"——加一个 fixture、一个断言与写一个新测试函数走完全相同的两道问题。

同时存在豁免条款:与测试无关地触碰测试文件(重命名、格式化、import 排序)不在此列。

价值门禁:写测试前必须先回答的两个问题

SKILL.md 将整个决策流程收敛为两道问题,每道用一句话回答:

问题一:这个测试配得上它的位置吗(Does it earn its place?)

它能捕获哪个现有测试都没捕获的真实回归?

答不出来——说不清具体的 bug、代码路径、会崩溃的输入——就不要写。"提高覆盖率""良好的实践""函数存在"都不是答案。

一个好的回答长这样:

"if someone makes parse_filters drop the team_id clause, this fails"(如果有人在 parse_filters 中丢掉 team_id 条件,这个测试就会失败)

或:

"empty-cohort input used to 500; this locks in the 400."(空 cohort 输入过去会 500,这个测试锁定了 400 行为)

SKILL 进一步要求把测试对准真实发生过的失败模式,而不是假设性问题。PostHog 将实际发布过并被 revert 的 bug 归纳为一组形态,并给出每个形态对应的测试级别与失败模式,详见 mistakes-we-make.md(下文专节展开)。

问题二:它应该放在哪里(Where does it go?)

通过第一问只是"买到了覆盖率",不等于买到"一个新测试函数"。先找到覆盖最近行为的现有测试,然后回答:

为什么不能成为那个测试里的一个用例(case)?

  • 如果新用例是该行为的变体,就扩展它:Python 用 @parameterized 用例,Jest 用 test.each 行;
  • 只有扩展行不通时才写独立的新测试,并且要能一句话说清理由:setup 不同、行为属于不同单元、或根本不存在相关测试;
  • "单独写更干净"本身不是理由,必须点名上述三种情况中的哪一种。

需要警惕的是:扩展是为了消除重复,而不是为了省 setup 时间。参数化用例依然是独立的测试调用,setUp / beforeEach 会像独立函数一样为它执行。这同时划定了边界:只折叠同一行为的变体,不要把无关行为的断言硬塞进一个本来就会通过的测试里。

最后,写之前先搜索——没找过最近的现有测试,就无法回答这道题。

不要写它:五个"不"

大部分低价值测试都能归入这五类,认得它们并直接跳过:

  1. 平凡 / 框架行为(Trivial / framework behavior):不要测试 getter、setter、常量、dataclass 字段赋值、"Django 保存了一行"、"DRF 序列化了一个字段"、"库按文档工作"。你测试的是别人的代码,不是你的。

  2. Change-detector 测试:仅镜像实现的测试——断言调用了哪些私有方法、调用顺序、mock 按当前代码接线——每次重构都会失败,却抓不到真实 bug。要通过公共接口测试可观测行为(返回值、持久化状态、发出的事件、HTTP 响应),而不是产生它的编排细节。

  3. 冗余覆盖(Redundant coverage):十个跑同一路径、换不同数据的测试等于一个参数化测试。新测试若是已有测试的变体,就是 @parameterized 用例(Python)或 test.each 行(Jest),不是新测试函数。SKILL 特别点出:"AI-generated suites bloat here first"——AI 生成的测试套件最先在这里膨胀,几百个近相同用例把 30 秒的套件拖成 3 分钟。

  4. 追逐覆盖率(Coverage-chasing):不要为了凑数字加测试;未覆盖的行是信息,不是缺陷。如果测试某个分支的唯一理由是覆盖率报告,那这个分支多半不需要测试——或者代码是死代码,应该删掉。

  5. 跨语言源码抓取(Cross-language source-scraping):绝不允许用一个语言的测试去读 / 正则解析另一种语言的源码——比如 Python 测试 Path(...).read_text() 读 .ts 文件并匹配 category: '...',或 TS 测试 grep .py 文件。这通过脆弱的字符串匹配把两个代码树耦合在一起,任何与行为无关的编辑(重命名、重格式化、移动文件、改注释)都会弄断它,而且它证明不了任何运行时行为——测试中两边从未真正一起运行。如果两边必须就一组值达成一致,就给它们一个唯一事实来源(single source of truth)——一个双方共同 import 的生成产物或受检数据文件,并针对它断言。否则就让漂移在两边真正交汇处暴露(API 契约测试、渲染输出、往返测试),而不是去抓另一语言的源码字符串。

当答案是"不要写"时,正确动作往往是扩展现有测试(加参数化用例)或删除代码而非测试它——两者都缩小了套件的表面积。

如果写——按测试金字塔压重量

值得写的测试也必须便宜。SKILL.md 把成本画成一把梯子,每一级大约比下一级慢一个数量级、也更 flaky:

pure function / unit  →  kea logic test  →  Django TestCase  →  ClickHouse-backed test  →  Playwright e2e
        cheapest                                                                                most expensive

目标是比例而非上限:底部大量、顶部极少。一千个纯单元测试比十个启动 Django 的测试更便宜可靠,而十个 Django 测试又比一次 Playwright 运行便宜。想要更多覆盖率?在底部加。

两条硬性原则:

  • 当东西难以廉价测试时,那是设计信号——抽取,而不是升级(extract, don't escalate)。如果只有立起数据库 + 请求 + 渲染才能触达你的逻辑,说明逻辑与依赖纠缠不清。把它抽成纯函数或 kea logic 直接测试,你同时得到更快的测试和更好的代码结构。升级到下一级是最后手段,不是默认选项。
  • 前端逻辑在 kea logic 里,就测 kea logic(logic.actions / logic.values),不要渲染完整组件;render() + DOM 查询的测试只留给只有 DOM 才能展示的东西。只有当回归真的活在 ClickHouse 或浏览器里时才去够它们。

Python(pytest / Django)实战细则

用 TestCase,除非真的需要 TransactionTestCase

TransactionTestCase 在测试间清空数据库而不是回滚事务——明显更慢,也是跨测试干扰的常见来源。这是 Postgres 隔离层面的选择,与你触碰哪个数据存储无关:ClickHouse 支持的测试依然是普通 TestCase(由 ClickhouseTestMixin 负责搭建 ClickHouse),所以"碰到 ClickHouse"不是换用 TransactionTestCase 的理由。

人们为了 TransactionTestCase 而换掉的常见场景通常有更便宜的替代:

  • 测试 transaction.on_commit 副作用 → 用 TestCase + self.captureOnCommitCallbacks(execute=True);
  • 需要连接在真实独立线程中可见(thread_sensitive)→ 用 async_to_sync(...),而不是 asyncio.run(...);
  • 只有当回归确实需要 TestCase 隐藏掉的已提交事务边界时,才用 TransactionTestCase。

DRF 输入校验放 SimpleTestCase,不放 APIBaseTest 往返

向端点 POST 畸形 body 并断言 400,要为 APIBaseTest 在 Postgres 里搭建 Organization + Team + User 并把测试包进事务——而它只是测试完全在内存里运行的校验逻辑。DRF 字段校验器(required、类型强转、choices、min/max、正则)和 validate_<field> 方法在 Serializer(data=...).is_valid() 内运行,不碰数据库也不碰请求:字段级校验发生在 to_internal_value,早于通常需要 self.context 的对象级 validate()。所以无效字段用例永远不会触达触碰数据库的代码。

直接测 serializer 并断言 .errors:

class TestTeamValidation(SimpleTestCase):  # no DB — not APIBaseTest
    def test_sample_rate_too_many_digits(self) -> None:
        s = TeamSerializer(data={"session_recording_sample_rate": "30001"}, partial=True)
        assert not s.is_valid()
        assert s.errors["session_recording_sample_rate"][0].code == "max_digits"

把用例矩阵压到 serializer 层后,保留(或添加)一个 DB 支撑的端点测试作为接线守卫(wiring guard)——证明 viewset 确实调用了这个 serializer,坏请求会被 400 拒绝。无 DB 的 serializer 测试证明了校验逻辑,却不证明 viewset 接线正确:一次丢掉 serializer_class、跳过 is_valid()、或不再调用 is_valid(raise_exception=True) 的重构,会通过所有 SimpleTestCase 却发布一个坏掉的端点。一个端点用例补上这个缺口;矩阵留在 SimpleTestCase 里。对于内联实例化的查询 serializer(如 Serializer(data=request.query_params).is_valid(raise_exception=True)),接线守卫就是"坏查询参数 → 400"断言。

两个额外提醒。第一,.errors 携带 DRF 的原始 code(invalid、max_digits);{"attr", "code", "detail", "type"} 的 HTTP 信封由 exceptions-hog 稍后渲染(它把 invalid 映射为 invalid_input)——那是框架行为,不要逐用例重复断言(接线守卫测试覆盖一次信封即可)。第二,真正需要 DB 的校验留在端点层——唯一性检查、PrimaryKeyRelatedField queryset 查询、关联对象存在性、权限/团队作用域、密码哈希检查——不要硬塞进 SimpleTestCase。

其余 Python 硬性规则

  • 参数化重复断言使用 parameterized 库,不复制粘贴测试体;仓库中 from parameterized import parameterized 的用法遍布各测试模块,如 test_ai_training_opt_in_history.py、test_conversation_admin.py;
  • Python 测试不写 doc 注释(house rule);
  • 只 mock 真正的边界——网络、外部 API、时钟、队列;不要 mock 自己的内部助手(这是 change-detector 测试的诞生方式);
  • Person/group/cohort 数据:使用 posthog/test/persons.py 中的助手(create_person、create_group、create_group_type_mapping、add_cohort_members 等),绝不直接 Person.objects.create() 之类的 ORM 调用。这些助手的定义可在源码中直接确认:如 create_person、create_group、create_group_type_mapping、add_cohort_members;
  • 全仓守卫(whole-repo guards)放 posthog/test/repo_invariants/。如果测试的输入是整个仓库——遍历 apps.get_models()、冷启动 django.setup() 后检查 sys.modules、枚举每条路由或 signal receiver、或 rglob 整棵树对基线——任何文件都可能弄坏它,且基于 diff 的测试选择无法选中它。repo_invariants 目录 里的测试(如 test_dataclass_defaults.py、test_pytest_module_collisions.py、test_startup_import_budget.py 等)在每个后端 PR 的 repo-checks CI 任务中无条件运行(含 products-only 和 draft PR),该任务没有 Postgres/ClickHouse,Core 分片会跳过此目录。输入有界的测试放在它们覆盖的代码旁边。

专门的迁移测试是临时的

专用的数据迁移测试是临时产物:当所有受支持环境都应用完迁移、回滚窗口关闭、没有受支持的升级依赖旧数据状态后,删除过期测试而不是标记 skip。但保留迁移文件与以下内容的测试:迁移工具、安全检查、可复用 backfill 系统、以及人们仍可运行的 backfill。迁移安全流程使用 /django-migrations 技能。

前端(Jest)实战细则

  • 每个文件一个顶层 describe 块(house rule);
  • 逻辑测试优先于组件渲染(见金字塔);
  • 变体用 test.each,不复制测试体;
  • 避免对渲染大型 DOM 的组件使用 *ByRole(..., { name: ... })(日历、taxonomic filter、整个场景)。Role 查询会遍历每个元素执行基于 getComputedStyle 的检查和可访问名称计算——jsdom 中每次查询要花数秒,再乘以每个 waitFor / findBy* 重试;该模式已造成 CI 中单个测试 p95 达 40 秒。优先 getByText、getByTestId / data-attr 选择器、或 getByLabelText;确实需要 role 查询时用 within(<小容器>) 限定范围。jest-no-byrole-name-queries semgrep 规则会标记这种用法;
  • 不要巨型快照:对大型渲染树或序列化 blob 做快照就是 change-detector 测试,膨胀仓库且每次无关改动都会挂。快照一个小而有意的值,或断言特定字段。

始终如一的确定性(determinism)与隔离(isolation)

这一节是 PostHog 测试方法论中最易被忽视、却直接决定 CI 稳定性的部分:

  • 控制状态转换,而不是竞速。选择与行为匹配的控制手段:
    • 时间流逝行为 → 开始工作前启用 fake timers,精确推进行为所需时长;
    • 最终异步结果 → 对可观测结果使用 wait_for / waitFor;
    • 进行中的状态 → 让 mock 的边界 await 一个由测试控制的 promise:先断言 pending 状态,释放 promise,再断言最终状态。不要假设 debounce、setTimeout、kea breakpoint 或快速 mock 在下一行仍然 pending——测试 setup 可能缩短内部延迟而不改变生产行为。
  • 禁止 time.sleep / 任意等待:sleep 是等待发生的 flake,还拖慢每次运行。用上面的匹配控制或 freeze_time 替代。
  • 测试中的绝对日期是不定时炸弹,直到你钉住时钟。fixture 日期只在真实时钟停留在原地时保持意义。如果被测内容会把该日期与 now 比较——age、窗口、"最近"标志、过期时间——断言今天成立、几周后全体失败,且在所有打开的分支上同时失败。把日期钉进应用状态 ≠ 钉住时钟:测试把"evaluated at"设成固定瞬间而墙钟保持真实,一旦真实时间漂移过窗口就会失败,因为代码重新读取 now,两者不再一致。做法:把进程时钟钉到 fixture 所述的时刻——Python 用 freeze_time,Jest 用 jest.useFakeTimers() + jest.setSystemTime(),在 finally 中 jest.useRealTimers() 释放——或把 fixture 写成相对 now(如 now - 2 days),让"距离"成为测试的陈述对象。对测试中每个绝对日期都问一遍:一年之后它断言什么? 如果答案不是"同一件事",提交前修掉。
  • 冻结时钟不冻结基础设施。freeze_time 只修补进程内的时钟;进程之外的一切仍按真实时钟运行——ClickHouse TTL、Postgres now() 默认值、S3 生命周期规则、别的服务的 token 过期检查。所以冻结到绝对日期再写入按年龄判断的行,会构建时间炸弹:绿几周,然后一旦墙钟漂过保留窗口就永远红。它在所有分支同时失败,看起来像"当前这个 PR 导致"——而错误归因,而非修复,才是耗时所在。大多数 ClickHouse 表已经是安全的:它们通过 ttl_period() 构建 TTL(见 kafka_engine.py),该函数在 settings.TEST 下返回空字符串,因此测试完全没有 TTL。硬编码 TTL 子句的表则退出这个保护——ai_events 就是其一。与其假设不如检查:grep -rlE '^\s*TTL ' posthog/models/ posthog/clickhouse/ --include=*.py。让行的生命周期独立于环境时钟——在插入时钉住保留列,就像 test_util.py 中 bulk_create_ai_events 写入 retention_days=10000 那样(第 183 行 "retention_days_{index}": 10000)。向前移动冻结日期只会重置计时器。
  • 禁止真实网络 / 实时外部服务:mock 边界。
  • 禁止跨测试顺序依赖:任何顺序、孤立环境都必须通过;不依赖前一个测试留下的状态。
  • 禁止无理由的 @skip / xfail / .skip:必须带一行理由和关联 issue;永久 skip 的测试是死重——删掉或修好。
  • 绝不提交 .only(it.only / describe.only):它不是跳过一个测试,而是跳过文件里其他所有测试——让套件在极小切片上变绿。

真实踩坑目录:PostHog 实际发布过的 bug 形态

references/mistakes-we-make.md 从合并的 fix: / revert: PR 中归纳出 PostHog 真实命中过、并因此被 revert 的 bug 形态,每条都在 diff 层面核对过"PR 是否真的加了回归测试、加在哪一级"。用它把测试对准真正发生过的失败模式。两条头条结论:

  • 大多数能被廉价测试阻止的 bug 是边界与契约错误——错误分类、null/错误形态输入、跨租户泄漏、非 UTC 时间——在金字塔底部就能抓到;
  • 一些真实且昂贵的失败模式无法廉价地用单元测试覆盖(查询性能、迁移顺序、异步 teardown、重构回归、资源耗尽)。为它们写单元测试只会带来虚假信心。动手前先弄清你遇到的是哪一种。

廉价测试能抓的 bug——要写

错误分类:可重试 vs 不可重试。 数据仓库导入源把永久性失败(坏认证、集成被删、密码过期)映射成可重试错误,Temporal 就会无限重试并淹没错误追踪;或反过来,把瞬时抖动设为终态、悄悄禁用一个客户的同步。这是最常见的 fix: 集群,也是测试覆盖最好的。捕获级别:纯单元测试,断言源把特定异常字符串映射到正确的(非)可重试类——两个方向都断言。如 Salesforce 把"已删除的 OAuth 集成"视为不可重试、Snowflake 把"密码过期"视为不可重试、Postgres 保持瞬时 SSL 掉线为可重试。

Null / 空 / 错误形态输入 → 崩溃。 代码假设某值存在或形态正确(DB 字段、JSON body、group type),结果崩溃而非优雅降级。捕获级别:触达边界的最廉价层级——用坏值调纯单元,或 Django TestCase 打端点。比如 metrics 列为 NULL 时到达 enumerate(None),一行坏数据 500 掉整个实验列表;测试针对 list/detail 端点参数化 null/empty 组合。再如事件 properties 不是 JSON 时本应返回 400 而非 500——修复把 TypeError 转成 ValueError(→ 400),单元测试直接调用函数断言,甚至比端点还低一级。

租户隔离 / 作用域(IDOR)。 查询或端点未按请求团队/组织作用域,跨租户泄漏读或允许写。捕获级别:Django TestCase 建两个 org,断言 org B 看不到也改不了 org A 的行——PostHog 标准的 IDOR 覆盖形态。价值在于具体的双 org 测试,例如断言其他 org 的 plugin id 不存在、dashboard 协作者的跨项目对(断言 404 且权限行未变)。

时区 / 非 UTC 正确性。 代码假设 UTC;对非 UTC 时区的团队,日期分桶、分页游标、图表标签会偏移一天——而 CI 的 TZ=UTC 会掩盖它。捕获级别:通常是最廉价层级——对非 UTC 时区(加一个 DST 边界)参数化的纯单元测试。但当截断发生在 ClickHouse 内部时,廉价测试看不见它,需要真实执行:比如 toStartOfDay 在 session-timezone 网格上截断而游标打印 UTC,导致非 UTC session_timezone 下 keyset 第二页为空——回归测试插入行并带 session_timezone=US/Pacific 跑真实 SQL(ClickHouse 支撑的 TestCase)。先弄清你属于哪种。

HogQL printer / 类型强转。 printer 产出的 SQL 让 ClickHouse 因 cast 错误崩溃或返回错误结果。这分为两个测试层级,混淆它们是个陷阱:

  • SQL 形态变化 → 打印 SQL 断言或 .ambr 快照(如 test_printer.py),不执行。快但只证明 SQL 变了,不证明 ClickHouse 不再报错;
  • 错误结果或硬错误 → ClickHouse 支撑的 TestCase 真正运行查询。

例如 toBool 空值安全修复(包 accurateCastOrNull)用打印 SQL 字符串断言 + .ambr 快照捕获——快照只证明 cast 包装存在,仅此而已;而 funnel 聚合目标在空检查前的强转修复(数字型属性撞 ClickHouse 错误码 72)仅靠 .ambr diff(一个 toString() 包装)证明不了错误消失,真实测试要对 ClickHouse 执行 .calculate()。

真正昂贵、不该用单元测试硬套的 bug

  • 非索引友好 / 无界查询:函数包裹索引列(如 toString(uuid) IN ...)或漏绑 team_id,退化成全表扫描、大团队超时。捕获手段是 assertNumQueries / 查询计数约束或审查打印的谓词——不是 happy-path 测试。文档诚实指出:历史上这类问题靠手工验证而非自动化约束发布,这恰恰是查询边界测试要补的缺口。
  • 迁移 / 应用时顺序:代码在迁移创建表之前读表。没有受检测试能守住它;安全网是 CI 迁移重放,它演练顺序。不要假装用单元测试守。
  • 异步 / Temporal teardown 挂起:fixture teardown 中不可取消的 sync_to_async gRPC 调用挂掉整个 job。修复方式是删调用、依赖 DB CASCADE,而不是加测试。相邻陷阱:mock 掉它本该验证的边界的测试,什么都抓不到——真实 workflow-logger 崩溃的修复,其 logger 测试却 mock 了 logger,所以无论崩溃是否存在测试都通过,也测不出再回归。
  • 逃过正确性测试的重构回归:"行为保持"的重构在测试未覆盖的轴向上回归。教训不是"加表征测试",而是"覆盖真正变化的行为"。

根本不适合测试的问题

  • 负载下的资源耗尽——OOM、连接池饥饿、事件循环阻塞。与负载相关,预防靠容量与告警(已知的意外 O(n) 可以加定向性能测试,负载本身不能)。
  • 基础设施 / 第三方故障——节点崩溃、DNS 或网络变化、磁盘耗尽、上游供应商中断。根因在应用之下,补救靠 runbook 与监控。

打开 PR 之前

PR 模板在"How did you test this code?"下会提示这一点——把理由写在评审者看得到的地方,每组测试一行就够:

"Added 3 cases to test_cohort_query covering empty / single / oversized cohorts — guards the 500 we just fixed; couldn't extend an existing test because none exercised the empty path."

写不出这一行,说明你找到了一个不该出现在 PR 里的测试。

配套技能与仓库定位

  • 修复现有 flaky 测试 → 用 /fixing-flaky-tests(复现、根因、验证);只有当修复新增或实质改动覆盖时才同时用本技能。该技能会追溯应用上面的门禁:flaky 测试已经证明了它的成本,如果说不清它捕获的回归,删除也是一种有效结局——不只是稳定化工作。
  • 编写非 flaky 的 Playwright 测试 → 先用本技能判断浏览器测试是否值得它的成本;值得再用 /playwright-test 处理机制细节。

对应的仓库佐证:规则入口 writing-tests.md、技能全文 SKILL.md、踩坑目录 mistakes-we-make.md、人物/组/cohort 测试助手 persons.py、全仓守卫测试 repo_invariants、ClickHouse TTL 测试防护 kafka_engine.py、ai_events 插入辅助 test_util.py。无论你写 pytest、Jest 还是 Playwright,这套"价值门禁 → 决策树 → 效率标准"的方法论都值得在动笔之前走一遍:每个测试都必须捕获一个现有测试都抓不住的真实回归,并且便宜、确定、彼此隔离。

登录后查看全文
posthog