Angular 深入浅出三十天：表单与测试 Day22 - 把 Cypress 变成 TypeScript 版

平常都用惯 TypeScript 版的 Cypress，但这两天都用 JavaScript 在写测试，令我有点不太习惯。

虽然 JS 版或 TS 版的差别并没有多大，但少了一些开发时期的型别检查与 Intellisense 还是令人感到别扭。

因此，我们今天就来分享如何把 JS 版的 Cypress 变成 TS 版吧！

Angular 专案

首先，如果你的专案是 Angular ，预设不会配有任何 E2E 自动化测试工具，如果我们想要在 Angular 的专案使用 Cypress ，可以直接在终端机输入以下指令：

$ ng add @cypress/schematic

等待它执行完成後，你会发现 Angular Schematics 除了帮你装好 Cypress 之後，也在 package.json 里的 scripts 区段增加了以下三个指令：

{
  "scripts": {
    "e2e": "ng e2e",
    "cypress:open": "cypress open",
    "cypress:run": "cypress run"
  }
}

并且在 angular.json 里的 architect 区段添加了以下设定：

{
  "cypress-run": {
    "builder": "@cypress/schematic:cypress",
    "options": {
      "devServerTarget": "ng-with-cypress:serve"
    },
    "configurations": {
      "production": {
        "devServerTarget": "ng-with-cypress:serve:production"
      }
    }
  },
  "cypress-open": {
    "builder": "@cypress/schematic:cypress",
    "options": {
      "watch": true,
      "headless": false
    }
  },
  "e2e": {
    "builder": "@cypress/schematic:cypress",
    "options": {
      "devServerTarget": "ng-with-cypress:serve",
      "watch": true,
      "headless": false
    },
    "configurations": {
      "production": {
        "devServerTarget": "ng-with-cypress:serve:production"
      }
    }
  }
}

e2e 的部份如果原本是使用 Protractor ，也会被调整过来。

这段设定的用意是让 Angular CLI 知道，当我们要执行 cypress run 、 cypress open 或是 ng e2e 的指令时，会连带启动 Angular 的服务，方便开发者使用时，不需额外自己启动。

葛来芬多 Cypress 加 10 分！

此外，不可少的 cypress.json 与 /cypress 资料夹当然也已经新增好了，而且 cypress.json 里还已经帮我们配置了以下设定：

{
  "integrationFolder": "cypress/integration",
  "supportFile": "cypress/support/index.ts",
  "videosFolder": "cypress/videos",
  "screenshotsFolder": "cypress/screenshots",
  "pluginsFile": "cypress/plugins/index.ts",
  "fixturesFolder": "cypress/fixtures",
  "baseUrl": "http://localhost:4200"
}

原本 /cypress 资料夹里的 .js 档也都变成了 .ts 档，至此，我们就成功地把 Cypress 加入的 Angular 专案之中了，是不是超方便、超简单的？！

Angular + Cypress 真的会把开发者宠坏

想知道什麽是 Angular Schematics 吗？可以阅读我的系列文：高效 Coding 术：Angular Schematics 实战三十天。

其他更多资讯，可以参考 Cypress 官方文件：https://docs.cypress.io/guides/migrating-to-cypress/protractor#Recommended-Installation

额外告诉大家一个小故事：其实这个 Schematics 原本不是官方维护的，这个 Schematics 的原身一开始是这个 @briebug/cypress-schematic ，不过後来被官方采用，才改由 Cypress 团队维护。

衷心感谢所有曾经或正在为 Open Source 贡献心力的每一个人。

其他类型专案

Angular 专案有 Angular Schematics ，但其他类型的专案或者是单单只有 Cypress 的专案怎办？

别担心，其实要做的事情也不会太繁琐或困难。

首先，我们可以先在专案里输入以下指令以安装 TypeScript ：

$ npm install typescript --save-dev

or

$ yarn add typescript --dev

如果你的专案里已经有安装 TypeScript 的话请略过此步骤

然後在 /cypress 资料夹内新增一个 tsconfig.json 档，并添加以下内容：

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

然後就可以把我们的 .js 档都改成 .ts 档，并把所有的 /// <reference types="cypress" /> 都拿掉罗！

不过如果你本来的专案就是 TypeScript 的，这时候你可能会发现你原本非 E2E 测试的 .spec.ts 档案多了一堆红色毛毛虫：

然後你将滑鼠游标移到红色毛毛虫上， VSCode 会跟你说：

但是如果我们实际跑测试的话，又都会通过，那到底为什麽会有红色毛毛虫呢？

其实这是因为， VSCode 以为原本非 E2E 测试的 .spec.ts 是 Cypress 的档案，所以它把原本是 Jasmine 的 expect() ：

误认为是 Chai 的 expect() ：

那该怎麽办才好呢？

其实会造成这个状况是因为 VSCode 它预设会吃 tsconfig.json 的设定，而如果原本根目录就有 tsconfig.json ，然後又在 /cypress 里加了 tsconfig.json 的话，就会出现这种状况。

这时我们只需要在根目录的 tsconfig.json 加上这个设定就可以恢复正常了：

{
  "include": [
    "src",
    "node_modules/cypress"
  ],
  "exclude": [
    "node_modules/cypress"
  ]
}

如果这部份有遇到问题的话，可以参考我的 Source Code 的设定。

不过别高兴地太早，还有一件事情需要我们留意与调整。

自订 Command

之前在 JS 版本使用自订 Command 时，自订的 Command 没有 Intellisense 很不方便，而且参数也都没有办法定义型别，也增加了後续维护的困难度。

而现在我们升级成 TS 版本後，想要享受 TS 所带来的好处之前，我们需要在我们的 command.ts 档的开头增加以下程序码：

declare namespace Cypress {
  interface Chainable {
    // 这里面摆放的是自订 Command 的宣告
    // 例如：
    fillWith(account: string, password: string): Chainable<string>
  }
}

原本的自订 Command 的区块也可以一并调整成这样：

Cypress.Commands.add('fillWith', (account: string, password: string) => {
  cy.get('#account').type(account);
  cy.get('#password').type(password);
})

如此一来，我们在写测试案例的时候即可享有 Intellisense 与型别检查的好处罗！

想知道更多可以参考官方的 TypeScript Support 文件

本日小结

今天的重点主要是升级完成後，千万记得要在 command.ts 加上 namespace 的宣告，这点可能会是很多人会不小心忘记的地方。

此外，也记得将 /// <reference types="cypress" /> 从程序码中移除，这个语法主要是针对 JS 的，升级 TS 之後有它反而会错。

我今天的实作程序码会放在 Github - Branch: day22 上供大家参考，不过虽然该专案是 Angular 专案，但我是使用「其他专案」的方式，所以在测试时会需要自己启动 Angular 的服务。

同时也建议大家在看我的实作之前，先按照需求规格自己做一遍，之後再跟我的对照，看看自己的实作跟我的实作不同的地方在哪里、有什麽好处与坏处，如此反覆咀嚼消化後，我相信你一定可以进步地非常快！

如果你有任何的问题或是回馈，还请麻烦留言给我让我知道！