@feiyangdefeng/sdk 1.1.0 → 1.2.0

package/tests/README.md

@@ -0,0 +1,203 @@
+# 测试地图
+
+`tests/` 按“子系统所有权 + 发布风险”组织，回归入口和发布门禁也围绕这套分层展开。
+
+## 目录结构
+
+- `tests/core`
+  - 核心工具、事件总线、存储、配置与基础能力
+- `tests/runtime`
+  - `Tracker` 运行时协作对象、配置联动、桥接与 facade 语义
+- `tests/processor`
+  - 采样、去重、压缩与 pipeline 行为
+- `tests/collector`
+  - click / input / exposure / view / auto-tracking 等采集逻辑
+- `tests/transport`
+  - sender、batch sender、离线恢复、状态机和销毁语义
+- `tests/extension`
+  - 插件、frame adapters、SessionReplay、PerformanceMonitor、用户画像等扩展能力
+- `tests/boundary`
+  - 生命周期、并发、资源回收、性能边界与回归边缘场景
+- `tests/functional`
+  - 跨子系统的运行时行为验证
+- `tests/e2e`
+  - 全链路工作流验证
+- `tests/examples`
+  - `examples/runnable/` 的 smoke 验证，锁定示例可运行性
+
+## 回归矩阵
+
+### `core-regression`
+
+目标：锁定运行时主线、pipeline、配置联动和公开 API 兼容。
+
+覆盖范围：
+- `tests/core/*`
+- `tests/runtime/*`
+- `tests/processor/*`
+- `tests/tracker.test.ts`
+- `tests/integration.test.ts`
+
+运行命令：
+
+```bash
+pnpm test:regression:core
+```
+
+### `collector-regression`
+
+目标：锁定点击、输入、曝光、性能采集、touch 路径和组件解析主线。
+
+覆盖范围：
+- `tests/collector/*`
+- `tests/boundary/collector-boundary.test.ts`
+- `tests/functional/auto-tracking.test.ts`
+
+运行命令：
+
+```bash
+pnpm test:regression:collector
+```
+
+### `transport-regression`
+
+目标：锁定批量发送、离线恢复、状态机、destroy/destroyAsync 和空地址语义。
+
+覆盖范围：
+- `tests/transport/*`
+- `tests/boundary/transport-boundary.test.ts`
+- `tests/boundary/error-recovery.test.ts`
+- `tests/functional/transport-layer.test.ts`
+
+运行命令：
+
+```bash
+pnpm test:regression:transport
+```
+
+### `extension-regression`
+
+目标：锁定插件、network interceptor、frame adapters、SessionReplay、PerformanceMonitor 和 UI 集成兼容。
+
+覆盖范围：
+- `tests/extension/*`
+- `tests/boundary/vue-integration-boundary.test.ts`
+- `tests/functional/extension-features.test.ts`
+- `tests/functional/performance-tracking.test.ts`
+
+运行命令：
+
+```bash
+pnpm test:regression:extension
+```
+
+### `system-regression`
+
+目标：锁定长会话、并发、资源回收和全链路协同。
+
+覆盖范围：
+- `tests/boundary/concurrency.test.ts`
+- `tests/boundary/resource-cleanup.test.ts`
+- `tests/boundary/performance-boundary.test.ts`
+- `tests/e2e/full-workflow.test.ts`
+
+运行命令：
+
+```bash
+pnpm test:regression:system
+```
+
+### `docs-examples-regression`
+
+目标：防止正式示例和文档示例漂移，确保 runnable 示例持续可执行。
+
+覆盖范围：
+- `tests/examples/*`
+- `examples/runnable/*`
+
+运行命令：
+
+```bash
+pnpm test:examples
+```
+
+## 发布门禁
+
+完整门禁命令：
+
+```bash
+pnpm test:release
+```
+
+执行顺序：
+
+1. `pnpm typecheck`
+2. `pnpm build`
+3. `pnpm test:regression:core`
+4. `pnpm test:regression:collector`
+5. `pnpm test:regression:transport`
+6. `pnpm test:regression:extension`
+7. `pnpm test:regression:system`
+8. `pnpm test:examples`
+
+失败分流：
+
+- `typecheck/build` 失败：发布级阻塞
+- `core/transport/runtime` 失败：发布级阻塞
+- `collector/extension/system` 失败：发布级阻塞
+- `examples` 失败：发布级阻塞，示例视为受支持资产
+
+## 公开契约与高风险验证点
+
+公开契约锁定主要集中在这些区域：
+
+- `tests/tracker.test.ts`
+- `tests/integration.test.ts`
+- `tests/runtime/*`
+- `tests/transport/*`
+
+高风险边界主要集中在这些区域：
+
+- 初始化、配置更新、多实例
+- 空 `serverUrl`
+- flush / retry / offline recovery
+- destroy / destroyAsync / 重复 destroy
+- SessionReplay 监听器清理
+- PerformanceMonitor 历史与告警路径
+- 资源回收与长期运行
+
+## 示例与性能基线
+
+示例 smoke 不替代 functional/e2e 测试，它只验证：
+
+- 示例能被加载
+- 示例能实例化 SDK
+- 关键交互路径不报错
+- 示例中的运行说明与实际行为一致
+
+性能与资源基线文档见 [docs/PERFORMANCE_BASELINE.md](/Users/xinxin/Downloads/1.项目/tracker_sdk/docs/PERFORMANCE_BASELINE.md)。
+当前固定保留的基线入口包括：
+
+- `ClickTracker` 主基线
+- `SessionReplay` 主基线
+- `PerformanceMonitor` 主基线
+- `SessionReplay` 长驻留代理观测
+- `Memory Leak Detection` 辅助基线
+
+## 常用命令
+
+```bash
+pnpm test
+pnpm test --run
+pnpm test:regression:core
+pnpm test:regression:transport
+pnpm test:examples
+pnpm test:release
+```
+
+## 注意事项
+
+1. 测试环境默认使用 jsdom，Node 专用场景会在单个测试文件内显式切换。
+2. `tests/examples` 依赖 `dist/` 产物，`pnpm test:examples` 会先执行 `pnpm build`。
+3. IndexedDB、网络发送、浏览器 API 在测试环境中通常需要 mock 或降级路径。
+