企业官网建设流程全解析

react-spring Parallax 测试应用指南：维护规则、快照测试与端到端验证

【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring

@react-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 入口 HTML；
• vite.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 驱动，见下文），它的存在意义在于：为人工调试、为未来可能接入的浏览器型快照/回归测试提供一个开箱即用的载体。

维护红线：这是测试专用资产，改动需谨慎

文档给出了两条明确的维护规则，属于仓库层面的硬性约定：

1. 除非是为了新增测试，否则不要改动该应用（"Please do not alter it unless it is to add new tests"）。因为它承载着现有回归用例所依赖的 DOM 结构与交互，任何与测试无关的改动都可能使既有断言失效。
2. 新增测试必须保证所有旧测试仍然通过（"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、layers（Set 实例）、controller、container.current、content.current与horizontal字段；
• scrollTo行为：在 400×500 的固定容器中，space（每页高度）等于clientHeight（500），调用scrollTo(1)后容器scrollTop会收敛到 500；
• factor尺寸计算：factor={2}的层最终高度为space * factor = 1000px。

关键技巧在测试顶部注释中写得很清楚：Parallax 的一切尺寸都派生自容器的clientHeight，因此测试必须把组件渲染进一个position: relative、尺寸固定的 wrapper 中，才能确定性钉住space值。这是为 Parallax 写测试时最重要的前提，也是文档所说「测试应用」之外，单元层级的补充验证。

2. 端到端测试（vitest browser mode）

tests/e2e/parallax.spec.tsx 在真实浏览器中验证完整滚动行为，是当前仓库替代「cypress 快照」的主力：

• 纵向/横向位移断言：滚动前后，逐帧断言各层的transform（如translate3d(0px, 1200px, 0px)）与 sticky 层的position（从absolute变为sticky）；
• scrollTo端到端验证：点击按钮后断言容器scrollTop/scrollLeft超过一页（容差 1%，容忍子像素取整）；
• 回归用例（#2052）：被组件包裹的 sticky 层因React.Children.map遍历静态元素树、无法读取到被包裹层的stickyprop，导致其落入滚动内容中而失效——该用例以it.skip显式记录了这一已知未修复限制，并注释了潜在修复方向（如改用createPortal将决策下放到层内）。

tests/e2e/parallax-scrollbar.spec.tsx 则记录了另一个回归（#2255）：Parallax 容器为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 新增测试的推荐流程如下：

1. 判断测试层级：
   • 只需验证数值/API 行为 → 在 parallax.test.tsx 中新增it用例，务必沿用固定尺寸 Wrapper 的做法；
   • 需要验证真实滚动/布局/回归 → 在 tests/e2e/ 中新增.spec.tsx，用page.viewport钉住视口尺寸，用waitForTransform这类轮询断言等待动画收敛；
   • 需要可视化手工验证 → 修改 test/src/App.tsx 增加路由与场景，这正是文档允许改动的唯一正当理由。
2. 改动后跑全量测试，确保旧用例不回归：

pnpm test # 根目录：单元 + 类型 + e2e 全量 pnpm test:e2e # 仅端到端（vitest run --project e2e）

3. 若 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