PostHog JS 测试体系深度剖析:Playwright、Vitest 与 CI 流水线完整指南

原创2026-11-12 12:23:141,646 阅读
文章标签:数据分析前端移动开发可观测性人工智能MCP 服务

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 服务。

rrweb 会话录制 WebGL 方形录制回放快照

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__/ 中的基准图逐像素对比。

rrweb 对话框回放测试视觉快照

上图就是一次"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):affected job 先判断本次 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 学到的测试设计启示

✅ 这套体系给普通开发者的启示其实很直接:

  1. 分层而不要混层——逻辑用 jsdom 单测、行为用 Playwright、像素用快照,各管一段,失败原因一目了然;
  2. Mock 服务优于真实接口——sdk-mock-server 让 E2E 测试零凭证、可断言请求字节;
  3. 把"版本错配"当一等公民——compat 测试 + 强制登记 skip 原因,把兼容性风险显性化;
  4. CI 要会"挑活"——affected 增量检测让无关 PR 秒过重型流水线。

想深入源码的话,建议从 packages/browser/playwright/ 和 tooling/sdk-mock-server/README.md 两个入口读起,配合 CONTRIBUTING.md 的 Testing 章节,基本能独立跑通并读懂 posthog-js 的整套测试体系。

登录后查看全文
posthog-js