PostHog 测试编写规范与实践指南:从价值门禁到测试金字塔的落地方法
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_filtersdrop theteam_idclause, 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 会像独立函数一样为它执行。这同时划定了边界:只折叠同一行为的变体,不要把无关行为的断言硬塞进一个本来就会通过的测试里。
最后,写之前先搜索——没找过最近的现有测试,就无法回答这道题。
不要写它:五个"不"
大部分低价值测试都能归入这五类,认得它们并直接跳过:
-
平凡 / 框架行为(Trivial / framework behavior):不要测试 getter、setter、常量、dataclass 字段赋值、"Django 保存了一行"、"DRF 序列化了一个字段"、"库按文档工作"。你测试的是别人的代码,不是你的。
-
Change-detector 测试:仅镜像实现的测试——断言调用了哪些私有方法、调用顺序、mock 按当前代码接线——每次重构都会失败,却抓不到真实 bug。要通过公共接口测试可观测行为(返回值、持久化状态、发出的事件、HTTP 响应),而不是产生它的编排细节。
-
冗余覆盖(Redundant coverage):十个跑同一路径、换不同数据的测试等于一个参数化测试。新测试若是已有测试的变体,就是
@parameterized用例(Python)或test.each行(Jest),不是新测试函数。SKILL 特别点出:"AI-generated suites bloat here first"——AI 生成的测试套件最先在这里膨胀,几百个近相同用例把 30 秒的套件拖成 3 分钟。 -
追逐覆盖率(Coverage-chasing):不要为了凑数字加测试;未覆盖的行是信息,不是缺陷。如果测试某个分支的唯一理由是覆盖率报告,那这个分支多半不需要测试——或者代码是死代码,应该删掉。
-
跨语言源码抓取(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-checksCI 任务中无条件运行(含 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-queriessemgrep 规则会标记这种用法; - 不要巨型快照:对大型渲染树或序列化 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、Postgresnow()默认值、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_asyncgRPC 调用挂掉整个 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_querycovering 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,这套"价值门禁 → 决策树 → 效率标准"的方法论都值得在动笔之前走一遍:每个测试都必须捕获一个现有测试都抓不住的真实回归,并且便宜、确定、彼此隔离。