OneDrive Client for Linux 端到端(E2E)自动化测试框架完全指南
OneDrive Client for Linux 端到端(E2E)自动化测试框架完全指南
本文是 OneDrive Client for Linux 仓库中端到端自动化测试框架的完整技术指南,系统讲解该框架如何在 GitHub Actions 中调用真实客户端、使用专用测试账户对 Microsoft OneDrive 执行真实同步操作,以持续验证全部客户端功能。读完本文,你将掌握测试套件的架构与运行流程、Personal / Business / SharePoint / 共享文件夹四种测试目标的差异、79 个核心用例与 70+ 细粒度场景的覆盖范围,以及如何本地运行、定向重跑和贡献新的测试用例。
测试框架定位与目标
docs/end_to_end_testing.md 描述的端到端测试框架,核心目标是:当应用程序后续发生任何变更时,确保所有客户端功能仍然正确工作。与单元测试不同,该套件不依赖 mock 或模拟服务器,而是直接在 GitHub Actions 中运行编译产物,对 Microsoft OneDrive 执行真实的同步操作,包括枚举、元数据检索、路径遍历、上传、下载、删除与双向协调。
从源码结构看,整个测试框架的代码集中存放在 ci/e2e/ 目录下,包含三大部分:
framework/:测试框架基础设施,包括上下文管理、基类、工具函数、认证预检、结果模型、manifest 构建与数据库捕获;testcases/:79 个核心测试用例(tc0001_basic_resync.py至tc0079_display_sync_status_validation.py);testcases_personal_shared_folders/与testcases_business_shared_folders/:共享文件夹专项测试;- 入口脚本
run.py、失败重跑脚本rerun_failures.py与求值门evaluate_rerun_gate.py。
四种测试目标:Personal、Business、SharePoint 与共享文件夹
个人账户与商业账户测试
Personal 与 Business 端到端测试针对已认证账户关联的默认驱动器执行完整测试套件,不在客户端配置中显式指定 drive_id。在此模式下,Microsoft Graph API 隐式解析用户的主驱动器(个人 OneDrive 或商业 OneDrive 根目录),所有驱动器枚举、元数据检索、路径遍历、上传、下载、删除与同步操作都在该默认上下文中完成。
这意味着同一套测试用例被反复用于验证客户端行为、配置处理与同步正确性,且不依赖任何显式的驱动器定向或覆盖。
需要特别注意的是:Personal 共享文件夹测试与 Business 共享文件夹测试是分开执行的,因为 OneDrive 共享文件夹快捷方式会引入与标准账户根同步完全不同的路径解析、元数据、驱动器发现、快捷方式锚定与过滤行为。
SharePoint 账户测试
SharePoint 端到端测试使用与 Personal / Business 完全相同的测试套件,但通过在客户端配置中提供 drive_id 值来切换目标驱动器。此时测试框架并非简单地在同一默认驱动器上下文上重复账户类型测试,而是显式强制客户端枚举、访问并操作一个不同的 Microsoft Graph 驱动器对象,从而产生不同的驱动器发现、元数据枚举、路径遍历、上传、下载、删除与同步 API 活动。
通过向测试配置注入 drive_id,每一个既有测试用例都针对 SharePoint 文档库上下文执行,确保完整套件在 SharePoint 后端存储上验证客户端行为、配置处理与同步正确性。这一机制在 ci/e2e/framework/context.py 中得到印证:validate_generated_config_dir() 只在 e2e_target == "sharepoint" 时强制校验生成的配置目录中必须存在非空的 drive_id 配置项,否则直接抛出运行时错误。
测试框架运行机制与架构
运行入口与整体流程
主入口 ci/e2e/run.py 的 main() 展示了完整的执行流程:
- 解析 CLI 参数与环境变量:
--case-id、--scenario、--debug、--skip-suite-cleanup、--output-subdir、--run-label等; - 构建测试套件:
build_test_suite()实例化全部 79 个测试用例类; - 认证预检(auth preflight):调用 ci/e2e/framework/auth_preflight.py 中的
run_auth_preflight(),使用隔离的配置目录与同步根目录,通过非变更性的--display-running-config --display-sync-status路径验证所选 E2E 账户能否认证,使过期的 refresh token 立即、明确地失败,而不会删除或同步账户内容; - 套件级清理:
perform_full_account_cleanup()先以--resync --resync-auth建立本地状态,再清空本地内容,随后以普通--sync将删除传播到线上,最后验证本地同步目录已清空; - 逐用例执行:每个用例运行后生成结构化
TestResult,汇总写入ci/e2e/out/results.json; - 失败时捕获数据库:当用例失败时,ci/e2e/framework/database_capture.py 会从工作根目录中递归收集所有
items.sqlite3*文件作为诊断工件。
运行上下文 E2EContext
ci/e2e/framework/context.py 中的 E2EContext 是框架的运行时上下文,强制要求三个环境变量:
ONEDRIVE_BIN:客户端二进制路径;E2E_TARGET:测试目标(personal、business、sharepoint、personal-shared-folders、business-shared-folders);RUN_ID:本次运行的唯一标识。
此外还支持 E2E_DEBUG、E2E_OUTPUT_SUBDIR、E2E_RUN_LABEL、E2E_ACCOUNT_LABEL、E2E_SKIP_SUITE_CLEANUP、E2E_SELECTED_CASES、E2E_SELECTED_SCENARIOS_JSON 等环境变量。调试模式下,框架会生成一个 onedrive-debug-wrapper.sh 包装脚本,以 --verbose 调用真实二进制(见 context.py)。
框架还会为每个用例/场景生成最小可运行的配置目录(refresh_token、config、.config.backup、.config.hash),其中 .config.hash 使用 QuickXorHash 算法计算(实现见 ci/e2e/framework/utils.py),从而让客户端无需立即要求 --resync 即可启动。
测试基类与结构化结果
所有测试用例继承自 ci/e2e/framework/base.py 中的 E2ETestCase 抽象基类,统一提供:
prepare_case_layout():重置每个用例的标准 work/log/state 目录;pass_result()/fail_result():生成统一格式的TestResult;- 一组文件系统断言助手:
assert_exists、assert_not_exists、assert_is_file、assert_is_dir、assert_file_text_equals、assert_manifest_contains等; write_manifest_artifact():通过 ci/e2e/framework/manifest.py 构建确定性 manifest(目录以/后缀区分,支持manifest_contains_prefix前缀匹配),用于本地树与远程树的一致性校验。
结果模型 ci/e2e/framework/result.py 中的 TestResult 包含 case_id、name、status、reason、artifacts 与 details 六个字段,其中 details 可携带 non_rerunnable 标记与 failed_scenario_ids 列表,为重跑逻辑提供依据。
客户端启动重试机制
ci/e2e/framework/utils.py 实现了对 OneDrive 服务启动期瞬时故障的自动重试:当输出中出现 403/408/429/5xx 等瞬时 HTTP 标记,且同时出现驱动器发现函数调用标记(如 syncEngine.getDefaultRootDetails()、syncEngine.getDefaultDriveDetails()、syncEngine.fetchRealOnlineDriveIdentifier())时,会在最多 3 次尝试内以 3 秒间隔重试,避免将网络抖动误报为用例失败。
79 个核心测试用例详解
测试套件覆盖客户端从基础冒烟到深度冲突处理的全部行为。以下按主题分组详解(完整表格见原文档 docs/end_to_end_testing.md)。
基础模式与同步开关(TC0001–TC0010)
| 用例 | 主题 | 核心验证点 |
|---|---|---|
| 0001 | 基础重同步 | 验证 E2E 框架可调用客户端、环境足以运行基础同步,是高级场景前的冒烟基线 |
| 0002 | sync_list 校验 |
策略一致性测试,覆盖排除、包含、通配符与 glob 路径/文件匹配,含 39 个 SL 场景(详见下文) |
| 0003 | Dry-run 安全 | --dry-run 执行完整同步分析但不做任何本地/远程变更 |
| 0004 | 单目录同步 | --single-directory 仅同步指定目录子树,范围外目录保持不动 |
| 0005 | 强制同步覆盖 | --force-sync 覆盖通常阻止单目录同步的阻塞条件 |
| 0006 | 仅下载 | --download-only 正确下载远程内容且不执行任何上传 |
| 0007 | 仅下载清理 | --cleanup-local-files 与 --download-only 组合:移除本地已不存在于远程的文件 |
| 0008 | 仅上传 | --upload-only 正确上传本地文件且不发生下载 |
| 0009 | 仅上传保留远程 | --no-remote-delete 确保远程文件即使本地不存在也不被删除 |
| 0010 | 仅上传移除源文件 | --remove-source-files 在成功上传后自动移除本地源文件 |
以 TC0001 为例,ci/e2e/testcases/tc0001_basic_resync.py 展示了用例的标准形态:创建独立 syncroot 与 confdir、调用 context.bootstrap_config_dir() 注入 refresh_token、执行 onedrive --sync --verbose --resync --resync-auth --syncdir <sync_root> --confdir <conf_dir>、记录 stdout/stderr 与元数据,最终根据返回码判定 pass/fail。
客户端过滤规则(TC0011–TC0017)
| 用例 | 主题 | 核心验证点 |
|---|---|---|
| 0011 | skip_file 模式 |
匹配模式的文件不上传也不下载 |
| 0012 | skip_dir 规则 |
覆盖非锚定目录名匹配、skip_dir_strict_match 全路径行为、显式同步根锚定路径、单/多段路径规则、通配符、大小写不敏感、多模式配置及上传/下载双向等价过滤,含 10 个 SD 场景 |
| 0013 | 点文件排除 | skip_dotfiles 排除以 . 开头的文件与目录 |
| 0014 | 文件大小排除 | skip_size 排除超过阈值的文件 |
| 0015 | 符号链接处理 | skip_symlinks = true 排除符号链接;skip_symlinks = false 时悬空符号链接被安全处理、客户端不崩溃且不将坏链接上传 |
| 0016 | .nosync 目录 |
含 .nosync 标记文件的目录被排除同步 |
| 0017 | .nosync 挂载保护 |
同步目录挂载点存在 .nosync 时中止同步以防误操作 |
其中 TC0012 的 10 个 SD 场景(skip_dir = "Cache" 非严格匹配、显式多段路径严格匹配、/DirectoryName 前导斜杠同步根锚定、含空格与尾随斜杠的多段路径、混合通配符/大小写不敏感/重复条目/根锚定通配符规则等)系统验证了 skip_dir 在本地到远程与远程到本地两个方向上的等价过滤行为。
回收站与运行配置(TC0018–TC0019)
TC0018 验证与 FreeDesktop 兼容回收站的集成:远程删除的文件被移入配置的回收站而非永久删除。场景覆盖:空回收站使用原始文件名;文件名冲突生成 .2 后缀并保留扩展名;连续冲突生成 .3、.4;冲突文件名不包含畸形双点扩展名(如 file.2..data);.trashinfo 文件名与回收文件名完全一致;无扩展名文件冲突重命名时不引入尾随点。
TC0019 验证客户端正确向配置的 log_dir 写日志,且 --display-running-config 输出有效运行时配置。
监控模式(TC0020、TC0041–TC0056)
TC0020 验证 --monitor 模式下,进程运行期间的文件系统变更被 inotify 事件自动检测并同步,无需手动重跑客户端。
TC0041–TC0056 构成监控模式专项矩阵:
- 基础传播:本地创建(0041)、修改(0042)、删除(0043)、重命名(0044)在
--monitor下自动上传/传播; - 目录操作:目录创建(0045)、目录重命名(0046)、目录删除(0047);
- 突发与压力:批量文件创建(0048)、混合突发操作(0049)、新目录内嵌套文件创建(0050)、快速创建再删除(0056);
- 专项场景:mtime-only 变更不上传(0051,验证工作簿内容未变时不触发上传且远程字节与 mtime 均不变)、大文件会话上传(0052)、重命名后修改(0053)、原子保存/临时文件交接工作流(0054)、仅上传移除空目录(0055)、监控下重命名为非法名(0078)。
TC0054 特别验证两种编辑器保存工作流:AS-0001 覆盖原子 os.replace() 替换已同步目标(Vim 式 .swp 保存);AS-0002 覆盖硬链接交接模式(写入 .staging 临时文件 → 硬链接创建最终路径 → 删除临时路径),生成 IN_CREATE -> IN_CLOSE_WRITE -> IN_CREATE -> IN_DELETE 事件序列,最终路径必须在 300 秒 monitor_interval 恢复周期前立即上传,临时路径不得上传。
可恢复传输与会话上传(TC0021)
TC0021 验证可恢复上传/下载会话行为,含 5 个 RT 场景:
- RT-0001:可恢复上传恢复——创建大文件、在配置的进度阈值后中断上传、验证会话状态保留在磁盘、以相同状态重跑客户端完成恢复并独立验证远程文件;
- RT-0002:可恢复下载恢复——远程播种大文件、中断下载、保留状态重跑续传、验证本地与远程文件;
- RT-0003:源路径变为悬空符号链接——恢复时执行陈旧上传会话路径而不崩溃、移除失效的
session_upload*状态、不将悬空链接上传为远程内容; - RT-0004:修改后多分片 XLSX 上传会话替换——程序化生成超过两个 10 MiB 分片的有效 XLSX 工作簿,在 SharePoint 场景下强制服务端走
404 itemNotFound / The upload session was not found恢复路径,客户端必须创建并采纳替换会话、从替换会话通告的偏移量重启、后续分片一致使用新会话 GUID;若替换会话未被采纳、分片 PUT 回退到旧 GUID、返回nameAlreadyExists、产生 safeBackup、遗留陈旧会话状态或修改后上传未完成则判失败; - RT-0005:中断上传的源身份校验——用确定性修订版 A 创建真实的 100 MiB 多分片上传,产生非零
nextExpectedRanges偏移与持久化会话状态后中断,再将本地源替换为字节大小完全一致、mtime 不同的修订版 B;恢复运行必须因sourceFileSize/ 全精度sourceFileMtime身份不匹配而拒绝旧会话、尽力取消陈旧的 Microsoft 上传会话、移除陈旧本地会话状态、从零开始全新上传,最终由独立下载校验客户端按字节大小与 SHA-256 确认远程对象精确匹配修订版 B。
冲突处理与数据保护(TC0022–TC0024)
- TC0022:
local_first配置——本地与远程发生冲突时以本地文件为权威源并更新远程; - TC0023:
bypass_data_preservation——启用后抑制冲突解决时的 safe-backup 文件创建,允许远程内容覆盖本地变更; - TC0024:
classify_as_big_delete保护机制——本地删除大量条目时客户端停止同步并发出警告,只有用户显式使用--force确认后才继续删除;同时验证跨账户类型在 API 时序或枚举差异下保护行为一致。
文件名合法性与 Microsoft 命名规则(TC0025–TC0028、TC0078)
| 用例 | 主题 | 核心验证点 |
|---|---|---|
| 0025 | 非法字符 | 含非法字符的文件名被阻止,合法同名兄弟文件仍正常同步 |
| 0026 | 保留设备名 | Windows 保留设备名被阻止,合法形近名仍正常同步 |
| 0027 | 尾随空格/点 | 尾随空白与尾随点名称被阻止,合法兄弟文件正常同步 |
| 0028 | 控制字符/非 UTF-8 | 控制字符与非 UTF-8 文件名被安全跳过、客户端不崩溃 |
| 0078 | 监控下重命名为非法名 | 已在线同步条目被本地重命名为 Microsoft 拒绝的名称时,保留在线副本而非删除;覆盖文件与目录两种重命名、后续协调/收敛两轮后在线副本仍不被清除 |
TC0078 的设计动机值得关注:TC0025 只覆盖新建非法名被跳过,TC0044/TC0046 只覆盖合法名之间的重命名,二者都不覆盖「已在线条目被重命名为非法名」这一交集——此时条目并未离开同步范围(仍在 sync_dir 内),只是无法在线命名,因此在线副本是本地仍然存在的数据的唯一同步副本。
文件名时间戳与内容替换(TC0029、TC0036、TC0037)
- TC0029:
--local-first --upload-only上传真实 XLSX 工作簿时不从 Microsoft API 响应数据改写本地文件时间戳,两次固定历史 mtime 上传后本地字节与时间戳均保持不动,最终 no-op 同步不做额外协调; - TC0036:覆盖/替换既有 Microsoft 文件内容,含 4 个 OR 场景——小文件不同内容 + 更新本地 mtime 正常上传无 safeBackup(OR-0001);小文件不同内容 + 故意保留旧 mtime,在线 eTag 未变则走简单修改上传无 safeBackup(OR-0002);大于 4 MiB 文件走自动会话上传路径(OR-0003);独立变更者在线修改 XLSX 而主体客户端保留旧本地替换时,
local_first强制在消费远程 delta 前评估陈旧 DB 基线,在线 eTag 已变则保留保守的 safeBackup 冲突路径(OR-0004); - TC0037:仅 mtime 变更处理,含 4 个 MT 场景——小 XLSX 默认简单上传种子、大 XLSX 自动会话上传种子、
force_session_upload = true的小/大文件;四种场景都要求 XLSX 包与修订标记保持有效、工作簿字节不被 mtime 操作改写、mtime-only 路径被显式检测、远程时间戳行为与所走传输路径匹配。
重命名、移动与目录操作(TC0030–TC0035、TC0038–TC0040、TC0065)
- TC0030/0031:本地文件/目录重命名正确传播到远程;
- TC0032/0033:陈旧本地客户端正确协调远程侧文件/目录重命名而不遗留陈旧本地内容(TC0033 使用已有本地与数据库状态的第二客户端协调另一客户端传播的远程目录重命名);
- TC0034/0035:本地/远程文件跨目录移动的传播与协调;
- TC0038:删除文件、同步删除、再以同名重建不同文件,最终远程与本地状态正确、无陈旧 item-id 或状态数据库问题;
- TC0039:空目录(含嵌套空目录)的创建、同步、验证与清理;
- TC0040:嵌套树重命名+删除+新建组合压力测试;
- TC0065:
sync_list作用域内远程目录移动/重命名的协调,含 5 个 S 场景(双向父目录移动、同父目录重命名、download-only 父目录移动、monitor 协调、download-only 移动后修改/删除生命周期)。
转移指标与 WebSocket 通知(TC0059、TC0062)
- TC0059:WebSocket 远程上传通知——一个客户端以隔离
--confdir运行--monitor,第二个隔离客户端以--sync --upload-only上传新文件;monitor 客户端必须收到 WebSocket 信号、处理/delta并在常规monitor_interval周期前下载远程上传文件; - TC0062:
--verbose --verbose下上传/下载转移指标正确生成,验证文件大小准确性、网络传输与端到端处理时长字段分离、传输速率以 Mbps 正确格式化。
本地优先与权威镜像(TC0063、TC0064)
- TC0063:
local_first = true正常同步期间本地父目录被重命名与进行中的下载竞争——本地文件系统竞态被正确检测与报告、下载失败被安全处理、客户端稳定且数据库无损坏、本地文件系统错误不被误报为 Microsoft Graph API HTTP 状态码错误; - TC0064:
mirror_local_state与local_first = true组合,在--resync --resync-auth期间删除本地已不存在的远程仅存文件与目录,使远程成为本地文件系统的精确镜像。
safeBackup 事务性数据保护(TC0066–TC0076)
这是套件中最深的冲突处理专题,围绕「safeBackup 备份文件」的事务边界展开:
- TC0066:正常替换事务——本地与在线均相对基线变更且在线更新时,规范路径保留权威在线副本、恰好一个 safeBackup 保存被替换的本地字节、无遗留
.partial文件; - TC0067:中断替换——32 MiB 本地修改文件 + 80 MiB 远程新版本 + 5 MiB/s
rate_limit+force_xfer_abort = "true",在下载完成至少 15% 后发送 SIGINT;中断不能移除或改动既有规范文件,恢复运行后成功提交权威副本、保留恰好一个 safeBackup、无.partial遗留; - TC0068:
--upload-only冲突——本地修改文件与在线新版本冲突时不下载覆盖、本地修改保留、safeBackup 保存本地字节并随后被上传到 OneDrive; - TC0069:远程移动目标冲突——远程移动协调进已被未同步本地内容占据的目标路径时,陈旧源路径被移除、被置换的本地内容恰好被保留一次为 safeBackup;
- TC0070:新文件上传冲突——本地无 DB 身份的旧文件与更新的在线文件同名冲突,本地旧文件保留、safeBackup 保存其字节且随后上传;
- TC0071:元数据仅差异身份验证——内容一致但本地 mtime 刻意偏离的冲突不得被误分类为需要 safeBackup 的内容冲突,协调后修正 mtime、不创建 safeBackup;
- TC0072:保存失败中止替换——预先占满
safeBackup-0001至safeBackup-1000全部分配范围,验证真实分配耗尽路径、规范文件保持原样、无.partial遗留、在线文件未被失败尝试改动; - TC0073:既有保存复用——已存在内容与元数据均匹配当前规范文件的
safeBackup-0001时复用之,不创建safeBackup-0002副本; - TC0074:干净重同步无冲突——
--resync本身在本地在线状态完全同步时不创建 safeBackup(与 TC0071 的区别:TC0071 无既有本地 DB 身份且故意引入元数据差异); - TC0075:远程删除 + 本地修改——唯一一个有意的「规范路径消失」safeBackup 工作流:权威在线删除协调时,本地修改字节被重命名为恰好一个 safeBackup 并上传;
- TC0076:重同步内容冲突——无 DB 基线且本地与权威在线字节真正不同时,重同步保留 pre-resync 本地字节为恰好一个 safeBackup,并将权威在线内容置于规范路径。
TC0071、TC0074、TC0076 三者共同证明:--resync 本身不会导致 safeBackup 创建——内容相同则不创建,内容真正不同则保留。
时间戳权威与同步状态(TC0077、TC0079)
- TC0077:系统时间权威安全门控,含 4 个 TA 场景——
--monitor启动时时钟漂移不安全则暂停同步、时间修正并重新验证后自动恢复(TA-0001);运行中的 monitor 时钟变为不安全时暂停、不传播队列中的本地变更、修正后恢复(TA-0002);--sync启动时确认阻塞性漂移则不同步并以失败退出(TA-0003);--disable-time-check显式覆盖时钟安全门后同步照常进行(TA-0004); - TC0079:重新设计的
--display-sync-status作为只读、双向协调评估命令,含 DS-0001 至 DS-0004 场景:干净的--single-directory基线输出Overall status: IN SYNC且查询不改变线上数据库/本地树/临时items-dryrun.sqlite3(DS-0001);force_children_scan = true全范围保守输出INDETERMINATE(DS-0001B);本地发散场景输出NOT IN SYNC、验证精确子 1 KiB 传输大小显示与skip_file排除文件不计数(DS-0002);双客户端 monitor 模型中远程变更的只读/children对比、2.09 KB (2144 bytes)传输报告与过滤(DS-0003);双向同时NOT IN SYNC报告(DS-0004)。
sync_list 与 skip_dir 场景深潜
TC0002 的 sync_list 校验是策略一致性测试:当且仅当所有涉及 fixture 树的同步操作都符合活动 sync_list 规则时测试才成功。39 个 SL 场景覆盖:
- 根目录包含的尾随斜杠/无尾随斜杠两种写法(SL-0001/0002);
- 非根按名包含、含嵌套排除的包含树、隐藏目录排除(SL-0003–0005);
- 命名目录内文件级包含、Programming 树根锚定包含(SL-0006/0007);
- Android/Web 递归构建输出排除、
.gradle、build/kotlin、.venv/venv、缓存与 vendor 目录排除(SL-0008–0014); - 复杂 Programming 规则集、跨 Programming/Documents/Work 的海量混合规则集、kitchen sink 压力规则集(SL-0015–0017);
- 尾随斜杠精确配置与无尾随斜杠变通的清理验证(SL-0018/0019);
- Projects 回归、根文件包含、
sync_root_files = true、前缀冲突安全、混合子树包含、通配符目录包含、glob 目录包含、深层通配符排除、递归 glob 排除、祖先保护、per-container 子排除、多树遍历、含空格路径、cleanup_local_files与sync_root_files覆盖(SL-0020–0039)。
TC0065 进一步验证 sync_list 过滤不会在正常移动协调前过早替换既有数据库父/路径状态,从而将远程目录移动识别为移动/重命名而非「新目录 + 源树本地删除」。
共享文件夹专项测试
OneDrive Personal 共享文件夹测试
Personal 共享文件夹测试验证通过共享文件夹快捷方式访问内容时的客户端行为。共享文件夹通过快捷方式样式访问可能由不同 OneDrive drive item 支撑的内容,在路径解析、元数据处理、快捷方式锚定与 sync_list 求值上引入独特行为。测试确保:
- 共享文件夹快捷方式被正确发现与遍历;
- 保留的共享文件夹拓扑被拉取而不产生 ghost 文件夹;
- 链接的共享文件夹内容同步时不破坏本地路径结构;
sync_list规则正确跨共享文件夹快捷方式边界生效;- 重命名、嵌套、含空格路径的共享文件夹保持正确锚定;
- 通配符、glob、包含、排除与清理场景正确;
- 安全测试变更不意外修改保留的共享文件夹 fixture 内容。
3 个专项用例(ci/e2e/testcases_personal_shared_folders/):--sync --verbose 干净拉取(0001)、--monitor --verbose 干净拉取(0002)、sync_list 校验(0003,含 24 个 SL 场景,覆盖根锚定包含、深层路径、嵌套排除、文件级包含、跨 WIDE_SET 快捷方式通配符、名称冲突与差异化排除、清理回归等)。
OneDrive Business 共享文件夹测试
Business 共享文件夹测试验证共享文件夹快捷方式与直接共享 Business 文件的同步行为。直接共享文件通过 --sync-shared-files 在 Files Shared With Me 下使用 Microsoft Graph Search 结果与 remoteType=file 身份物化(替代已废弃的 sharedWithMe 端点)。7 个专项用例(ci/e2e/testcases_business_shared_folders/)包括:
- 0001/0002:clean sync / clean monitor 拉取,不产生 ghost 文件夹;
- 0003:
sync_list校验,34 个 SL 场景覆盖 SharePoint 后端共享文件夹、用户自有共享文件夹、重命名快捷方式、根级快捷方式、跨驱动器上下文、跨多共享根、不同 drive identifier、深路径锚定、含撇号路径等; - 0004:直接共享文件拉取——验证
--sync --verbose --sync-shared-files正确枚举并物化Files Shared With Me拓扑,保留按用户分组与文件/文件夹分类,且当接收账户成为共享 Office 文件的当前作者/修改者时文件仍可被发现(不被错误过滤); - 0005:monitor 运行期间执行
--get-sharepoint-drive-id '*'视为 no-sync 操作,验证共享配置目录/状态数据库/认证上下文下的并发无冲突; - 0006:SharePoint 后端共享文件夹时间戳保留替换(SF-0001–0003,含 4 MiB 会话上传阈值与
--local-first保守冲突路径); - 0007:直接共享 Office 文件(DOCX)时间戳保留替换(DSF-0001),验证
driveId、id、remoteDriveId、remoteId在修改期间保持稳定,回滚为强制路径,且 PII 清理不改变用于构建合成共享文件层级活动的sharedBy元数据。
如何运行与重跑测试
主运行
在仓库根目录执行:
python3 -u ci/e2e/run.py
运行前需设置 ONEDRIVE_BIN、E2E_TARGET、RUN_ID 三个必需环境变量,并在默认配置目录(~/.config/onedrive 或 $XDG_CONFIG_HOME/onedrive)存在有效 refresh_token。SharePoint 目标还需在 ~/.config/onedrive/config.sharepoint 提供含 drive_id 的基础配置。
定向运行与场景过滤
ci/e2e/run.py 支持以下 CLI 参数:
# 只跑单个用例
python3 -u ci/e2e/run.py --case-id 0024 --debug --output-subdir tc0024-debug
# 跑多个用例
python3 -u ci/e2e/run.py --case-id 0002,0021,0024 --debug --output-subdir targeted-debug
# 只跑指定用例的指定场景(CASE:SCENARIO 格式)
python3 -u ci/e2e/run.py \
--case-id 0002,0021 \
--scenario 0002:SL-0004,SL-0018 \
--scenario 0021:RT-0001 \
--debug \
--output-subdir targeted-scenarios-debug
亦可使用环境变量 E2E_DEBUG=1、E2E_OUTPUT_SUBDIR=<subdir>、E2E_RUN_LABEL=<label>、E2E_SKIP_SUITE_CLEANUP=1、E2E_SELECTED_CASES=0002,0021、E2E_SELECTED_SCENARIOS_JSON={"0002": ["SL-0004"], "0021": ["RT-0001"]}。
两阶段失败自动重跑
仓库采用两遍 CI 模型(详见 ci/e2e/README-rerun.md):
- 先用
ci/e2e/run.py正常执行主套件; - 用 ci/e2e/rerun_failures.py 解析
results.json,仅对失败用例/场景以 debug 模式自动重跑:
python3 -u ci/e2e/rerun_failures.py \
--results ci/e2e/out/results.json \
--output-subdir debug-rerun \
--run-label debug-rerun
该脚本会读取主运行结果、仅收集失败 case ID、在可用时将场景类用例收窄到失败场景 ID、以 debug 详细模式重跑,并将输出写入 ci/e2e/out/debug-rerun/,同时把重跑计划写入 ci/e2e/out/debug_rerun_plan.json。details.non_rerunnable == true 的用例(如认证预检)会被跳过重跑。
结果工件与诊断
每次运行结束后,ci/e2e/out/ 下会生成:
results.json:结构化结果,包含运行元数据(target、run_id、run_label、account_label、debug、选中的用例与场景)与每个用例的id、name、status、reason、artifacts、details;logs/:每个用例的 stdout/stderr 日志与用例目录;state/:每个用例的元数据文件与失败时的items.sqlite3*数据库捕获(见 ci/e2e/framework/database_capture.py);run.log:主运行日志。
贡献新的测试用例
正如文档所述,该套件覆盖面虽广但并非穷尽,真实使用仍会暴露新边界情况。若发现覆盖缺口、未验证的场景或可改进的既有用例,欢迎按既有框架结构开发并提交新用例(见 ci/e2e/testcases/ 中既有用例的形态):在 build_test_suite() 中注册、在 E2ETestCase 基类提供的目录准备/断言/结果助手之上实现 run(context),并补充场景级 --scenario 过滤支持与 failed_scenario_ids 报告,即可融入现有 CI 与失败重跑流水线。
关键源码索引
- 测试框架入口:ci/e2e/run.py、失败重跑:ci/e2e/rerun_failures.py、重跑说明:ci/e2e/README-rerun.md
- 框架基础设施:ci/e2e/framework/(
context.py运行上下文、base.py测试基类、auth_preflight.py认证预检、utils.py工具与 QuickXorHash、result.py结果模型、manifest.py清单、database_capture.py数据库捕获) - 核心用例示例:ci/e2e/testcases/tc0001_basic_resync.py、完整用例目录:ci/e2e/testcases/
- 共享文件夹专项:ci/e2e/testcases_personal_shared_folders/、ci/e2e/testcases_business_shared_folders/
- 官方文档:docs/end_to_end_testing.md