shenleiandClaude Opus 5
d830311894
打开普通 PDF 并使用仿真翻页阅读时，除首页外每翻一页都是纯白：没有页面 内容，也没有页面四周的衬底色。横向滚动与竖滑模式不受影响。样张 英汉大词典App需求说明.pdf 上第 2 到第 9 页无一例外。 根因是页面数据回来时找不到对应的视图。UIPageViewController 会通过 viewControllerBefore/After 提前构建相邻页的内容视图，构建时页面描述尚未 就绪，configure 发起异步 readerPage 请求后先返回一张空白页。描述返回后 acceptPageDescriptor 调用 refreshVisiblePage，而它经由 RDPDFReaderView.pageContentView(pageNum:) 定位视图，该方法在仿真翻页下 只检索 nativeCurlPageController.viewControllers，也就是已经上屏的 child。 预建的 child 此时还不在其中，图片因此从未被装配上去；翻页动画结束后又 没有任何路径重新 configure 该视图，白页就固定下来。此前偶尔能看到内容， 是 OCR 完成回调顺带触发了一次刷新，并非稳定行为。 改为按页码刷新该页的全部活动视图：控制器用弱引用表记录已创建的页面视图， refreshVisiblePage 改名为 refreshPageViews(at:)，除已上屏视图外一并装配 尚未上屏的预建视图，pageContentView 创建时即写入 tag 以便按页码匹配。 翻页落定时在 pageNum 回调中补一次装配，使内存告警清掉页面描述的场景也能 重新发起请求并恢复。另外把 image 为空的页面描述改按无效结果处理，走既有 的重试与失败重载入口，不再缓存出一张永远不会重试的白页。 新增 PDFPageTurnBlankPageTests 作为回归：翻页稳定后截屏统计画面中部深色 像素占比，白页为 0，扉页约 0.002，正文页在 0.01 以上，以 0.0005 为判定 阈值，覆盖仿真翻页正翻、仿真回翻和横向滚动三种路径。 验证：iPhone 17 Pro / iOS 26.4.1 模拟器执行 PDFPageTurnBlankPageTests、 PDFAnnotationTests、PDFDrawingModeTests、PageNavigationTests、 DisplayTypeTests 共 23 条用例，22 条通过。修复前仿真翻页第 2 到 9 页墨迹 占比全为 0.0000，修复后与横向滚动模式逐页吻合。唯一失败的 DisplayTypeTests.testDisplayTypeSwitchMidSession 属 EPUB 设置面板既有问题， 将本次改动还原后同样失败。文档补充了 Demo 因链接 FoundationModels 而必须 使用 iOS 26 及以上模拟器的说明。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
150 lines
5.0 KiB
Markdown
150 lines
5.0 KiB
Markdown
# 测试说明
|
||
|
||
**分析日期：** 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 | 页面导航 |
|
||
| PDFPageTurnBlankPageTests.swift | PDF 翻页后白页回归（截屏墨迹占比判定） |
|
||
| 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`，并已提交 `ReadViewDemo/Pods/` 与 `ReadViewDemo/Podfile.lock`。如本地环境未同步，请在示例工程目录运行：
|
||
|
||
```bash
|
||
cd ReadViewDemo && pod install
|
||
```
|
||
|
||
（依赖入口：`ReadViewDemo/Podfile`）
|
||
|
||
### 模拟器要求
|
||
|
||
Demo 链接了 `FoundationModels.framework`（AI 助手示例入口）。该框架自 iOS 26 起提供，
|
||
在 iOS 18 及更早的模拟器上 App 会在启动时因 `Library not loaded` 直接崩溃，测试表现为
|
||
卡在 Launch 阶段。请选择 iOS 26 及以上的模拟器运行 UI 测试。
|
||
|
||
### 运行 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/` 下的历史测试报告
|