react-spring Parallax 测试应用指南维护规则、快照测试与端到端验证【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-springreact-spring/parallax是 react-spring 中基于弹簧物理实现滚动视差效果的子包而 packages/parallax/test/README.md 正是管理其测试应用test app与端到端测试的唯一权威说明。这篇指南将围绕该文档展开介绍 Parallax 测试应用的用途、维护红线、快照测试的运行机制并结合仓库中的单元测试与 e2e 测试源码讲清「如何在不破坏现有测试的前提下为 Parallax 新增测试」。读完本文你将掌握这套测试设施的结构、命令与回归用例设计思路。测试应用的角色为 Parallax 提供可运行的真实载体文档开篇点明了packages/parallax/test/目录的定位——「This app is here for testing only」。它不是一个示例 Demo 站而是为验证 Parallax 组件行为而搭建的最小可运行 Vite 应用。从目录结构看packages/parallax/test/它是一个标准 Vite React TypeScript 应用main.tsx通过ReactDOM.createRoot挂载App并启用了React.StrictMode用于在开发期暴露潜在副作用问题index.html标准的 Vite 入口 HTMLvite.config.ts关键配置是将react-spring/web别名解析到仓库源码targets/web/src/index.ts从而让测试应用直接运行未打包的源码而不是已构建产物。该应用在 App.tsx 中用wouter路由组织了两个页面/vertical纵向视差与/horizontal横向视差两者共用同一个BaseDemo组件。BaseDemo演示了 Parallax 的核心用法pages{3}总空间为 3 页两个普通层一个offset{1} speed{1}的默认层以及一个horizontal{!horizontal}的反向运动层一个sticky{{ start: 1, end: 2 }}的吸附层用于验证 sticky 行为一个带按钮的层点击后调用parallax.current.scrollTo(1)触发编程式滚动。配套的 App.css 为各层定义了区分色与布局类。需要说明的是该应用并非当前仓库测试流水线的必跑环节根目录的test:e2e直接由 vitest 驱动见下文它的存在意义在于为人工调试、为未来可能接入的浏览器型快照/回归测试提供一个开箱即用的载体。维护红线这是测试专用资产改动需谨慎文档给出了两条明确的维护规则属于仓库层面的硬性约定除非是为了新增测试否则不要改动该应用Please do not alter it unless it is to add new tests。因为它承载着现有回归用例所依赖的 DOM 结构与交互任何与测试无关的改动都可能使既有断言失效。新增测试必须保证所有旧测试仍然通过make sure all old tests still pass。这是回归测试的基本契约——新增用例不得破坏既有行为的验证。这两条规则本质上是把packages/parallax/test/与tests/e2e/下的测试用例绑定在了一起改应用 改测试基线因此改动必须由「新增测试」这一正当理由驱动。快照测试DOM 变更会导致失败如何重新生成文档指出快照测试在 DOM 被改动时会失败Snapshot tests will fail if the DOM is altered并给出了重新生成快照的标准流程删除根目录cypress/integration下的__snapshots__文件夹然后运行pnpm test:e2e重新生成。需要说明当前仓库的实际演进从仓库结构看cypress目录与__snapshots__已不存在相关 e2e 已迁移到 vitest 浏览器模式见 tests/e2e/且当前 package.json 中的快照测试实际由vitest/expect的toMatchFileSnapshot/快照断言体系承载例如 packages/core/src/snapshots/Controller.test.ts.snap。但文档所传达的工作流原则依然有效快照测试把「序列化后的 DOM 结构或输出」固化为基线文件任何导致 DOM 变化的代码改动都会让当前输出与基线不一致从而失败当改动是有意为之例如新功能确实需要改变结构时先清除旧快照再重新运行测试以生成新基线反之若 DOM 变化是意外引入的快照失败就是最好的告警信号。就 Parallax 而言仓库当前并没有独立的 DOM 快照文件其行为验证以「显式断言 transform/position 值」为主详见下文这比脆弱的快照对比更精确也是快照策略在现代测试中的常见演进方向。从文档到实现Parallax 的测试设施全景围绕这份文档仓库实际存在三层测试设施可视为文档所述「新增测试」的具体落点1. 单元测试vitest-browser-react jsdom 式容器packages/parallax/src/parallax.test.tsx 使用vitest-browser-react渲染组件覆盖了命令式 API 完整性ref.current暴露scrollTo、update、stop、layersSet 实例、controller、container.current、content.current与horizontal字段scrollTo行为在 400×500 的固定容器中space每页高度等于clientHeight500调用scrollTo(1)后容器scrollTop会收敛到 500factor尺寸计算factor{2}的层最终高度为space * factor 1000px。关键技巧在测试顶部注释中写得很清楚Parallax 的一切尺寸都派生自容器的clientHeight因此测试必须把组件渲染进一个position: relative、尺寸固定的 wrapper 中才能确定性钉住space值。这是为 Parallax 写测试时最重要的前提也是文档所说「测试应用」之外单元层级的补充验证。2. 端到端测试vitest browser modetests/e2e/parallax.spec.tsx 在真实浏览器中验证完整滚动行为是当前仓库替代「cypress 快照」的主力纵向/横向位移断言滚动前后逐帧断言各层的transform如translate3d(0px, 1200px, 0px)与 sticky 层的position从absolute变为stickyscrollTo端到端验证点击按钮后断言容器scrollTop/scrollLeft超过一页容差 1%容忍子像素取整回归用例#2052被组件包裹的 sticky 层因React.Children.map遍历静态元素树、无法读取到被包裹层的stickyprop导致其落入滚动内容中而失效——该用例以it.skip显式记录了这一已知未修复限制并注释了潜在修复方向如改用createPortal将决策下放到层内。tests/e2e/parallax-scrollbar.spec.tsx 则记录了另一个回归#2255Parallax 容器为position: absolute若未钉住top/left在place-items: center这类宿主 CSS 下会溢出视口、在文档上产生「双重滚动条」。测试通过注入一段模拟 Vite 默认 CSS 的样式断言文档本身不出现滚动scrollHeight - clientHeight 0。3. 手工调试应用即文档主角 packages/parallax/test/。运行方式在 packages/parallax/package.json 中定义pnpm test # 在 packages/parallax 下执行vite serve ./test启动后访问/vertical与/horizontal即可手工验证视差、吸附与按钮滚动行为。如何正确地「新增测试」实操路线综合文档规则与仓库现状为 Parallax 新增测试的推荐流程如下判断测试层级只需验证数值/API 行为 → 在 parallax.test.tsx 中新增it用例务必沿用固定尺寸 Wrapper 的做法需要验证真实滚动/布局/回归 → 在 tests/e2e/ 中新增.spec.tsx用page.viewport钉住视口尺寸用waitForTransform这类轮询断言等待动画收敛需要可视化手工验证 → 修改 test/src/App.tsx 增加路由与场景这正是文档允许改动的唯一正当理由。改动后跑全量测试确保旧用例不回归pnpm test # 根目录单元 类型 e2e 全量 pnpm test:e2e # 仅端到端vitest run --project e2e若 DOM 结构确实被有意改变按文档原则清除旧快照并重新生成基线若 DOM 变化是意外则修复代码而非更新基线。结语packages/parallax/test/README.md 虽短却精确界定了 Parallax 测试资产的边界测试应用仅供测试、改动需以新增测试为由、旧测试必须保持通过、DOM 变更需重生成快照。这套约定与仓库中单元测试、e2e 回归用例共同构成了 Parallax 的质量防线。对于想为 Parallax 贡献测试的开发者把握住「固定容器尺寸钉住space」「真实浏览器中轮询断言 transform/position」「回归用例显式记录已知限制」三个要点就能写出稳定、可维护的测试。【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考