如何解决Cypress中“An uncaught error was detected outside of a test”报错

你遇到的报错不完全是import/export语句的问题，更多是Cypress上下文使用规则、异步逻辑处理的问题，具体根因和修复方案如下：

问题根因 #

• fs是Node.js原生服务端模块，不能直接在Cypress浏览器端运行的测试代码（test.spec.js、Utils.js都属于浏览器上下文代码）中调用，你在Utils.js里直接导入调用fs本身就会触发异常。
• Cypress所有操作默认是异步队列执行的，你同步调用comparePNGImages时，前面的downloadPng还没执行完成、图片文件还未落地，此时读取文件也会触发异常。
• looksSame的回调属于异步回调，回调内的expect断言如果执行时已经脱离了Cypress测试用例的生命周期，就会被判定为「测试外的未捕获错误」。
• 导入写法确实存在问题：fs是默认导出不是命名导出，import { fs } from "fs"本身写法错误，正确的Node侧写法为import fs from 'fs'或者const fs = require('fs')。

修复方案 #

1. 把图片对比逻辑迁移到Cypress插件层（Node.js上下文） #

你已经在plugins中引入了相关依赖，直接补充任务注册逻辑即可：

// cypress/plugins/index.js 完整相关代码
const fs = require('fs');
const looksSame = require('looks-same');

module.exports = (on, config) => {
  on('task', {
    comparePNGImages(fileName) {
      const basePath = `./cypress/fixtures/baseImage/${fileName}`;
      const currentPath = `./cypress/fixtures/currentImage/${fileName}`;
      // 前置判断文件是否存在
      if (!fs.existsSync(basePath) || !fs.existsSync(currentPath)) {
        throw new Error(`待对比的图片文件不存在: ${fileName}`);
      }
      return new Promise((resolve, reject) => {
        looksSame(fs.readFileSync(basePath), fs.readFileSync(currentPath), (error, result) => {
          if (error) return reject(error);
          resolve(result.isEqual);
        })
      })
    }
  })
}

2. 改写Utils.js调用逻辑，改为调用Cypress Task #

// Utils.js 代码
export const comparePNGImages = (fileName) => {
  expect(fileName).to.be.a('string')
  cy.log("#### compareImages #### ");
  // 调用Node侧注册的Task，通过then处理异步返回结果
  return cy.task('comparePNGImages', fileName).then(isEqual => {
    expect(isEqual).to.be.true;
  })
}

3. 测试用例调整调用顺序，适配Cypress异步特性 #

// test.spec.js 相关代码
var imageName = "SailingDirection.png";
// 确保downloadPng返回Cypress链式对象，通过then保证下载完成后再执行对比
downloadPng(imageName).then(() => {
  comparePNGImages(imageName)
})

注意事项 #

• 如果downloadPng是自定义命令，需要保证它内部的异步操作都正确包裹在Cypress链式调用中，没有脱离Cypress执行队列的同步逻辑。
• 所有涉及文件读写、操作系统层能力的逻辑，都必须放在Cypress插件层（Node.js上下文）执行，不能直接写在浏览器侧的测试代码中。

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