# 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 `Future`s 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.