4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d830311894040f6d137fd812628f89dd26f56c58
ReadViewSDK/Doc/TESTING.md
T
shenleiandClaude Opus 5 d830311894 修复 PDF 仿真翻页模式下翻页后页面全白 
打开普通 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>
2026-07-30 17:52:29 +09:00

5.0 KiB
Raw Blame History

测试说明

分析日期： 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。如本地环境未同步，请在示例工程目录运行：

cd ReadViewDemo && pod install

（依赖入口：ReadViewDemo/Podfile）

模拟器要求

Demo 链接了 FoundationModels.framework（AI 助手示例入口）。该框架自 iOS 26 起提供， 在 iOS 18 及更早的模拟器上 App 会在启动时因 Library not loaded 直接崩溃，测试表现为 卡在 Launch 阶段。请选择 iOS 26 及以上的模拟器运行 UI 测试。

运行 UI 测试

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

运行单个测试类

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

运行脚本

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

./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/ 下的历史测试报告
Reference in New Issue View Git Blame Copy Permalink