theme: nico

最近准备给公司项目做重构，原本是打算使用Jest来作为测试工具的，刚好无意之中接触到了Cypress这款测试工具，虽然用上它非常的不容易（简直是一波三折），但是用上了之后觉得真香啊。我们本篇文章就是讲Cypress如何安装和使用，以及解决安装和使用过程的坑。

提前预先告知一下遇到的问题：

cypress 包下载不下来

Cypress 应用程序下载太漫长，经常性失败（挂梯子也没用）

TypeScript 类型错误

为什么选择 Cypress？

Cypress是新一代的前端测试工具。可以测试在浏览器中运行的一切。并且它的所有动作都是在浏览器环境运行的，这意味着你通过Cypress跑测试用例跟在生产环境使用一模一样。这会比Jest这种在虚拟浏览器中进行测试更加可靠。

安装 Cypress

安装Cypress可是非常的不容易，使用Cypress最大的障碍就是安装Cypress——这太折磨了吧。

初始化项目

我们这里使用vite快速创建一个项目（额外贴上Webpack构建的 👉 demo）

pnpm create vite

根据指引选择你想要的框架与配置（不同框架之间配置基本一致），我的如下：

✔ Project name: cypress-vite
✔ Select a framework: › React
✔ Select a variant: › TypeScript

进入文件目录并安装基本的依赖

cd cypress-vite && pnpm install

不知道为什么，最近npm的依赖基本安装不下来（我看群里有好几个人都说最近安什么包都安不下来）。没办法，换淘宝源吧

npm config set registry https://registry.npm.taobao.org

重新pnpm install算是安装上了

安装 cypress 依赖

pnpm install cypress --save-dev

尝试启用cypress

npx cypress open

第二个折磨来了，报错内容如下

No version of Cypress is installed in: /Users/UserName/Library/Caches/Cypress/11.1.0/Cypress.app

Please reinstall Cypress by running: cypress install

-----------

Cypress executable not found at: /Users/UserName/LibraryCaches/Cypress/11.1.0/Cypress.app/Contents/MacOS/Cypress

-----------

Platform: darwin-x64 (20.6.0)
Cypress Version: 11.1.0

这是因为安装的cypress包只是跑测试用例的代码, 而控制浏览器完成自动化测试的是通过Cypress应用程序进行的。

既然如此，我们就按照提示安装Cypress应用程序

npx cypress install

结果发现根本装不下来，每次都是到1%的进度就断掉或者没有进展（有些人等了几个小时仍然没有安装下来，是谁我不说🤪

百度、谷歌、stackoverflow、github 上查了半天，最终是无意之间在 Github 上的 issue 上找到了解决办法。需要在安装命令后面加上--force

npx cypress install --force

几秒钟就安装了下来（这个凭什么就能安装下来呢？！？！？！

启用 Cypress

重新执行

npx cypress open

就会打开Cypress应用程序，界面如下：

E2E Testing

我们这里先选择E2E Testing。Component Testing 我后面会讲怎么配置（毕竟还有TypeScript的坑要填呢～）

关于这两者之间有什么区别，可以点击Welcome to Cypress!下方的Review the differences between each testing type →前往查看，这里就不多做解释了。

告知在我们的项目添加了以下文件

选择你将要运行的环境以后就会打开一个浏览器窗口

这里检测到我们没有可以执行的例子，所以提供了两个选择：

生成一些例子，来帮助我们了解如何通过Cypress写测试
生成一个空的测试文件，以便于我们开始测试应用

选择哪一个都可以，建议选择生成一些例子，这样就可以了解测试用例如何去写了。

生成好测试用例以后点击一个文件就可以开始测试了

Component Testing

退回到Cypress应用程序中，选择Component Testing

Cypress将会自动检测并选择上当前使用的框架及构建工具

基于上一步的选择来检查必要的依赖是否已安装

最后安装下去，Cypress会帮助我们在项目中生成cypress/component目录和cypress/support/component-index.html、cypress/support/component.ts文件

cypress/support/component-index.html 是用于测试的html模版，当然你也可以在cypress.config.ts中指定测试模版，将component.indexHtmlFile设置为指定的模版路径即可

浏览器页面上提示我们并没有可执行的测试用例，页面上展示着生成一个空的测试页面，我们选择它，它生成在测试文件在根目录的cypress/component文件下，由于我们做的是组件测试，比较好的做法是测试文件与被测试的组件在一起（官方给的例子也是如此QAQ）。
在src目录下创建文件如下

// /src/components/Button.tsx
export detault function Button() {
    return (
        <button data-cy="btn">0</button>
    )
}

// /src/components/Button.cy.tsx/
import Button from "./Button"

describe('Button', () => {
    it('mount Button', () => {
        cy.mount(<Button />)
        cy.get('[data-cy=btn]').should('have.text', '0')
    })
})

点击Cypress打开的浏览器中的Button.cy.tsx文件，测试通过了

解决VSCode TypeScript类型错误

尽管测试通过了，但是VSCode中的Button.cy.tsx文件报类型错误，标红也就算了，还乱给智能提示，实在难受

这是TypeScript的类型错误，我们需要在tsconfig.json中添加types: ["cypress"]配置

{
  "compilerOptions": {
    "types": ["cypress"],
    // ......
}

加上以后虽然describe等关键字没有报错，但是cy.mount仍是报错的，这是因为我们的mount方法是在cypress/support/component.ts文件中添加上的，虽然定义了全局类型，但并没有在src目录下生效，为了让两边都生效，我们将这个全局定义单独放到根目录下作为一个类型文件。

// cypress.d.ts
import { mount } from 'cypress/react18'

declare global {
  namespace Cypress {
    interface Chainable<Subject> {
      mount: typeof mount;
    }
  }
}

同时在根目录的tsconfig.json中使用

{
  "compilerOptions": {
  // ......
  "include": [
    "src",
    "cypress.d.ts" // 添加 cypress.d.ts 让类型生效
  ],
  // ......
}

接着就可以将cypress/support/component中的类型删除掉，并在cypress目录下创建一个tsconfig.json文件

{
  "compilerOptions": {
    "target": "es5",
    "lib": ["es5", "dom"],
    "types": ["cypress"]
  },
  "include": ["**/*.ts", "../cypress.d.ts"]
}

这样，cypress.d.ts在src及cypress目录下定义的类型都可以生效了。

当然，也有可能会出现定义了以后cy.mount或者Cypress.Commands.add('mount', mount)仍在报错。可以在VSCode中输入组合键command + shift + p打开快捷指令栏，输入TypeScript: Restart TS server回车来重启TypeScript服务，如若仍不生效，建议重启试试～