# 测试说明

**分析日期：** 2026-06-22（更新）

## 测试框架与现状

**Runner：**
- XCTest（iOS/Xcode 默认测试框架）
- **当前仓库状态**：包含 UI 测试 Target `ReadViewDemoUITests`，位于 `ReadViewDemo/ReadViewDemoUITests/`

**断言库：**
- XCTest 内建断言（`XCTAssert*`、`XCTAssertEqual`、`XCTAssertNotNil` 等）
- XCUIElement 断言（`exists`、`waitForExistence`、`isHittable` 等）

## 测试文件组织

**位置：**
- 测试文件：`ReadViewDemo/ReadViewDemoUITests/ReaderUITests/`
- 辅助文件：`ReadViewDemo/ReadViewDemoUITests/Helpers/`

**文件清单（24 个测试文件）：**

| 测试文件 | 覆盖功能 |
|----------|----------|
| BookmarkTests.swift | 书签基础操作 |
| BookmarkManagementTests.swift | 书签管理（增删改查） |
| ConcurrentParsingTests.swift | 并发解析稳定性 |
| ConfigurableWindowTests.swift | 可配置章节窗口 |
| DisplayTypeTests.swift | 显示模式切换 |
| ErrorAndEdgeCaseTests.swift | 错误与边界情况 |
| FanrenParseTimeTest.swift | 《凡人修仙传》解析性能基准 |
| HighlightsManagementTests.swift | 高亮标注管理 |
| LargeBookOnDemandTests.swift | 大书按需加载 |
| LocationPersistenceTests.swift | 阅读位置持久化 |
| MetadataParseBenchmarkTests.swift | 元数据解析性能基准 |
| PageNavigationTests.swift | 页面导航 |
| ReaderAnnotationTests.swift | 标注基础功能 |
| ReaderAnnotationExtendedTests.swift | 标注扩展功能 |
| ReaderOpenCloseTests.swift | 阅读器打开/关闭 |
| ReaderToolbarTests.swift | 工具栏交互 |
| SearchTests.swift | 全文搜索 |
| SelectionMenuTests.swift | 选区菜单 |
| SettingsEffectTests.swift | 设置效果验证 |
| SettingsExtendedTests.swift | 设置扩展功能 |
| SettingsPanelTests.swift | 设置面板交互 |
| TableOfContentsTests.swift | 目录功能 |
| TOCInteractionTests.swift | 目录交互 |
| ToolbarStateTests.swift | 工具栏状态管理 |

**辅助文件（3 个）：**

| 文件 | 用途 |
|------|------|
| AccessibilityIdentifiers.swift | UI 元素 accessibility identifier 定义 |
| DemoReaderState.swift | 测试用阅读器状态辅助 |
| XCUIApplication+Launch.swift | XCUIApplication 启动配置扩展 |

**统计：**
- 测试类：23 个（XCTestCase 子类）
- 测试方法：约 99 个（`func test...`）
- 辅助文件：3 个

## 如何运行

### CocoaPods 依赖准备

> 仓库包含示例工程 `ReadViewDemo`，并已提交 `Pods/` 与 `Podfile.lock`。如本地环境未同步，可在仓库根或示例工程目录运行：

```bash
pod install
```

（依赖入口：`Podfile`、`ReadViewDemo/Podfile`）

### 运行 UI 测试

```bash
xcodebuild test \
  -workspace ReadViewDemo/ReadViewDemo.xcworkspace \
  -scheme ReadViewDemo \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  -only-testing:ReadViewDemoUITests
```

### 运行单个测试类

```bash
xcodebuild test \
  -workspace ReadViewDemo/ReadViewDemo.xcworkspace \
  -scheme ReadViewDemo \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  -only-testing:ReadViewDemoUITests/SearchTests
```

### 运行脚本

项目提供了自动化回归脚本：

```bash
./scripts/run_ui_regression.sh
```

测试报告输出到 `.artifacts/ui-tests/{timestamp}/UI-Test-Report.md`。

## 架构整改回归重点

在 2026-06-22 的阅读器架构整改后，以下场景应作为 smoke 回归最小集合：

- 打开大书后首次进入阅读页
- 章节尾页连续翻页，确认跨章节动画无明显卡顿
- 目录远跳到未预热章节，再返回当前阅读流
- 关闭并重新打开书籍，恢复上次阅读位置
- 长按选区、高亮、批注后再次翻页
- 打开设置面板调整字号/间距，观察预览与最终全量 repagination

建议同时记录以下观测项：

- `prepareOnDemandChapter` 主线程 wall clock
- `RDEpubReaderPreloadController` 预加载命中率
- `bookPageMap` partial extension / full replacement 次数
- 页面静态底图缓存命中率
- CFI 延迟构建完成次数与耗时

## 覆盖率（Coverage）

- 当前未启用代码覆盖率收集
- 若需启用，可在 Xcode Scheme → Test → Options 中勾选 "Code Coverage"
- 或通过 `xcodebuild test` 加 `-enableCodeCoverage YES` 参数

## Mocking / Fixtures

- 未使用统一 mocking 框架
- 测试通过 Demo App 加载真实 EPUB 文件进行端到端验证
- 辅助文件 `DemoReaderState.swift` 提供测试状态管理

## Evidence（关键证据文件）

- `ReadViewDemo/ReadViewDemo.xcodeproj/project.pbxproj`
- `ReadViewDemo/ReadViewDemoUITests/` 目录
- `ReadViewDemo/Podfile`
- `ReadViewDemo/Podfile.lock`
- `.artifacts/ui-tests/` 下的历史测试报告