PostHog JS 测试体系深度剖析:Playwright、Vitest 与 CI 流水线完整指南
PostHog JS 测试体系深度剖析:Playwright、Vitest 与 CI 流水线完整指南
PostHog JS(posthog-js)是用于从 Web 应用向 PostHog 发送行为分析数据(autocapture 自动采集、功能开关、会话录制等)的开源 SDK。作为支撑多端 SDK 的 pnpm monorepo,它的 PostHog JS SDK 测试体系堪称前端质量保障的"教科书":Vitest 负责单元层、Playwright 负责端到端层、rrweb 负责视觉回归层、GitHub Actions 把一切串成 CI 流水线。本文面向新手,带你看懂这套体系的设计思路与运行方式。
四层测试架构:一张图看懂整体布局
🧩 posthog-js 的测试并非"一个框架打天下",而是按职责分了四层:
| 层级 | 工具 | 验证目标 | 主要位置 |
|---|---|---|---|
| 单元/功能层 | Vitest + jsdom | 单个模块的逻辑与行为 | packages/browser/src/__tests__/ |
| 端到端层 | Playwright | 真实浏览器中加载 SDK 的全链路 | packages/browser/playwright/mocked/ |
| 视觉回归层 | rrweb + Puppeteer | 录制回放画面像素级一致 | packages/rrweb/ |
| CI 编排层 | GitHub Actions + Turbo | 自动化、增量检测、产物归档 | .github/workflows/library-ci.yml |
下面逐层拆解。
Vitest 单元测试:jsdom 里的"浏览器替身"
浏览器 SDK 的单测不能真的开浏览器,posthog-js 的解法是在 vitest.config.ts 中配置 jsdom 环境模拟 DOM,并通过大量 resolve alias 把 @posthog/core、@posthog/browser-common 等包直接指向 monorepo 内的源码文件——测试永远跑在最新源码上,无需等待构建。
几个值得新手学习的设计点:
- CSS 注入技巧:调研(surveys)样式表通过
__SURVEY_CSS__常量注入,.css文件统一走identity-obj-proxy桩; - 快照断言:
src/__tests__/__snapshots__/下保存序列化快照,配合-u更新; - 功能测试与单测分离:
functional_tests/目录(如 feature-flags.test.ts)用独立的POSTHOG_FUNCTIONAL_TESTS=1标记运行,验证更贴近真实调用的集成行为。
本地运行命令(在 CONTRIBUTING.md 中有完整说明):
# 从仓库根目录跑所有包的单测
pnpm test:unit
# 只跑 browser 包中某一个测试文件,快速迭代
cd packages/browser
pnpm exec vitest run src/path/to/test.test.ts
💡 小坑提醒:packages/browser/AGENTS.md 特别指出,Vitest 不做类型检查,所以 CI 会额外跑
pnpm check-types兜底。
Playwright 端到端测试:真实浏览器 + 模拟服务端
端到端测试的配置见 playwright.config.ts,它同时配置了 chromium、firefox、webkit 三个浏览器工程,并用 webServer 自动在本地 2345 端口起一个静态服务(npx http-server)。CI 环境下还会开启失败重试 2 次、并发 workers 固定为 2,兼顾稳定性与耗时。
真正让这套 E2E 测试"可复现"的,是一个内部造轮子——SDK 模拟 HTTP 服务。
tooling/sdk-mock-server/ 提供 createMockServer():它返回 PostHog 形状的 HTTP 端点(config、flags、capture 等),精确记录每个请求的字节与 JSON,还支持"响应闸门"(barrier)——测试可以故意卡住某个接口的响应,验证 SDK 的超时、重试、降级逻辑。相比真实调用 PostHog API,这带来了零凭证、零网络抖动、可断言请求体的三大好处。测试代码位于 packages/browser/playwright/mocked/,覆盖 autocapture、feature flags、会话录制、surveys、跨标签页会话、错误追踪等 30+ 个场景。
特色亮点:向后兼容性测试(版本错配防线)
这是很多开源 SDK 都没有、但 posthog-js 做得很完整的一层。
问题背景:array.js 是核心库,运行时再懒加载 surveys、web-vitals 等扩展。如果用户浏览器缓存了旧版 array.js、却加载了新版扩展,就可能出事故。
解法:playwright.config.compat.ts 定义了多个"错配工程",通过 staticOverrides 把静态文件替换为 npm 上已发布的旧版本(如 array.npm-latest.js、lazy-recorder.npm-legacy.js),再跑同一套 mocked 测试。若某个测试在旧版本上确实不适用,则需在 compat-skips.ts 中登记跳过,并且必须写明原因和引入版本号。
CI 侧还配了一个 compat-comment job:一旦检测到兼容失败,机器人会自动在 PR 下评论失败用例,并区分"新特性预期失败"与"真正的破坏性变更",测试恢复通过后还会自动删除该评论——把质量信息直接推回开发者的视线内。
rrweb 视觉回归:像素级的录制回放验收
posthog-js 内置了基于 rrweb 的会话录制能力,对录制画面正确性的验证采用了**图像快照(image snapshot)**方式:在 packages/rrweb/rrweb/test/e2e/ 等目录下,Puppeteer 以 1920×1080 视口录制并回放 WebGL 图形、对话框、视频等场景,将回放画面与 __image_snapshots__/ 中的基准图逐像素对比。
上图就是一次"dialog 元素打开时应渲染完整快照"的视觉断言基准图。CI 中该测试跑在 xvfb-run(虚拟显示器)下,失败时会自动上传 __diff_output__ 差异图作为 artifact,开发者点开即可看到哪一像素不对。此外仓库还有 scripts/rrweb-package-exports.test.mjs 等脚本,验证外部消费方安装 rrweb 包后的类型与导出是否正常。
跨浏览器与 IE11 真机:Playwright 覆盖不了的死角
三大现代浏览器引擎由 Playwright 矩阵覆盖(integration.yml 按 Chromium/Firefox/Safari 三个 job 并行执行,Chromium 还额外包含 chromium-es5 工程验证 ES5 产物)。
而 IE11 这类 Playwright 不支持的浏览器,走的是独立的 testcafe.yml 流水线:用 TestCafe 框架 + BrowserStack 云真机跑测试,并针对基础设施失败与真实断言失败做了精细的错误标记区分(BROWSERSTACK_SETUP_FAILURE vs 用例失败)。测试结束后还会轮询 PostHog 真实后端,确认事件确实到达。
CI 流水线:library-ci.yml 是主战场
主测试流水线 library-ci.yml 的设计值得逐一点评:
- 增量检测(affected check):
affectedjob 先判断本次 PR 是否真的改动了 browser 相关包,未命中则跳过 Playwright E2E 等重型任务,节省 CI 资源; - Unit tests job:串起类型检查(
check-types)、单测、rrweb 消费方测试、文档脚本测试,并且会扫描单测日志里的 Jest/Vitest 资源泄漏告警,有泄漏直接判失败; - Playwright E2E job:在官方
mcr.microsoft.com/playwright镜像中运行,报告归档 30 天; - 向后兼容 job:即上文 compat 测试,含失败结果解析与 PR 评论;
- Package tarballs job:打真实的 npm 包,然后在 examples/example-next-app-router/ 等示例工程里安装本地包并构建,等价于"发布前冒烟";
- 其他守护:bundled-size.yaml 监控包体积、es-check.yml 校验 ES5/ES6 产物语法、sdk-compliance-tests-node-v2.yml 运行 compliance/ 下的跨 SDK 合规测试。
其他关键流水线一览(详见 CONTRIBUTING.md 的 CI/CD 章节):
| 流水线 | 职责 |
|---|---|
| library-ci.yml | 主测试管道(单元 + E2E + 兼容) |
| integration.yml | Playwright 多浏览器集成测试 |
| testcafe.yml | IE11 + BrowserStack 真机 |
| release.yml | 发布 npm 包与浏览器资源 |
新手速查:常用测试命令清单
📋 日常开发时最常用到的命令都整理在这里(仓库根目录执行):
| 目的 | 命令 |
|---|---|
| 全部单测 | pnpm test:unit |
| browser 单测 | pnpm --filter=posthog-js test:unit |
| 快速跑单个文件 | pnpm exec vitest run src/xxx.test.ts(在 packages/browser 下) |
| Playwright 非交互式 | pnpm exec playwright test --reporter=line |
| 兼容模式 E2E | pnpm playwright:compat |
| 更新 Vitest 快照 | pnpm turbo --filter=<包名> test:unit -- -u |
| 完整 CI 对齐校验 | pnpm lint && pnpm check-types && pnpm test:unit && pnpm test:functional |
⚠️ 注意:默认 HTML reporter 在本地失败后会阻塞等待,命令看起来"卡住"其实是服务在跑,加
--reporter=line即可规避。
总结:从 posthog-js 学到的测试设计启示
✅ 这套体系给普通开发者的启示其实很直接:
- 分层而不要混层——逻辑用 jsdom 单测、行为用 Playwright、像素用快照,各管一段,失败原因一目了然;
- Mock 服务优于真实接口——sdk-mock-server 让 E2E 测试零凭证、可断言请求字节;
- 把"版本错配"当一等公民——compat 测试 + 强制登记 skip 原因,把兼容性风险显性化;
- CI 要会"挑活"——affected 增量检测让无关 PR 秒过重型流水线。
想深入源码的话,建议从 packages/browser/playwright/ 和 tooling/sdk-mock-server/README.md 两个入口读起,配合 CONTRIBUTING.md 的 Testing 章节,基本能独立跑通并读懂 posthog-js 的整套测试体系。

