# 测试与依赖 这份文档讲三件事:依赖怎么装、怎么升级;改完代码要跑哪些测试、CI 怎么分;新测试该写成什么样。 Windows 发布制品的覆盖升级在 Actions 的「Windows 覆盖升级验收」手动执行:填写已发布的起始版本、目标版本及目标制品的完整构建提交。工作流分别验证 ZIP 原位解压和安装包原位安装,每种路径覆盖默认数据目录与 `PEACH_DATA_ROOT` 指定目录,并上传日志。它使用已发布制品,不重新构建或发布;在线更新和失败回滚仍由 `scripts/smoke_online_update.py` 单独验证。 Release 工作流还在干净的 Windows runner 上运行 `smoke_update_tasks.py --apply`,使用临时账本验证安装接受正在运行的采集任务、暂停并保留任务标识、覆盖后自动续跑,以及配置保留。脚本默认只预演;本机可以验证 ZIP 与安装助手协议,安装包实装限干净的 Actions runner。 ## 环境与锁文件 纯文档 CI 仍在 Windows 和 macOS 执行 checks,但不安装前端依赖、FFmpeg 或配置 Chrome;混合运行时改动与未知输入保留完整工具。集成按同一选测边界识别文档,显式映射到运行时验收的 Markdown 不豁免全量锁。代码集成先等待全量锁,再取得集成锁,避免等待中的代码任务阻挡文档交付。 依赖由 uv 按锁文件精确复现。源码安装用 `uv sync --locked`。开发、测试和构建在隔离工作树里建自己的 `.venv`,工作树不碰正在服务的环境;主检出的依赖同步与迁移由重启流程负责,见 [运行与配置](OPERATIONS.md) 的「刷新源码运行态」一节(ADR-0091)。 安装全部测试依赖(先完成前端依赖安装和构建,再开始正式验证): ```text uv sync --locked --all-extras ``` 添加直接依赖并同时更新清单和传递锁文件;版本必须精确固定: ```text uv add "包名==版本" ``` 构建环境只选择构建依赖: ```text uv sync --locked --extra build ``` 提交 `pyproject.toml` 与 `uv.lock`。CI 用 `--locked` 拒绝过期锁文件;Dependabot 的 `uv` 生态负责更新。`uv pip install` 只用于临时环境或安装产物,不用来维护项目依赖。普通 pip 安装 wheel 的冒烟另外独立验证打包声明。 ### 接手 Dependabot 的升级 Dependabot 的 PR 一律在本地接管,不在网页上合: 依赖升级须同时提交派生产物。只改 npm 清单与锁文件时,vendor 版本记录或构建结果可能与 Git 中的文件不一致,相关门槛会拒绝;这本身不代表依赖存在兼容性问题。Test 工作流先完成所选前端检查,通过后才启动 Python、浏览器与 wheel 回归。缺少产物时先本地接管重算,不能跳过一致性检查后直接合并。 - npm 的两份清单各有一层派生产物:根 `package.json` 对应 `web/vendor/**` 与 `web/index.html` 的版本注释,`frontend/package.json` 对应 `web/dist/` 的主界面与独立页面包。Dependabot 算不出这些,它的 workflow 拿到的 token 又是只读的,推不回 `dependabot/**`,所以 `npm run check:vendor` 或前端产物检查会失败。 - uv 与 github-actions 没有派生产物,但 master 在本机集成、通常领先 origin。在网页上合会让两边分叉,回并要在主检出 master 上 merge,被 `scripts/githooks/` 拒收。 每周的升级在一个隔离工作树里一次接完: 1. 运行 `scripts/adopt_dependency_bump.py --all-open --co-author '<工具> (<模型>) <厂商 noreply>'`,看它列出的 PR 与各自的清单。 2. 加 `--apply`,按编号从小到大一个 PR 一个提交:取回分支,只把它自己对清单的改动三方合并套进来,npm 重算派生产物,uv 跑 `uv lock --check`。 3. 两个 PR 改到相邻行时脚本停下,报出冲突文件并在 `build/adopt-pr-<编号>.txt` 备好提交说明。按它印出的步骤解冲突、重算、提交,再跑一次 `--all-open --apply`;已接管的 PR 按提交说明跳过。 4. 跑 `test.ps1 full`,走 ready / integrate,推送 master 后按它印出的 `gh pr close` 逐个关 PR。PR 显示为 Closed 而不是 Merged,因为提交是在本地重做的。 5. 同一轮跑 `scripts/check_reference_updates.py check --cadence weekly --diff`,查 Dependabot 管不到的上游:按 sha 钉住的 amane 是否前移,Peach 代码直接消费或逐字复制的参考来源是否变化。审阅与 `accept` 按 `peach-reference-evidence` 技能;amane 前移单开分支升级。 单个 PR 用 `--pr <编号>`,流程相同。`.github/dependabot.yml` 把每个生态的 minor 与 patch 合成一个 PR,semver-major 照常一个包一个 PR,接管前先读变更说明。需要改代码的大版本在隔离工作树完成迁移和验证;TanStack Table 的大版本也由 Dependabot 检查。 版本来自 `src/peach/__init__.py`,已纳入 uv 缓存键;源码版本更新后再次同步会刷新安装元数据。缓存规则采用 [uv 官方动态元数据机制](https://docs.astral.sh/uv/concepts/cache/#dynamic-metadata)。 ### 每次发版检查 依赖升级是定版前的固定批次。发版授权包含检查、适用升级、兼容修改、派生产物、验证和集成,不能只列出可用更新就进入定版。 1. 开工先做只读发版审阅和两份 npm 高危审计,覆盖两份 Python 清单与锁、两份 npm 清单、Docker 镜像、GitHub Actions、SHA 固定的运行依赖及登记的参考来源。`scripts/release_review.py` 的 `--public-github` 模式匿名读取 GitHub 元数据;审计使用 `scripts/npm_audit.py`,分别指定根目录和 `frontend`。审阅先于升级方案、全量回归与制品构建。 2. 在隔离工作树中优先接管 Dependabot 的独立差集,保留来源,再核对稳定版本和未被 PR 覆盖的更新。审阅大版本迁移、真实消费者、字段语义、许可证和平台兼容性,固定版本与锁并重算 vendor 和前端产物。运行时遵守平台范围和官方支持周期;参考变化只作证据。不能升级的逐项记录新旧版本、具体兼容问题、失败证据和恢复条件,其余升级继续完成。 3. 完成定向回归和适用预览确认后,在重型验证前复核依赖及安全更新,记录提交、清单、锁与固定来源,冻结本批输入。检查未完成或仍有待处理安全更新时,先处理输入,不启动全量回归或制品构建;不能把冻结检查推迟到集成、打包或生产重启后。 4. 对冻结输入完成 Windows、macOS 正式全量与适用制品验证,再走 ready / integrate 和运行核验。同环境的有效测试按正式入口复用,只补受变更影响的检查;制品按其实际源码、锁、构建入口和目标平台判断能否复用。文档或维护 CLI 改动不触发运行内容未变的桥和 Docker 验证制品重建。版本提交的 CI 演练和标签发布仍遵守既有门槛。 5. 在干净 master 上运行 `release_tag.py --bump auto --apply`,保留定版及标签前的安全复查,再确认发行说明并继续 `--ship --apply`。冻结后出现的普通更新登记到后续批次;发现必须处理的安全更新时返回独立补充,重新冻结并验证实际影响,不整批无差别重跑。 `release_tag.py --bump auto --apply` 在写版本前调用 `release_review.py`,检查两份 Python 锁、两份 npm 清单的可用更新、Dependabot 待处理 PR、SHA 固定的运行依赖及其最新稳定发布,以及登记表中全部非 manual 参考来源。独立检查入口为 `scripts/release_review.py`;报告存于 `build/release-review.json`,含提交、时间、差异与逐项错误。Docker 与 GitHub Actions 的更新以 Dependabot PR 为线索,不据空 PR 列表断言全部最新。 网络失败记为「未取得」,其余检查继续;检查不全时版本文件保持原样。审计门槛仍由发布入口执行,不能用暂缓升级的说明放过高危漏洞。原文证据按 `peach-reference-evidence` 审阅后接受,人工笔记不被网页覆盖。升级批次是发布工作流程;现有 `release_tag.py` 不自动改依赖或创建升级分支。 用户手动提供的公开参考正文可通过 `--reference-evidence SOURCE=FILE` 明确用于本次检查。报告记录用户取证渠道、原始 URL 与正文 SHA-256,直接网络取证仍标为「未取得」;参数不修改来源登记、快照或后续发版的默认检查。 ## 验证频率 测试直接使用项目入口,由入口按[整机测试名额](#整机测试名额)排队,不另设 CPU、内存或进程数限额。每轮并发由 `-Jobs` / `--jobs` 选择,默认按本机核数取最多四路,显式正整数不设机器级上限。取消时只按已创建的 PID 清理本轮子进程树;全量测试与集成仍按代码一致性要求互斥。 Python 静态检查使用开发依赖 Ruff,随每个正式测试域扫描全仓自有 Python 文件,覆盖应用、脚本、测试和打包入口。规则为 Pyflakes(`F`)、Ruff 支持的 Pylint 错误规则(`PLE`),以及可变默认参数、`finally` 跳转、无效表达式和循环闭包规则(`B006`、`B012`、`B018`、`B023`)。生成的 `downloads_clouddrive_pb2.py` 排除;公开导出的导入用显式同名别名声明。命名、行数、空行和复杂度偏好不属于这套 lint 门槛。 无效转义由 Ruff `W605` 阻断,Windows 路径使用原始字符串或双反斜杠。正式入口和定向调试都将未处理的后台线程异常记为测试错误,保留原始 traceback;临时账本须在线程退出后清理。Starlette TestClient 使用开发依赖 `httpx2`,应用的 HTTP 客户端仍按运行时清单安装。 前端通过 `allowScripts` 逐项登记安装脚本策略,未登记脚本由 `frontend/.npmrc` 拒绝安装。`@sentry/cli` 使用锁文件中的平台二进制包,禁用额外下载脚本;`fsevents` 的可选原生构建也禁用,文件监听沿用 Node 提供的能力。升级后核对实际安装、构建和 CLI 可用性,不批量放行脚本。 文档与文案检查包含 seiso 稳定规则和最终状态检查,随正式入口执行。分类、范围、独立检查与预览规则用法见 [文档与界面文案](WRITING.md#检查与复核)。seiso 由开发依赖与锁文件固定,运行 Peach 不需要它。 不是每次都跑全量:本机按改动涉及的域选测,CI 按提交类型决定覆盖多宽。 调试先跑相关用例,冻结代码后运行一次 `auto`;不要手写逐域循环重复执行公共用例。测试失败先定向复现,修复后由 `auto` 判断哪些域需要补测。 | 场景 | 验证 | | --- | --- | | 本机修改 | 正式入口默认 `auto`,按影响域取并集;同代码、环境与范围的有效记录可复用;受信 CI 证明也可用于集成交付,见下节 | | 普通 PR | Python 3.14:macOS 与 Windows 均按影响域验证 | | 普通主线提交 | Python 3.14:相对最近成功且属于当前祖先的主线 Test,选择 macOS、Windows 的影响域及适用前端、浏览器与 wheel | | 实际依赖、迁移、共享测试设施、未知影响面 | Windows 与 macOS 的 Python 3.14 全量 | | 手动 CI | 完整系统矩阵 | | wheel | Windows 与 macOS 各一次 Python 3.14 独立最小安装 | | Release | 复用同 SHA 主线成功 CI;Windows 独立 EXE 与 Apple Silicon、Intel DMG 分别构建和验收 | Python 全量按文件稳定分片,Windows 四片、macOS 两片。`auto` 按影响域选择文件;唯一选测文件达到 150 个时,两平台复用各自的分片数;更小的 `auto` 两端均用单片。Windows 独立 Python 分片按 `scripts/ci-python-timings.json` 的成功日志耗时分配,不计已经交给浏览器任务的本机耗时先验;macOS 保持文件名轮转。每片使用独立 runner,仍按同一基线和影响域运行,汇总任务要求所有分片和计划选择的任务成功。分片子进程不签发记录。 Test 工作流的 `web-bundle` 在 Ubuntu 上统一执行 tsc、lint、Vitest、构建及产物差异检查;lint 同时检查无诊断且扫描文件数大于零。CI 的 Python 任务把这三个工具用例交给前端任务,把两个真实浏览器用例交给浏览器矩阵;同模块的契约测试仍执行。任务身份由固定工作流与 job 名识别,未知任务和本机保留完整测试。承担部分 CI 职责的运行不签发本机测试记录。 浏览器用例由 `web-e2e` 的六个 Windows runner 分担,每片有自己的服务、演示库与日志。`ci_plan.py` 按 `ci-browser-timings.json` 的实测秒数分配文件,新文件使用默认权重;每个文件恰好执行一次。每片经项目入口的 `-Focus` 运行分配的浏览器文件,首启文件始终归首次设置服务。它装 Node 24、前端依赖、ffmpeg,并经 `PEACH_E2E_CHROME` 指定 Chrome。本机浏览器入口与并发语义保持完整。 PR 与普通主线计划按改动选择前端、vendor、wheel 与浏览器任务,文档只执行适用检查;实际依赖、未知影响、无已验证基线与手动验证包含全部任务。`frontend-ready` 汇总所选前端检查,失败时不启动后续完整回归;未选择前端任务的计划可正常执行。产物差异以文件统计显示。`verified` 根据计划核对必需任务,缺失、失败、取消及必需任务跳过均判失败。Actions 工作流本身由固定版 actionlint 检查语法、表达式、依赖与脚本。PR 更新取消同 PR 的过期运行,主线 Test 按提交各自保留结果。GitHub 的计划任务与 Python 任务使用同一个已验证基线,不以最近一次失败的推送提交代替。 ### 受信 CI 测试证明 最后内容、测试和构建完成,适用预览确认后提交并执行工作树 `preflight`,再选择本机正式入口或 PR Test。输入冻结期间不补无关润色;新增失败由原入口按实际影响补验,不同时启动两条完整回归。 Test 的计划任务导出内容树、实际检出提交、基线、范围、完整矩阵与运行尝试,上传 `test-proof-<尝试编号>`。`ready --ci-run <运行编号>` 经 GitHub 官方 API 核对同仓库、相同 HEAD、成功 Test、内容树、完整计划和全部必需平台及分片;下载的证明 ZIP 须与服务端 SHA-256 相符。主检出核验工作树时,文件选择、导入索引、浏览器和权重均显式读取待交付根目录,索引缓存按根区分。全量计划不依赖已有差异基线。缺失、失败、取消、过期、fork 来源与内容不符均拒收。 证明协议和执行入口须与当前目标主线保持相同逻辑;逻辑改动先经本机完整验证,再成为主线的受信协议,Python 纯注释按内容指纹判断。协议文件集合由 `ci_test_evidence.py` 维护,见 [ADR-0151](adr/0151-trusted-ci-test-proof.md)。CI 中保留 `Fresh`,每个 runner 仍执行自己的必要任务;本机复用不依赖复制 runner 的临时目录。 回执只保存运行定位信息与核验摘要,`ready` 和 `integrate` 每次都重新查询远端状态,不把 CI 证明写成本机环境的通过记录。只重跑失败作业时,使用该运行各任务的最新结果,并核对原计划的同一内容;旧失败不会因合并多个尝试而隐藏。已取得有效本机记录时仍可沿用本机路径。CI 证明不替代明确要求的本机桌面、特殊硬件、真实数据或生产生效核验。 独立 Star 图工作流只生成图表并写入专用分支,改动选择 `tooling` 与工作流检查;混合提交仍按其他文件补齐影响域,未知工作流保留全量判断。 Python 分片上传完整测试输出;浏览器分片上传 TAP、服务日志及已脱敏网络日志,保留 14 天。npm 审计遇到 high 或 critical 漏洞直接失败;只有临时网络错误最多请求三次,在前两次失败后分别等待 15 与 30 秒,未知响应不当成通过。 GitGud 流水线(`.gitlab-ci.yml`)的 `verify-linux`、`verify-windows`、`verify-macos` 在分支与合并请求上跑改动域加本平台的平台敏感用例:基线是最近一条成功的主线流水线里、作为本提交祖先的那个提交,由 `scripts/ci_scope.py` 判定;先用正式入口跑 `auto --base <基线>`,选域与退回全量的规则同本机 `auto`,再用 `-Focus` 跑 `PLATFORM_TESTS` 里本平台的用例。取不到基线(首次推送、强推、接口不可达)、改了 `.gitlab-ci.yml` 本身,或改动落到必须全量的面时只跑一次全量。版本提交(`chore(release): 版本 X`)的主线流水线是发布演练:三平台全量、媒体构建、桌面安装升级与镜像验收都成功后登记候选;`--ship` 等演练成功才打标签。标签核对同一提交、验证任务和产物 SHA-256,发布已验收的相同文件与镜像,不重新构建。候选身份、保留与回收见 [ADR-0127](adr/0127-verified-release-artifact-promotion.md),全量范围见 [ADR-0119](adr/0119-mainline-changed-scope-release-full-suite.md)。 演练先读取发布桶真实占用,媒体编译可与正式回归并行;构建清单齐备后在安装冒烟前核对包含暂存与公开副本的精确峰值,候选登记与正式上传仍复查。媒体缓存身份绑定固定源码、构建脚本、工具链、平台与架构;GitHub 外层键和包内回执使用同一身份,两平台二进制和对应源码均逐文件校验。缓存未取得或校验不符时重新构建,缓存不代替独立制品验收。Docker 发布核对演练记录的 image ID、提交与版本,在桌面包和 Release 就绪后推送。版本发布与覆盖升级验收不取消进行中的同目标运行;覆盖升级需明确选择目标版本及完整构建提交。 浏览器用例覆盖 `frontend/e2e` 下全部 `*.test.ts`,包括子目录。`setup.test.ts` 由 `SetupE2ETests` 在首次设置服务上执行,其余文件在已配置的演示库服务上按文件并发、文件内串行。并发数取 `PEACH_E2E_CONCURRENCY`;未设时本机取逻辑核数的四分之一、上限 4,CI(`GITHUB_ACTIONS=true`)为 1。每个文件单独起一次 Node,限时 600 秒,取得自己的完整 TAP;空出的通道马上领下一个文件,没有批与批之间的等待。并发时文件按 `scripts/ci-browser-timings.json` 的实测秒数先长后短排队(没测过的按 30 秒算),测量动画、密度切换与等待态替换的文件(`tests/test_web_e2e.py` 的 `TIMING_SENSITIVE_SUITES`)在并发文件全部结束后逐个串行;并发为 1 时按设计决定、交互回归和路由冒烟的顺序逐个执行。任一文件失败或超时,整轮验证失败。并发的文件共用一个服务和演示库:用例触发的写请求只能落在别的用例不断言的状态上,否则用 `page.route` 拦下或归进时序敏感的串行文件。两组服务都断开外网:环境代理指向测试进程里的本机代理,Python 进程另由 `sitecustomize` 只放行回环地址,漏拦的外联当场失败、不等超时;系统联网检测地址由代理照常回答,服务保持在线。服务日志里出现 `[e2e-offline]` 记录,或代理收到请求时整轮失败,并列出目标;前后的访问记录指向触发它的接口,会去问来源的接口(如 `/api/jav/detail`)由用例用 `page.route` 或 `item-fixture.ts` 的桩回答。控制台在每个文件结束时输出成败与耗时;每个文件的 TAP 日志 `e2e-<文件名>.tap`、首启的 `setup.tap` 与服务访问日志 `serve.log` 保存在 `build/agent-verification/browser/`,CI 在测试结束后上传其中的 TAP 日志。 需要外部前置条件(Node、ffmpeg、Chrome 等)的用例,本机缺条件时跳过,在 CI(`GITHUB_ACTIONS=true`)里判失败,判定集中在 `tests/support/conditions.py` 的 `missing_prerequisite`。所以 `python` 矩阵里 `core` 以外的行也装 Node,Windows 行另装 ffmpeg 与 Chrome。 本机默认并行:入口传 `--jobs auto`(Windows `-Jobs`)。选中的快速检查先执行,包含仓库与资源位置、参考资料登记,以及前端类型、样式和文案检查;失败时不启动后续测试。普通测试切成并发数四倍的片,按实测耗时分配,每个子进程各领一片、先完成的接着领下一片。内部已并行的 Vitest 与浏览器容器分别独立执行,不与普通分片或彼此重叠。`-Jobs 1` 使用同一阶段顺序,普通分片串行运行。父进程汇总成败、用例数与耗时后签发一份记录,一片红整轮红。 每次运行把各测试文件的墙钟(含类级准备)并进共享记录目录的 `test-timings.json`,普通分片按它先长后短装进当前最空的一片(没测过的文件取中位数)。父进程把划分交给子进程,父子用同一份;CI 的 Windows 使用固定实测权重,macOS 按文件名轮转。测试账本、仓库夹具与端口须彼此隔离。运行器为每次运行创建 `peach-test-run-<时间戳>-*` 目录,`TEMP`、`TMP`、`TMPDIR` 与 `tempfile.tempdir` 指向它,分片子进程沿用同一目录,结束时删除;中断遗留超过一天的运行目录在下次启动时清扫。用例仍负责回收自己的临时资源。 分片结果分别显示真实退出码、是否取得完整报告及补验覆盖状态;失败明细列出分配文件、报告解析错误及是否因完成后未退出而回收。报告成功不代替正常退出,正文通过但覆盖未完整也不签发成功记录。后台线程测试在断言失败时同样释放事件、请求停止并等待线程退出,再清理临时账本。 正式记录的 `phases` 保存输入快照、历史记录读取、恢复规划、测试执行和结束核验耗时;测试执行内另列快速门槛、普通测试及各前端容器。父子阶段有包含关系,不能相加。`elapsed` 从取得输入快照前开始计时,不包含入口安装依赖、工具预检与取得全量锁前的等待。恢复规划在同一输入快照内复用域集合、测试导入图与路径影响;检查点发现输入改变时重新规划,不沿用旧图。 Windows 的路径、挂载、托盘、证书、进程编码、更新、认证及迁移属于 `core`。构建和工作流修改选择 `packaging` 与 `tooling`;测试调度自身仍全量。仅 uv 工具版本或项目展示字段变化不算依赖图变化;无法解析时全量。 人名对照等业务测试保留:修改相关域时执行,主线全量也执行。测试数据库从真实迁移生成模板,各用例复制独立临时库;迁移测试直接执行迁移。重试测试注入 sleeper 并断言退避序列。重复继承的测试只保留一份。 ## 写什么测试 纯 HTTP 请求契约可使用 `tests/support/web.py` 的 `route_client`:请求经过真实路由、中间件和依赖,不启动后台服务;调用方仍须准备完整临时账本。服务启动、恢复与关闭语义使用正常 lifespan,由集成测试覆盖。 浏览器入口通过 `PEACH_E2E_NET_LOG_DIR` 保存 Chromium 网络事件日志;模式为 `HeavilyRedacted`,文件位于 `build/agent-verification/browser/network/`,CI 与 TAP 一起上传。文件通过后删掉自己的网络事件日志,只留失败文件的。网络请求失败仍使测试失败;排查 `ERR_NO_BUFFER_SPACE` 时同时核对 TAP 与该次浏览器的网络事件,不根据错误字样推断机器资源状态,也不添加放行重试。 [Chromium 572515601](https://issuetracker.google.com/issues/572515601) 的 Windows 回环建连缺陷由 Playwright 默认禁用的 `TcpPortRandomizationWin` 规避,隔离 E2E 浏览器不另传 `--disable-features`:同名开关的最后一个值会覆盖整串默认值。`browser-launch.test.ts` 用真实 Chrome 启动参数与原生 Playwright 对照,确认默认列表保留且包含该项。生产浏览器、页面断言、请求失败判据及机器网络配置不变;独立的启动超时不能据此标为已修复。 测试应在用户可感知的行为错误时失败。页面的请求、缓存、选择、错误反馈和路由由组件测试与浏览器测试验证;CSS 层叠、主题、尺寸和交互后的样式由浏览器读取计算值。 源码检查集中在通用规范、隐私边界、产物、依赖和跨语言常量一致性。组件名称、变量名、某个函数是否被调用、端点字面量出现几次和文档的具体措辞,不单独设门槛。一个失败模式优先在最便宜且能真实触发它的层验证;组件已验证的业务分支,不在 Python 中再逐段比对其源码。浏览器保留真实导航、布局、焦点与层叠等需要浏览器才能成立的检查。 按下面的分工写: - 行为(点了发出什么请求、状态怎么变、算出什么值)写 vitest(`frontend/test/`)或 `tests/test_web_js.py`;后端调用真函数或真接口。 - 用户定过的设计决定写进对应区域的 `frontend/e2e/design-*.test.ts`(共用 `design-fixture.ts`),读 `getComputedStyle`;布局与运行期不变量进 `smoke.test.ts`。 - 源码文本断言只减不增,由 `tests/test_source_assertion_ratchet.py` 按文件计数拦截。已有行为或浏览器验证的实现文本断言直接清退;确有行为缺口时才补用例,并同步降低基线。 - 先列失败模式再写用例。异步请求的中间态用手动放行的 Promise 验证;假 fetch 在同一个 `act` 里就回话,会掩盖请求未完成时的时序问题。 - 修缺陷先写一条会失败的用例,看它红了再修;修完按同一写法搜别处,有同类就收成共用实现。没有行为缺口的改动(文案、纯样式)不补回归用例。 - 使用应用 lifespan 的测试应显式准备账本状态:正常后台服务使用完整迁移的临时账本,缺失或迁移未就绪的场景验证后台服务保持停止。用 `assertNoLogs("peach", level="ERROR")` 覆盖服务启动、请求和正常退出;故障注入用 `assertLogs` 核对预期原因,不能仅凭接口返回成功放过非预期后台错误,也不能全局屏蔽错误日志。 - `support.gitrepo.seed_repository` 的临时仓库在命令返回前完成 Git 自动维护;仓库局部设置 `maintenance.autoDetach=false` 与 `gc.autoDetach=false`,避免后台写入与模板复制、临时目录回收竞争。保留正常维护和清理错误,不修改机器的 Git 配置。 - 不写同义反复的用例:断言常量等于它自己、mock 掉被测对象再断言 mock 被调用,都证明不了什么。 ### 采集、任务与资料的回归边界 只覆盖本次真实风险,复用既有样本和适当测试层;相关修复可共享临时样本与验证,不把每个任务分别扩成全量。 | 修改范围 | 验证内容 | | --- | --- | | 番号解析与来源匹配 | 从真实失败文件名经过规范番号、站点查询到候选身份。覆盖确需等价的分隔符、前后缀和补零写法,以及不能合并的反例;只用站内写法不能证明流水线输入有效。同番号多作品不以字符串等价直接合并。 | | 暂停、取消与恢复 | 按已声明的控制边界分别核对父任务、已开始的工作、后继任务、浏览器及检查点;页面或状态字段显示暂停不能单独证明执行停止。 | | 来源失败与诊断 | 区分成功、正常无结果和失败;相关记录能关联任务、影片或文件、来源、阶段、异常原因及适用的构建/采集器版本,并验证脱敏。与故障无关的字段不强制填充。 | | 人工资料与来源刷新 | 按[人工资料与身份边界](SOURCING.md#人工资料与身份边界)验证字段保护,以及清空、恢复来源、修改归属和身份合并各自的语义。 | 旧编号、快照或已完成断点可能挡住修复时,按[升级生效范围](../.claude/skills/peach-worktree/SKILL.md#修复的升级生效范围)验证定向补修。测试结论说明实际环境、覆盖范围、跳过及未取得项,不以用例数量代替原场景验收。 ### 来源录制回放 `tests/fixtures/source-replay/<来源>/<番号>.json` 是站点真实响应的录制,`tests/test_metadata_replay.py` 用 [`sources/replay.py`](../src/peach/sources/replay.py) 的 `ReplayTransport` 离线重跑同一次 `query`,结局须与录制当日一致:成功时整份 payload 逐键相同,失败时细档与措辞相同。回放期间套接字建连与域名解析一律抛错;录制里没有的请求、录了却没被问到的请求都判失败。改了取页方式或解析结果,按差异核对后重录。 录制按「方法 + 规范化 URL + 请求体 SHA-256」匹配,不比请求头。响应只存状态、最终地址与 `content-type`;图片只存尺寸与哈希,回放时生成同尺寸灰图;视频只存字节数。录制里的 payload 是当日解析器的输出、经人工过目,用例另核番号、标题、日期、女优、厂牌与封面地址的形状。 录制只由 `scripts/record_source_fixtures.py 来源:番号` 联网取得,CI 里该脚本直接拒绝。它把代理设置、连接设置与生产冷却记录复制进临时根再请求,冷却期内的站照样不发;不写 ledger,也不写生产冷却。默认不带 Cookie;`--with-credentials` 只用于不登录拿不到作品页的站,Cookie 值、CSRF 令牌与账号标识换成固定假值。去掉脚本、样式等与解析无关的区块后,脱敏与瘦身两步各回放一次,结局变了就不采用这一步。连接失败、冷却、限流、验证页、封禁与地区限制不写入录制文件,记为「未取得」。已有录制要加 `--update` 才重录。番号取站上公开作品,不从个人馆藏挑选。 ## 正式入口 测试只从下面两个入口跑,入口负责选测、签发测试记录和环境预检,自己拼的命令拿不到有效记录。 Windows 按影响域验证: ```powershell & .\scripts\test.ps1 ``` macOS 按影响域验证: ```sh ./scripts/test.sh ``` 显式全量用 Windows `-Scope full` 或 macOS 首参数 `full`。入口通过 `scripts/test_environment.py` 准备 Python 依赖,再核对源码位置、选测并记录慢测试。隔离工作树按 `uv sync --locked --all-extras` 同步自己的 `.venv`;缺少本地环境时用主检出的 Python 启动准备,测试仍在新建的本地环境里运行。同步保留启动解释器的 Python 版本,忽略外部 `VIRTUAL_ENV` 和 `UV_PROJECT_ENVIRONMENT`,拒绝工作树环境指向主检出。 主检出只按 ADR-0091 只读检查依赖;缺包或检查失败时以 `3` 退出,依赖变更由重启流程执行。找不到 uv、锁文件过期或同步失败也会停止测试。前端依赖与构建仍按上文安装。完成安装和编辑后再启动最终验证;运行中发生改动时,完整批次按下述规则保留未受影响的文件结果。 测试入口按下文的[整机测试名额](#整机测试名额)排队;全量验证与集成另按仓库代码一致性锁互斥,浏览器和 Vitest 的阶段顺序由测试入口安排。 全量先单独跑一片秒级检查(`test_runner.GATE_TESTS`:仓库策略、编码、文案终态、上下文预算、源码断言棘轮、复杂度、Python lint、外发代理、仓库整洁与依赖清单,合计约 1 分钟),有一项不过就不起其余分片。 全量失败后,入口从逐条结果里取出失败的 Python 用例、e2e 文件与 vitest 文件,不超过 6 个文件时用定向入口逐个单独重跑一次。单独重跑通过的,记录照样签为通过,名字写进记录的 `flaky` 字段并打印出来;单独重跑仍失败、失败面更大、或浏览器容器整个没起来的,按真实失败处理。CI 的独立 Python 分片同样处理;浏览器分片走定向入口,由 `-RerunFailures`(macOS/Linux 为 `--rerun-failures`)开启同一处理。偶发通过时写进测试结果历史;在 GitHub Actions 上另标为警告并写进作业摘要,PR 上可见。同一文件反复偶发,说明它的等待写法或时限需要修;`python scripts/test_history.py flaky` 按次数排行,`--folder` 可另读下载的 CI 历史制品。 本机全量验证与代码集成共用 `full-suite.lock`,从取得代码和环境快照一直持有到记录写入完成。仅修改两份 README 或 `docs/` 下 Markdown 的集成只取得 `integration.lock`,仍核对工作树、验证记录与冲突,不等待无关全量测试。 锁忙时按到达先后排队:等待者在锁旁的 `full-suite.lock.queue/` 放一张以纳秒时刻开头的票, 前面没有活票时才去抢锁,拿到即撤票;提示里打印持有者与前面排队的个数。票主进程退出后, 它的票由后来者清掉。测试入口默认一直排队,不再叠加比全量耗时还短的上限;`integrate` 最长等 30 分钟,超时撤票退出,不合并。集成事务本身仍由 `integration.lock` 串行保护。部分域验证与 CI 分片不签发独立的本机全量记录。 代码集成排队期间目标分支前进时,`integrate` 拿到两把锁后在工作树里把分支 rebase 到目标上,按统一入口的步骤补验 `auto`,用 `--force-with-lease` 推送工作者分支,等 PR 头跟上新提交再合入;回执的 `refreshed` 记下 rebase 前后的提交。补验由集成进程直接派出工作树解释器,以 `--full-lock-held` 沿用集成进程持有的全量锁,运行器核对锁的持有者在自己的祖先链上(Windows venv 的 `python.exe` 是启动器,中间多一层进程)。两边改了同一文件时不自动 rebase,照旧拒收并要求复核;rebase 冲突时撤回;补验未通过时不推送、不合入,日志在工作树 `build/integrate-verify.log`。补验期间一直持锁,后面排队的集成按 30 分钟上限等待,测试入口一直排队。文档集成不持全量锁,目标前进时仍要求在工作树 rebase 后重新验证。 锁旁的持有者信息用独立文件锁保护读写和清理;主锁仍负责验证与集成互斥。等锁线程关闭记录文件后,持有者才删除记录,避免 Windows 文件共享冲突。 测试入口退出码:`0` 验证有效,`1` 用例失败,`2` 参数或锁等待失败,`3` 环境预检失败, `4` 验证期间代码或依赖变化,尚未取得当前状态的完整记录。Windows 托盘遇到 `4` 最多执行三轮完整验证, 只有取得有效记录才继续打包;用例失败直接停止。 正式入口会在创建测试分片前探测 PATH 中的外部工具。工具路径存在但当前权限不能启动时, 入口以一条环境结论退出,不把同一个 `CreateProcess` 权限错误散落到多个用例。整条 `scripts/test.ps1` 要在正常 PowerShell 权限下运行;权限不足时补权限再原样重跑, 不拆成单测也不跳过用例。 判失败的只有本次所选域真的会用到的工具,其余启动受限的工具只打印一行提示:受限环境里 ffmpeg 起不来是事实,但它不该挡住一次只改文档的 `checks`。域由选中的测试源码推出来。 确认本次无关时用 `PEACH_SKIP_PREFLIGHT=1` 整体跳过预检;分片子进程不重复预检。 ### 整机测试名额 本机几个会话同时跑全量和浏览器用例会把整机压满,有时限的用例随之误报失败。测试入口因此按整机名额排队([ADR-0172](adr/0172-machine-wide-test-slots.md)):名额默认 2 个,环境变量 `PEACH_TEST_SLOTS` 可调整,各会话应使用同一个值。名额是 Windows `%LOCALAPPDATA%\peach-test-locks\slots\`、macOS/Linux `~/.local/state/peach-test-locks/slots/` 下的 `slot-.lock`,本机所有检出与工作树共用。 | 运行 | 占用名额 | | --- | --- | | 待跑文件的预计串行耗时达到全量的 60%,含新开的 `full` | 全部,从 1 号起按顺序逐个取 | | 其余 `auto`、显式域与续跑 | 1 个 | | 含 `frontend/e2e/` 文件,或点了超过 10 个测试文件的 `-Focus` | 1 个 | | 其余 `-Focus`:最多 10 个 Python 或 Vitest 测试文件 | 不占 | | 复用有效记录、CI 作业、持有名额的运行派出的分片与隔离重跑 | 不另占 | 预计耗时按 `test-timings.json` 里各文件的本机实测秒数相加,没测过的文件取已测文件的中位数,浏览器冒烟不低于先验值;只看 `full` 标签不够,`auto` 选中多个域时跑的文件接近全量。 等待者在 `slots.lock.queue/` 放一张排队票,按到达先后取名额。排在最前面的全量只取到一部分名额时继续留票,后到的运行不会插到它前面。等待期间每分钟打印一次各名额的范围、pid、工作树路径、开始时刻与已运行分钟数。排队不设时限;只有 `machine_lock.py --wait` 这类显式时限会超时,以 `2` 退出且不执行命令。 名额是操作系统文件锁,持有进程退出或被强行结束即释放;pid 已退出或已被别的进程复用的持有记录不再报出。持有名额的运行把自己的 pid 写进 `PEACH_TEST_SLOTS_HELD`,它派出的子运行据此不再排队。`PEACH_TEST_SLOTS` 与 `PEACH_TEST_SLOTS_HELD` 不进[记录的环境身份](#记录的环境身份),名额设置不同的会话仍承认彼此的记录。 锁的顺序固定为全量锁、同状态验证锁、整机名额。全量先取得上文的 `full-suite.lock` 再排名额;`integrate` 补验时沿用集成进程的全量锁,补验运行再取 1 个名额;持有名额的运行不再等待别的锁,所以两者不会互相卡住。名额只在确实要运行用例时排队,复用记录不等待。失败文件的隔离重跑在本次运行持有的名额内进行,此时本次分片都已结束;没有名额的定向调试先排 1 个再重跑。 排队等待是正常现象,不要调小或调大 `PEACH_TEST_SLOTS` 插队。不经测试入口的重负载命令用 `scripts/machine_lock.py -- 命令` 包住,它与全量一样取满全部名额。 ### 交付预检与 PR 绑定 最后交付提交完成后,先在当前隔离工作树根目录运行元数据预检,再开始耗时验证或推送。预检核对工作树干净、目标分支已纳入,以及提交主题和署名。 Windows(PowerShell 7)运行预检: ```powershell & .\.venv\Scripts\python.exe -X utf8 .\scripts\agent_worktree.py preflight ``` macOS/Linux(zsh)运行同一预检: ```zsh ./.venv/bin/python -X utf8 scripts/agent_worktree.py preflight ``` `preflight` 不安装依赖、不计算测试环境身份、不读取或签发测试证明,也不访问远端 PR。退出码为 `0` 只表示元数据通过;`tests` 与 `pull_request` 仍是 `not_checked`。`ready` 和 `integrate` 继续使用相同元数据判据,并核对当前内容对应的正式测试记录。 `integrate` 在合并前通过工作树的 GitHub CLI 仓库上下文取得 PR。PR 必须开放,`headRefOid` 等于工作者当前提交,`baseRefName` 等于集成目标分支;成功回执保留 PR 链接及这两个身份。未取得 PR、字段无效或身份不匹配时停止,不改变主线内容。此核对不替代 PR 审阅、对应提交的 CI 与既有预览确认。 ## 定向调试与局部记录 Windows 的 `-Focus` 接受 Python 模块、类、方法或仓库相对路径,可传数组;通过 `pwsh -File` 调用时也接受一个逗号分隔参数。macOS/Linux 对每个选择器重复传 `--focus`。入口统一去重,拒绝空项并核对源码及隔离依赖。选择器不存在、浏览器路径超出 `frontend/e2e` 或与分片混用时拒绝执行。浏览器用例只收单个 `frontend/e2e/*.test.ts` 文件,不收目录;要跑全部 e2e 时把文件逐个列进数组。 浏览器冒烟逐个文件执行,一个文件失败仍跑完其余文件,最后把各失败文件的输出与日志路径一起报出;一轮全量就能看到所有 e2e 失败。搜索建议、键盘列宽调整和嵌套弹层的失败输出另保留当时的输入、焦点、弹层、等待态与无障碍树,原异常作为 cause 保留。取证不延长等待、不重试交互,也不忽略运行期错误。 React Aria 表格首次取得焦点时先建立行导航。键盘列宽测试先进入行并确认公开焦点状态,再聚焦手柄,核对真实 `activeElement` 后按 Enter;不把直接调用 `focus()` 已返回当成焦点仍在手柄的证明,也不用等待时长或重复按键消除竞态。 定向调试 Python 回归: ```powershell & .\scripts\test.ps1 -Focus test_test_evidence ``` 定向调试一个浏览器文件,包括它的桌面和手机用例: ```powershell & .\scripts\test.ps1 -Focus frontend/e2e/jav-detail.test.ts ``` macOS/Linux 的相同入口: ```sh ./scripts/test.sh auto --focus frontend/e2e/jav-detail.test.ts ``` 定向调试一个或几个 vitest 文件(路径从 `frontend/test/` 起),只跑这几个文件: ```powershell & .\scripts\test.ps1 -Focus frontend/test/jav-card-title.test.ts ``` 定向调试不签发记录,不能作为 `ready` / `integrate` 的验收证明。浏览器文件选择只在调试环境生效;正式入口拒绝残留的 `PEACH_TEST_FOCUS` / `PEACH_E2E_FILES` / `PEACH_VITEST_FILES`,防止局部运行被签成整域。浏览器文件失败或超时时保留它的完整 TAP 与服务日志。 浏览器沿用 Playwright 的默认进程模型与静音设置,不限制渲染进程数,也不把 GPU 或音频服务强制并入浏览器进程。原生浏览器启动限时 60 秒,页面主体等待限时 15 秒,每批限时 600 秒;进程启动与页面行为分别验收。需要任务状态桩的页面通过 `visit` 的准备回调在首次导航前安装响应,等对应的 React 主体出现后再检查任务状态;进行中的任务不作为主体等待态。页面主体等待失败时保留 URL、关闭状态、已收集的运行期问题与无障碍树,夹具关闭本次浏览器上下文。 Windows Release 工作流使用 `uv sync --locked --all-extras` 准备完整依赖。安装目录回归与 PyInstaller 构建共用这份 venv,测试入口按完整锁文件核验依赖。 Windows 独立制品验收的宿主从同一检出的 `scripts/` 加载辅助验证模块,并按发行锁核对随包采集工具。临时应用与采集工具自检清除 `PYTHONPATH`,使用移除开发工具的 PATH;源码路径只供验收宿主使用。 macOS Release 使用 `macos-15`(Apple Silicon)和 `macos-15-intel`(Intel)分别构建,解释器、依赖与目标架构必须一致。独立验收任务只下载候选制品与冒烟脚本,挂载只读 DMG,核对 Applications 链接、许可证、签名与原生架构,再执行 `scripts/smoke_macos.py`。该脚本将应用移到源码树外,在移除开发工具的 PATH 下验证首次设置、迁移、单机账本、登录、前端资源与配置保存,数据全部使用临时目录。所有平台验收成功才发布;普通 push 不构建安装包,手动运行 Release 不上传公开资产。 `auto` 扫描同环境的有效记录,按测试文件合并 24 小时内、未受输入差异影响的成功结果;记录数量没有固定搜索上限。每项保留原通过时间,最新的失败或未完成状态阻止旧成功结果恢复。缺少、损坏、过期或未来时间的证明不计入覆盖;单份损坏记录不影响其他候选。`-Fresh` 始终实际执行请求范围,显式 `full` 默认也实际执行;`-Resume` / `--resume` 允许全量验证按完整批次来源续跑,与 `Fresh` 互斥。 在当前隔离工作树根目录续跑全量验证: ```powershell & .\scripts\test.ps1 -Scope full -Resume ``` macOS/Linux 使用相同的恢复规则: ```sh ./scripts/test.sh full --resume ``` GitGud 的三平台验证使用正式恢复入口,通过 GitLab 原生缓存保存证明 JSON。缓存按作业、分支和保护状态隔离,成功或失败后均保存;锁文件不进入缓存。重试作业恢复缓存后,仍逐项核对当前代码、依赖、环境、通过时间和完整批次。缓存缺失或证明无效时执行必要测试,不能仅凭缓存存在取得通过结论。并行分片在预计总耗时相同时按文件数分配,实测耗时为零的文件也会分散到非空分片。 正式父运行在开始时原子保存待验证状态,每个分片完成后立即保存检查点。失败批次仍保留成功文件、成功补充用例及其时间;整文件状态不覆盖已取得的单项结果。共享输入变化和 `Fresh` 同时作用于文件及其补充用例。快速门槛失败时,其余文件保持未完成。进程中断后,下一次 `auto` 在所需范围内补齐缺少的文件,串行与并行使用相同结果模型。分片报告必须完整且格式有效,结束码须与报告一致;异常退出不能产生该片的成功证明。分片写出完成报告后仍未退出的进程,等待 15 秒后回收该片的进程树,不给尚在执行的测试设置额外时限。 浏览器与 Vitest 容器内按外部测试文件保存完成结果,只有逐条输出不能证明整个文件完成。恢复计划绑定当前输入快照、完整文件集合及每个省略项的成功时间。Python 容器用例自身也必须有成功证明,才能连同其外部文件一起省略;容器的后置检查失败仍需补测。选择参数只在对应容器用例执行期间启用,普通 Python 用例不继承这些参数;失败或退出时恢复环境。外部选择仅由正式父运行生成,`Focus` 和独立 CI 分片不签发正式记录。 全量证明还要求所有文件与容器检查属于同一个完整批次。独立局部运行可以补齐所需域,不能拼成 `full`;有完整批次来源的中断或失败运行,补齐缺少项后可恢复全量证明。每次写入时清退写盘超过 24 小时的记录、持锁说明与残留临时文件;锁文件和非记录文件不动。 选测比较文件内容:Python 只有注释或格式变化、npm 清单只有 description/keywords 变化、TOML 只有注释或格式变化时选 `checks`。Python docstring、运行时字串和类型注释属于有效内容。Python 构建元数据变化选 `packaging`,实际依赖变化、文件模式变化、解析失败和未知影响面保留完整验证。 新增、删除文件按所属功能域选测;已有文件的执行权限变化和符号链接保持 `full`。 域、补充用例、路径映射与 CI 职责登记在纯数据文件 `scripts/scope_registry.toml`,由 `test_runner.py` 读取。它不属于执行协议,按登记差异选测,也能用 CI 证明交付。`change_impact.py` 按集合比较前后两份登记:任何位置新增精确 `test_*.py` 文件名、补充用例,或新增、扩大路径映射时,选这些条目相关的新旧域与 checks(checks 里的 `test_test_planning.py` 核对选测计划与登记完整性);只改注释选 checks。删除或缩小映射、改序、通配符、新域、让已有前缀失效的新前缀,以及 `[ci]` 段的任何变化仍按完整验证处理。普通 `scripts/` 脚本已有 tooling 前缀映射,同域时不再添加重复的精确映射。记录快照和 CI 使用同一内容判据;无法识别的旧记录保持保守判断。 改 `scripts/<名字>.py` 时选 tooling,再按文件补上导入它的测试:沿 `scripts/` 内部的导入链传递,不穿过 `peach` 包。脚本之间的导入链有界,单个脚本最多牵到十来个测试文件。工作树、集成、测试证明与名额这几份重型交付测试登记在 `delivery` 域,不在 tooling 里,只在改到它们用到的脚本、改它们自己或跑全量时运行。按文件补选的测试名直接出现在选测结果里(例如 `tooling, test_agency_reject.py`),记录、续跑与 CI 计划与域同样处理。 `resources/locales/*/server.json` 与 `cli.json` 改动时,在 web 与 tooling 之外按文件补上读到改动条目的测试:源码字符串里写了条目键,或写了旧原文中不短于 6 个字的片段。没有前后内容可比时,按整份文件的全部条目找读者。 `src/peach/` 的已知模块合并直接导入它的测试所在域,名称或显式映射不排除直接消费者。按名字推不出测试文件的模块,还并上直接导入它的源码文件按同一套规则推出的域;互相导入的一组模块合起来算。导入者推不出域、谁都不导入它,或未知模块被共享测试设施 `tests/support` 使用时仍 `full`。不沿导入链一路扩散:函数里的延迟导入把几乎所有模块连成一团,传递闭包等于全量。随应用分发的 `resources/` 按加载它的模块与打包面选域;`.gitlab-ci.yml` 与 `MANIFEST.in` 在本机选 `packaging` 与 `tooling`(主线流水线改 `.gitlab-ci.yml` 时三平台仍跑全量);只登记在 `core` 或 `packaging` 的测试文件改动时跑登记它的那个域。 README 的 Python 下限和双语入口由 checks 的安装契约检查,普通文档不选择整个 tooling。静态文件输入识别以仓库根及其别名为依据,临时夹具的同名写入不属于仓库读取。缺失文件不进入当前快照,删除由前后文件集合识别,暂存或提交相同删除不会改变内容证明。 运行中输入改变时,无论该批次是否全部通过,都按差异保留未受影响的成功结果和原时间;退出 `4`,随后 `auto` 补齐缺少项。独立 Python 测试文件的逻辑变化使该文件、直接或间接导入它的测试及公共门槛失效;浏览器测试文件变化使该文件及相应容器检查失效。共享设施、未知范围、执行模式或环境变化仍按完整影响范围重新验证。 首次设置目录 `frontend/src/react/pages/setup/`、素材 `resources/setup/` 和独立页面产物 `web/dist/peach-pages.js`、`web/dist/peach-pages.css` 的补测保留主应用浏览器结果,仍检查首次设置浏览器流程、全部相关 Python 契约、组件与打包。首次设置浏览器用例集中在 `frontend/e2e/setup.test.ts`;新增独立页面浏览器容器时须同步扩充这份对应关系。主应用产物、共享样式或公共组件同时改变时,主应用浏览器结果照常失效。 测试记录格式升级时,主检出的入口可能无法识别新格式。先在工作树通过 `ready`,再由主检出调用该工作树中已验收的 `scripts/agent_worktree.py`,用 `--repo` 指定主检出并执行 `integrate`。该方式仍检查测试记录、目标分支和集成锁;不要手工改写记录或跳过门槛。集成后主检出使用同一版本的入口。 PR 与普通主线的浏览器 CI 根据界面、Web API、认证与浏览器用例选择;普通后端单测不单独触发浏览器任务。工作流按职责选测,发布工作流触发打包验证,看板等管理工作流只触发工具检查。无可用基线、未知影响与手动完整验证覆盖全部 CI 任务,发布演练和制品验收按其独立门槛执行。 ## 记录的环境身份 记录只在「代码、环境、范围」三项都匹配时可复用,环境那一项由 `scripts/test_evidence.py` 的 `environment()` 算成一个摘要:Python 版本、实现与运行时文件内容、规范化的已安装包名称和版本、平台、影响行为的环境变量、前端安装锁的规范化 JSON、实际 Chrome 文件内容,以及 node/npm/git/ffmpeg/ffprobe/openssl 六个外部工具。相同运行时和依赖位于不同工作树、安装锁只有排序或缩进差异、CI 运行编号或工作目录变化,不改变环境身份。CI 工作流和 job 职责、浏览器安装状态与内容变化仍参与判断。 测试入口强制设置的 `PEACH_REPORTING_TEST_MODE` 防外发标记不参与环境选择;入口源码仍参与代码快照。 GitLab 的作业令牌、容器仓库密码和依赖代理密码按是否存在记录;`CI_REPOSITORY_URL` 保留协议、主机、路径、用户名及认证存在性,密码值不参与身份。`CI_JOB_RETRY_COUNT`、`CI_JOB_STARTED_AT_SLUG` 和 `CI_BUILD_NETWORK_NAME` 表示本次运行的计数、时间与网络名称;`CI_TRACEPARENT` 和 `CI_TRACESTATE` 标识作业的分布式追踪上下文。这些运行元信息不参与身份。作业职责、覆盖模式和应用行为变量仍参与判断。变量含义见 [GitLab 预定义变量](https://docs.gitlab.com/ci/variables/predefined_variables/)。 uv 只探针、不进指纹:它负责建环境,装出来的解释器与包已经逐个记在摘要里,而它自己由 winget 自动升级。把它的版本也算进去的话,升级当天全部记录一起失效,被验证的那套环境 却一个字节都没变。 工具身份取它**自报的版本**,不取 PATH 解析到的路径与文件字节。同一套 Git 安装在 PowerShell 里解析到 `Git\cmd\git.exe`、在 Git Bash 里解析到 `Git\mingw64\bin\git.exe`, 两个前端字节不同而版本和行为相同;按路径记身份会把记录绑在 shell 上:在一个 shell 里 跑出记录,换另一个 shell 跑 `integrate` 就报「缺少有效测试记录」,回到工作树跑 `auto` 又说「复用记录」,两句查的是两个键,代价是白跑一遍全量。 改环境身份、内容签名或记录结构时,主检出的旧算法可能算不出新键或读不了新记录,无法验证带着新格式的分支。 那一次的 `integrate` 用分支自己的脚本和判据,并把仓库指到主检出;不重复执行已取得有效记录的测试。`--repo` 是顶层参数, 放在子命令前面,放后面会被 argparse 拒收: ```powershell & .\.venv\Scripts\python.exe -X utf8 <工作树>\scripts\agent_worktree.py ` --repo <主检出> integrate --branch <分支> ``` ## 测试结果历史 正式入口与定向调试每次运行都把逐条结果追加进测试结果历史,用来统计每条测试抓到回归的比率,并区分抖动、期望过时与环境失败。实现在 `scripts/test_history.py`。 文件是 Git common directory 上一级的 `build/test-history/YYYY-MM.jsonl`:本机落在主检出的 `build/` 下,与测试记录 `build/agent-verification/` 同级,所有工作树共用;CI 上就是作业目录的 `build/test-history/`,由流水线作为 artifact 上传。JSON Lines 按月分文件、只追加,多个进程同时写时由旁边的 `.lock` 串行。 每次运行先写一行运行头: | 字段 | 含义 | | --- | --- | | `type` | 固定为 `run` | | `run` | 本次运行的编号,逐条结果用它关联 | | `time` | 写入时刻 | | `scope` | 请求与实际范围,如 `auto:catalog web`、`full:full`、`focus:<选择器>`;CI 独立分片带 `shard i/n` | | `platform`、`python` | 平台与解释器版本 | | `head`、`branch`、`worktree` | 提交、分支(分离头指针时取 CI 的分支变量)与工作树路径 | | `ci` | `CI`、`GITLAB_CI`、`GITHUB_ACTIONS` 任一非空即为真 | | `files`、`count` | 本次跑到的测试文件模块名与用例总数 | 之后逐条写 `type` 为 `test` 的行:`run`、`id`、`outcome`(`pass`、`fail`、`error`、`skip`)与 `seconds`,失败与报错另有 `message`,取最后一行异常,遮掉 `token=`、`password=` 一类的值,截断到 200 字。Python 用例名为 `模块.类.方法`,vitest 为 `vitest:文件 > 分组 > 标题`,浏览器用例为 `e2e:文件 > 分组 > 标题`。 偶发另写一行 `type` 为 `flaky`:`time`、`head`、`branch`、`worktree`、`ci` 与单独重跑通过的 `selectors`。 为控制体积,只逐条写非通过的用例与耗时不少于 5 秒的通过用例。一次全量约一万条结果,全部逐条写约 2.4 MB;按这个口径约 250 行、75 KB。某条用例跑了几次,用运行头的 `files` 推算:文件在场、没被记成 `skip` 的用例都跑过;逐文件耗时另见 `test-timings.json`。 写历史失败只打印一行告警,不改变测试判定。历史不经环境变量传递,也不在被快照的工作树里,测试记录的环境指纹与有效期不受影响。用例里调用运行器的那些测试不写真实历史,也不取走外层运行收集中的 vitest 与浏览器结果。