yx_tracking_flutter/docs/example_app_test_plan.md

Example App Comprehensive Test Plan

示例应用综合测试规划

Goal / 目标

Ensure the SDK works reliably in production and any SDK errors do not crash or impact the host app. 确保 SDK 在生产环境稳定运行，任何 SDK 错误都不会导致宿主应用崩溃或影响正常使用。

---

项目现状与差距分析（基于当前实现）

1. Example App 已具备基础入口：Track/Flush/Refresh Config，支持缓存条数与最近事件列表。
2. 配置拉取参数为 systemCode，需后端接口一致；联调地址为 HTTP 时必须开启 allowInsecureHttp。
3. 生命周期自动 flush 已实现，但 Example App 需要绑定 Analytics.bindLifecycleObserver()。
4. Isolate 存储默认启用，并支持失败降级到 sqflite；Example App 需补充可验证路径（或增加调试开关）。
5. Validator 行为依赖后端配置（必填 tag/事件定义需在后台配置）。

Test Categories / 测试分类

1. Stress Testing / 压力测试

Feature / 功能	Description / 描述
Batch Track (1000 events)	Rapidly track 1000 events to test storage throughput. / 快速记录 1000 条事件，测试存储吞吐量。
Concurrent Track	Fire multiple Futures concurrently (same isolate). / 同一 isolate 内并发触发多个 Future。
Continuous Flush	Repeatedly flush while events are still being added. / 在持续添加事件的同时反复 flush。

2. Error Handling / 错误处理

Feature / 功能	Description / 描述
Network Failure Simulation	Disconnect network and track events, verify queue persists and retries. / 断网状态下追踪事件，验证队列是否持久化并可重试。
Server Error (5xx) Simulation	Point to an endpoint that returns 500 errors. / 指向返回 500 的端点。
Invalid Payload Test	Track events missing required tags (requires backend config). / 追踪缺少必填标签的事件（依赖后台配置）。

3. Edge Cases / 边界情况

Feature / 功能	Description / 描述
Empty Event Params	Track event with no eventParams. / 追踪不带 eventParams 的事件。
Very Large Payload	Track event with a very large JSON payload (e.g., 100KB). / 追踪一个超大 JSON 负载的事件 (例如 100KB)。
Special Characters	Track event with special characters in eventType or params. / 在 eventType 或参数中使用特殊字符。
Rapid Init/Dispose	Initialize and dispose SDK multiple times quickly. / 快速多次初始化和释放 SDK。
Background/Foreground Transitions	Track events while app is backgrounded. / 在应用后台时追踪事件。
Event Expiration	Insert old events and verify cleanup. / 插入过期事件并验证清理。

4. SDK Robustness (Isolation) / SDK 健壮性（隔离性）

Feature / 功能	Description / 描述
Exception Swallowing	Verify SDK exceptions are caught and logged, not propagated to app. / 验证 SDK 异常被捕获并记录，而不是传递给应用。
Timeout Handling	Verify network timeouts don't freeze the app. / 验证网络超时不会冻结应用。
Fallback Storage	Force Isolate init failure and verify fallback. / 人为触发 Isolate 初始化失败并验证回退。

---

Proposed UI Structure / 建议的 UI 结构

DemoApp
├── Basic Actions / 基本操作
│   ├── Track Demo Event
│   ├── Flush Now
│   └── Refresh Config
│
├── Stress Tests / 压力测试
│   ├── Track 1000 Events (Concurrent)
│   ├── Track 5000 Events (Sequential)
│   └── Continuous Track + Flush
│
├── Error Simulation / 错误模拟
│   ├── Track Invalid Event (missing fields)
│   ├── Simulate Network Timeout
│   └── Simulate Server 5xx Error
│
├── Edge Cases / 边界情况
│   ├── Track Empty Params Event
│   ├── Track Large Payload Event
│   └── Rapid Init/Dispose Cycle
│
└── Status & Logs / 状态与日志
    ├── Cache Count
    ├── Recent Events List
    └── Real-time Log Output

---

具体测试用例（结合当前 SDK）

A. 基础联通（必做）

1. 初始化与配置
   • 配置 allowInsecureHttp: true（仅联调）。
   • systemCode 与后端配置一致。
   • 期望：初始化成功，不抛异常。
2. Track + Flush
   • 连续点击 Track 5 次，触发 flush。
   • 期望：缓存减少，后端收到事件。
3. Refresh Config
   • 点击刷新配置。
   • 期望：ConfigManager 拉取成功或日志提示跳过（未过期）。

B. 压力与稳定性

1. 1000 条批量写入
   • 一键触发批量 track。
   • 期望：无崩溃，无明显卡顿；缓存数正确。
2. 并发写入
   • 同时启动 10 个 Future，每个 100 条。
   • 期望：无异常；最终缓存数正确。
3. 持续 flush
   • 循环 track + flush 30 秒。
   • 期望：无死锁；重试与退避日志正常。

C. 错误处理

1. 断网
   • 断网后 track，恢复网络再 flush。
   • 期望：队列持久化，恢复后上报成功。
2. 后端 5xx
   • 指向返回 500 的端点。
   • 期望：retryCount 增加，事件不丢失。
3. 必填标签缺失
   • 后端配置必填 tag，track 不带该字段。
   • 期望：Debug 模式 log warning；Release 模式打 _sdk_* 标签。

D. 边界与健壮性

1. 空参数
   • eventParams=null 或空对象。
   • 期望：事件可正常入库。
2. 超大 payload
   • eventParams 约 100KB。
   • 期望：入库正常，flush 不崩。
3. 特殊字符
   • eventType 含空格/emoji/符号。
   • 期望：入库正常，后端能接收。
4. 生命周期
   • 进入后台触发自动 flush。
   • 期望：日志中出现 flush，缓存减少。
5. Isolate 回退
   • 临时在 debug 分支让 Isolate init 抛错，观察回退日志。
   • 期望：自动降级至 sqflite，功能不受影响。

---

Implementation Priority / 实现优先级

1. [High/高] Stress Test (1000 events) - Already in progress.
2. [High/高] Error Handling - Network failure and retry behavior.
3. [Medium/中] Edge Cases - Large payload, special characters.
4. [Medium/中] SDK Robustness - Exception isolation verification.
5. [Low/低] Advanced UI - Real-time log display.

---

Next Steps / 下一步

1. Finish implementing _runStressTest method.
2. Add error simulation buttons.
3. Add edge case test buttons.
4. Add real-time log display widget.
5. Add a toggle for allowInsecureHttp and useIsolateStorage in demo.