Percy CLI快照执行顺序异常、登录脚本失效问题排查

常见配置疑问解答 #

• 快照执行顺序控制：Percy CLI 默认对快照列表采用并发调度策略，无内置执行顺序保证。如需按配置顺序执行，可在顶层配置中开启serial: true参数，强制所有快照串行执行；也可将配置导出为异步函数，手动控制执行流顺序。
• 支持的配置格式：除 JS 模块导出格式外，还支持 JSON、YAML 两种静态配置格式，但这两种格式仅支持基础URL、等待规则配置，无法承载自定义execute交互逻辑。
• 预注入登录Cookie：完全支持。可在顶层配置的cookies字段中提前写入登录态对应的Cookie信息，所有快照启动前会自动将Cookie注入浏览器上下文，无需走页面登录流程，可彻底规避执行顺序依赖问题。
• 复杂交互场景的SDK选择：基础percy snapshot命令仅适配静态页面、轻量DOM操作场景。如需实现表单提交、多步跳转、登录态持久化这类复杂交互，需搭配对应自动化测试框架的Percy SDK使用，可直接复用框架提供的页面操作API，稳定性远高于原生execute函数注入。

现有脚本故障修复方案 #

1. 快照执行顺序错乱问题 #

故障原因：默认并发调度模式下，快照执行顺序由页面加载速度决定，和配置书写顺序无关，因此加载更快的Home页会先被捕获。
修复方式：调整配置结构，开启串行执行开关，参考配置如下：

module.exports = {
  options: {
    serial: true // 强制按snapshots数组顺序串行执行
  },
  snapshots: [
    {
      name: 'Login Page - Execute Login',
      url: 'http://localhost:3000/login',
      waitForSelector: '.login-form > button',
      waitForTimeout: 3000,
      execute() {
        // 修正后的表单填充逻辑
        const emailInput = document.querySelector('#email');
        emailInput.value = 'test@test.com';
        emailInput.dispatchEvent(new Event('input', { bubbles: true }));
        emailInput.dispatchEvent(new Event('change', { bubbles: true }));

        const pwdInput = document.querySelector('#confirmPassword');
        pwdInput.value = 'password';
        pwdInput.dispatchEvent(new Event('input', { bubbles: true }));
        pwdInput.dispatchEvent(new Event('change', { bubbles: true }));

        document.querySelector('.login-form > button').click();
        // 额外增加等待时间，确保登录请求完成、Cookie写入、页面跳转触发后再结束当前快照
        return new Promise(resolve => setTimeout(resolve, 3000));
      }
    },
    {
      name: 'Home',
      url: 'http://localhost:3000/home',
      waitForTimeout: 2000
    }
  ]
}

2. 表单填充逻辑不生效问题 #

故障原因：直接通过DOM赋值修改input的value属性，不会触发React/Vue等前端框架的状态监听逻辑，无头浏览器环境中框架无法感知到输入值变化，提交时表单仍为空值。
修复方式：给输入框手动派发input、change原生事件，模拟真实用户输入的事件流，确保框架能捕获到值变更；如果交互逻辑更复杂，建议直接换用Playwright/Puppeteer对应的Percy SDK，用框架自带的fill、click方法操作页面，自动处理事件触发、等待逻辑，不会出现这类兼容性问题。

更稳定的登录实现方案：提前通过接口请求拿到登录态Cookie，直接注入到配置中，跳过页面登录操作，既可以提升快照执行速度，也能避免前端交互变更导致的登录流程失效。

内容的提问来源于stack exchange，提问作者cascade