7 |
8 | * [《Jest 实践指南》访问链接](https://github.yanhaixiang.com/jest-tutorial/)
9 | * [《Jest 实践指南》配套项目](https://github.com/haixiangyan/jest-tutorial-example)
10 |
11 | ## 前言
12 |
13 | [Jest](https://jestjs.io/) 看似很简单，就像很多博客写的那样：
14 |
15 | ```js
16 | expect(sum(1, 1)).toEqual(2)
17 | ```
18 |
19 | 然而在真实业务中，写出一个好测试的难度并没有大家想的那么低。我总结了一下写测试的几个难点：
20 |
21 | **不会配置。** Jest 的上手文档非常简单，甚至不需要配置。但真实情况是只要一个配置没配好，所有测试都跑不起来。测试不像开发，代码有问题可以慢慢调。
22 | 测试是一个 0 - 1 游戏，不是成功就是失败，挫败感非常强。
23 |
24 | **不知道要怎么 Mock。** 这个绝对是经典中的经典。虽然官方文档有教程，但是真实的业务往往不是那么理想，远比文档要复杂的多。
25 |
26 | **不会构造测试用例。** 刚接触测试时，很容易把做业务那套 “实现 XXX 功能” 的想法代入测试。但测试的重点不在于实现功能，而是构造用例。
27 |
28 | **没有测试策略。** 上面是 “技” 的难点，测试还有 “术” 的难点。闷着头一通肝测试代码并不高效，使用合适的测试策略远比写 10 个测试用例重要。
29 |
30 | 上面这些问题很容易让人写出难以维护和复杂的测试。只要业务一改，不仅要维护业务代码还要维护测试代码。
31 | 这时，你不禁感叹：“测试真浪费时间”，最终放弃写测试，直接开摆。
32 |
33 | **好的测试会让你获得很高的代码信心，而不好的测试则会严重拖垮项目开发。所以，大家所厌恶的不应该是测试本身，而是那些维护性差的测试。**
34 |
35 | ## 目的
36 |
37 | 我在网上翻找关于前端测试的资料时，我发现真的太少了，几乎可以分为几类：
38 |
39 | 1. **入门类。** 安装 Jest，外加 `expect(1 + 1).toEqual(2)` 小例子
40 | 2. **API 说明书类。** 类似于把 Jest 官网抄了一遍
41 | 3. **理论类。** 是什么、为什么、测试分类等，但最重要的 “怎么做” 没有说
42 |
43 | 并不是说这些文章不好，只是，这些文章大多数停留在最初级，很不利于其他同学来学习一门新技术。
44 |
45 | 同时，我还拜访了一下 [Jest 的官网](https://jestjs.io/zh-Hans/) 。没想到，都 2022 年了，中文翻译依然这么难看：
46 |
47 | 
48 |
49 | 先不说翻译的正确性如何，单看这中文的内容就让人没有想看下去的欲望，真希望 Jest 能找稍微专业一点的人来做翻译。
50 | 由于官网的中文翻译做的实在太烂，遇到问题几乎在中文社区是找不到的。
51 |
52 | 终于，我看到了 React Testing Library 作者 Kent C. Dodds 的 [博客](https://kentcdodds.com/) 。
53 |
54 | 
55 |
56 | 他写了很多关于测试思路的文章，每一篇都非常精彩。**受他的启发，我觉得有必要把这些思想和技巧分享出来，最终形成了这本小书。**
57 |
58 |
59 | ## 内容
60 |
61 | > 此次教程主要分享测试的思路为主，虽然以 React 为主要技术栈，但使用其它技术栈的读者依然可以流畅阅读。
62 |
63 | **本教程是我结合了自身实践、Kent C. Dodds 文章、StackOverflow、Github Issue 以及别的博客最终总结出来的一套实践指南。**
64 |
65 | 小书包含 3 部分：
66 |
67 | **基础实践。** 从 0 到 1 写项目和测试，每一章会通过一个业务例子来分享测试难点、解法和思路。
68 |
69 | **测试思路。** 分享一些 Kent 的文章（中文翻译）以及测试总结。
70 |
71 | **[配套项目](https://github.com/haixiangyan/jest-tutorial-example)。** 如果你在某一步卡壳了，也可以参考这个项目。
72 |
73 | 最近给这个 Repo 开了一个 [讨论区](https://github.com/haixiangyan/jest-tutorial/discussions) ，如果你有任何问题（Jest、测试、小书）
74 | ，都可以在这里一起讨论 😄。
75 |
76 | ## 求关注
77 |
78 | **这教程 + 配套项目写了 3 周，说实话挺累的。原创不易，打赏就不必了，观众老爷省着吧。只求大家多关注一下我的新公众号【写代码的海怪】。**
79 |
80 | 
81 |
--------------------------------------------------------------------------------
/cover.jpeg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/cover.jpeg
--------------------------------------------------------------------------------
/deploy.sh:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env sh
2 |
3 | # 确保脚本抛出遇到的错误
4 | set -e
5 |
6 | # 生成静态文件
7 | npm run docs:build
8 |
9 | # 进入生成的文件夹
10 | cd docs/.vuepress/dist
11 |
12 | # 如果是发布到自定义域名
13 | # echo 'www.example.com' > CNAME
14 |
15 | git init
16 | git add -A
17 | git commit -m 'deploy'
18 |
19 | # 如果发布到 https://
7 |
8 | * [《Jest 实践指南》访问链接](https://github.yanhaixiang.com/jest-tutorial/)
9 | * [《Jest 实践指南》配套项目](https://github.com/haixiangyan/jest-tutorial-example)
10 |
11 | ## 测试难点
12 |
13 | [Jest](https://jestjs.io/) 看似很简单，就像很多博客写的那样：
14 |
15 | ```js
16 | expect(sum(1, 1)).toEqual(2)
17 | ```
18 |
19 | 然而在真实业务中，写出一个好测试的难度并没有大家想的那么低。我总结了一下写测试的几个难点：
20 |
21 | **不会配置。** Jest 的上手文档非常简单，甚至不需要配置。但真实情况是只要一个配置没配好，所有测试都跑不起来。测试不像开发，代码有问题可以慢慢调。
22 | 测试是一个 0 - 1 游戏，不是成功就是失败，挫败感非常强。
23 |
24 | **不知道要怎么 Mock。** 这个绝对是经典中的经典。虽然官方文档有教程，但是真实的业务往往不是那么理想，远比文档要复杂的多。
25 |
26 | **不会构造测试用例。** 刚接触测试时，很容易把做业务那套 “实现 XXX 功能” 的想法代入测试。但测试的重点不在于实现功能，而是构造用例。
27 |
28 | **没有测试策略。** 上面是 “技” 的难点，测试还有 “术” 的难点。闷着头一通肝测试代码并不高效，使用合适的测试策略远比写 10 个测试用例重要。
29 |
30 | 上面这些问题很容易让人写出难以维护和复杂的测试。只要业务一改，不仅要维护业务代码还要维护测试代码。
31 | 这时，你不禁感叹：“测试真浪费时间”，最终放弃写测试，直接开摆。
32 |
33 | **好的测试会让你获得很高的代码信心，而不好的测试则会严重拖垮项目开发。所以，大家所厌恶的不应该是测试本身，而是那些维护性差的测试。**
34 |
35 | ## 目的
36 |
37 | 我在网上翻找关于前端测试的资料时，我发现真的太少了，几乎可以分为几类：
38 |
39 | 1. **入门类。** 安装 Jest，外加 `expect(1 + 1).toEqual(2)` 小例子
40 | 2. **API 说明书类。** 类似于把 Jest 官网抄了一遍
41 | 3. **理论类。** 是什么、为什么、测试分类等，但最重要的 “怎么做” 没有说
42 |
43 | 并不是说这些文章不好，只是，这些文章大多数停留在最初级，很不利于其它同学来学习一门新技术。
44 |
45 | 同时，我还拜访了一下 [Jest 的官网](https://jestjs.io/zh-Hans/) 。没想到，都 2022 年了，中文翻译依然这么难看：
46 |
47 | 
48 |
49 | 先不说翻译的正确性如何，单看这中文的内容就让人没有想看下去的欲望，真希望 Jest 能找稍微专业一点的人来做翻译。
50 | 由于官网的中文翻译做的实在太烂，遇到问题几乎在中文社区是找不到的。
51 |
52 | 终于，我看到了 React Testing Library 作者 Kent C. Dodds 的 [博客](https://kentcdodds.com/) 。
53 |
54 | 
55 |
56 | 他写了很多关于测试思路的文章，每一篇都非常精彩。**受他的启发，我觉得有必要把这些思想和技巧分享出来，最终形成了这本小书。**
57 |
58 |
59 | ## 内容
60 |
61 | ::: tip
62 | 此次教程主要分享测试的思路为主，虽然以 React 为主要技术栈，但使用其它技术栈的读者依然可以流畅阅读。
63 | :::
64 |
65 | **本教程是我结合了自身实践、Kent C. Dodds 文章、StackOverflow、Github Issue 以及别的博客最终总结出来的一套实践指南。**
66 |
67 | 小书包含 3 部分：
68 |
69 | **基础实践。** 从 0 到 1 写项目和测试，每一章会通过一个业务例子来分享测试难点、解法和思路。
70 |
71 | **测试思路。** 分享一些 Kent 的文章（中文翻译）以及测试总结。
72 |
73 | **[配套项目](https://github.com/haixiangyan/jest-tutorial-example)。** 如果你在某一步卡壳了，也可以参考这个项目。
74 |
75 | 最近给这个 Repo 开了一个 [讨论区](https://github.com/haixiangyan/jest-tutorial/discussions) ，如果你有任何问题（Jest、测试、小书）
76 | ，都可以在这里一起讨论 😄。
77 |
78 | ## 求关注
79 |
80 | **这教程 + 配套项目写了 3 周，说实话挺累的。原创不易，打赏就不必了，观众老爷省着吧。只求大家多关注一下我的新公众号【写代码的海怪】。**
81 |
82 | 
83 |
--------------------------------------------------------------------------------
/docs/bad-translation.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/docs/bad-translation.png
--------------------------------------------------------------------------------
/docs/basic/automation/README.md:
--------------------------------------------------------------------------------
1 | # 自动化测试
2 |
3 | 每次手动 `npm run test` 跑测试是很痛苦的。通常我们会把执行测试这一步放到流水线中，这也是前端工程化非常重要的一步，称为 **“自动化测试”**。
4 |
5 | 正好我们可以使用 Github 推出的流水线工具—— [Github Actions](https://github.com/features/actions) 。这一章，就带大家一起配置一下吧。
6 |
7 | ## Github Actions
8 |
9 | 在根目录添加 `.github/workflows/node.js.yml`：
10 |
11 | ```yml
12 | # .github/workflows/node.js.yml
13 | name: Node.js CI
14 |
15 | on:
16 | push:
17 | branches: [ main ]
18 | pull_request:
19 | branches: [ main ]
20 |
21 | jobs:
22 | build:
23 |
24 | runs-on: ubuntu-latest
25 |
26 | strategy:
27 | matrix:
28 | node-version: [16.x]
29 |
30 | steps:
31 | - uses: actions/checkout@v3
32 | - name: Use Node.js ${{ matrix.node-version }}
33 | uses: actions/setup-node@v3
34 | with:
35 | node-version: ${{ matrix.node-version }}
36 | - run: npm install
37 | - run: npm test
38 | ```
39 |
40 | 这里 `on` 会监听 `main` 分支的 `git push` 和 PR 提交两个操作。 **开发者在 `main` 分支推代码或者 PR 合并都会执行下面配置的 `jobs`。**
41 | 下面的 `jobs` 也很好理解，就是执行一些 `bash` 脚本。
42 |
43 | 现在把代码推到 `main`，会发现 Github Actions 开始执行，并成功。
44 |
45 | ## Coveralls
46 |
47 | 还记得刚开始时我们配置的 Jest 测试覆盖率么？如果流水线每次跑完都生成一份可视化的测试报告就完美了，不仅能做预警，还能实时了解整体测试覆盖情况。
48 |
49 | 比较著名的测试平台有 [Coveralls](https://coveralls.io/)，它能够读取 Jest 生成的 `lcov.info` 覆盖率文件，并以可视化的方法展示出来：
50 |
51 | 
52 |
53 | 首先在 [Coveralls 官网](https://coveralls.io/sign-in) 用 Github 账号登入：
54 |
55 | 
56 |
57 | 接下来，添加你的 Github 项目：
58 |
59 | 
60 |
61 | 添加完项目并没有结束，如果你使用 [Travis CI](https://travis-ci.org/) ，可能要手动写命令把 `lcov.info` 传给 [Coveralls](https://coveralls.io) 。而 Github Actions 里有 Coveralls 组件，使用它就能自动完成：
62 |
63 | ```yaml
64 | name: Node.js CI
65 |
66 | on:
67 | push:
68 | branches: [ main ]
69 | pull_request:
70 | branches: [ main ]
71 |
72 | jobs:
73 | build:
74 |
75 | runs-on: ubuntu-latest
76 |
77 | strategy:
78 | matrix:
79 | node-version: [16.x]
80 | # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
81 |
82 | steps:
83 | - uses: actions/checkout@v3
84 | - name: Use Node.js ${{ matrix.node-version }}
85 | uses: actions/setup-node@v3
86 | with:
87 | node-version: ${{ matrix.node-version }}
88 | - run: npm install
89 | - run: npm test
90 |
91 | - name: Coveralls
92 | uses: coverallsapp/github-action@master
93 | with:
94 | github-token: ${{ secrets.GITHUB_TOKEN }}
95 | ```
96 |
97 | 再次把代码推到 `main` 分支，等上一会，就可以在 [Coveralls 项目列表页](https://coveralls.io/repos) 看到你的测试覆盖率情况了。
98 |
99 | 一旦把测试报告推到 Coveralls，你就可以在项目详情页里找到这个 Badge：
100 |
101 | 
102 |
103 | 点击 `embed` 可以看到有多种嵌入方法，一般会把这个 Badge 放到 `README.md`，让项目看起来更有逼格：
104 |
105 | [](https://coveralls.io/github/haixiangyan/jest-tutorial-example?branch=main)
106 |
107 | ## 总结
108 |
109 | 这一章我们学会了如何配置 Github Actions，在每次推代码和合并 PR 时自动跑测试，并通过 `coverallsapp/github-action@master` 组件把测试覆盖率报告发送给 [Coveralls](https://coveralls.io)，将测试情况可视化。
110 |
--------------------------------------------------------------------------------
/docs/basic/automation/add-repo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/docs/basic/automation/add-repo.png
--------------------------------------------------------------------------------
/docs/basic/automation/badge.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/docs/basic/automation/badge.png
--------------------------------------------------------------------------------
/docs/basic/automation/coveralls.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/docs/basic/automation/coveralls.png
--------------------------------------------------------------------------------
/docs/basic/automation/signin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/docs/basic/automation/signin.png
--------------------------------------------------------------------------------
/docs/basic/component-test/README.md:
--------------------------------------------------------------------------------
1 | # 组件测试
2 |
3 | 终于到正片了，这一章我们来讲讲组件测试中的一些技巧和策略吧。
4 |
5 | ## 需求
6 |
7 | 首先，我们还是以一个需求来开始这一章：**实现一个 `AuthButton`，通过 `getLoginState` 获取当前用户的身份并在按钮中展示用户身份。**
8 |
9 | 简单分析一下这个需求：
10 |
11 | 1. 实现 `AuthButton` 业务组件
12 | 2. 在 API 函数 `getLoginState` 发请求获取用户身份
13 | 3. 把 Http 请求的返回 `loginStateResponse` 展示到按钮上
14 |
15 | 我们先来安装一下 `axios`：
16 |
17 | ```shell
18 | npm i axios@0.26.1
19 | ```
20 |
21 | 然后添加 `src/apis/user.ts`，里面写发送获取用户角色身份的 Http 请求：
22 |
23 | ```ts
24 | import axios from "axios";
25 |
26 | // 用户角色身份
27 | export type UserRoleType = "user" | "admin";
28 |
29 | // 返回
30 | export interface GetUserRoleRes {
31 | userType: UserRoleType;
32 | }
33 |
34 | // 获取用户角色身份
35 | export const getUserRole = async () => {
36 | return axios.get
100 |
101 | 登录
102 |
103 |
104 | )
105 | }
106 | ```
107 |
108 | ## Less 的引入问题
109 |
110 | 好，现在我们一个一个问题来看。写完上面的代码后，TS 首先受不了报错：
111 |
112 | 
113 |
114 | 我们需要在全局类型声明文件 `src/types/global.d.ts` 里添加 `.less` 文件的类型定义：
115 |
116 | ```ts
117 | // src/types/global.d.ts
118 | declare module "*.less" {
119 | const content: any;
120 | export default content;
121 | }
122 | ```
123 |
124 | 相信大家都能看懂 `AuthButton` 的代码，就不展示页面的情况了，下面主要来讨论测试用例的问题。
125 | 创建一个用例 `tests/components/AuthButton/simple.test.tsx`：
126 |
127 | ```tsx
128 | // tests/components/AuthButton/simple.test.tsx
129 | import { render, screen } from "@testing-library/react";
130 | import AuthButton from "components/AuthButton";
131 | import React from "react";
132 |
133 | describe('AuthButton', () => {
134 | it('可以正常展示', () => {
135 | render(
164 |
167 | )
168 | }
169 |
170 | export default App;
171 | ```
172 |
173 | 到这里我们的业务就完事了，接下来再配置一下 `tsconfig.json`，所需要用的路径都做一下映射：
174 |
175 | ```json
176 | {
177 | "compilerOptions": {
178 | "jsx": "react",
179 | "esModuleInterop": true,
180 | "baseUrl": "./",
181 | "paths": {
182 | "utils/*": ["src/utils/*"],
183 | "components/*": ["src/components/*"],
184 | "apis/*": ["src/apis/*"],
185 | "hooks/*": ["src/hooks/*"],
186 | "store/*": ["src/store/*"]
187 | }
188 | }
189 | }
190 | ```
191 |
192 | ## 启动应用
193 |
194 | 现在执行 `npm run start`，进入 `localhost:3000` 就能看到我们的页面了：
195 |
196 | 
197 |
--------------------------------------------------------------------------------
/docs/basic/config-react/react-preview.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/docs/basic/config-react/react-preview.png
--------------------------------------------------------------------------------
/docs/basic/getting-started/README.md:
--------------------------------------------------------------------------------
1 | # 起步
2 |
3 | 首先，我们来创建一个新项目。
4 |
5 | ::: warning
6 | 阅读中遇到卡壳时，可以参考 [配套项目](https://github.com/haixiangyan/jest-tutorial-example) 。
7 | :::
8 |
9 | ## 创建项目
10 |
11 | 使用 `npm` 初始化，并安装 `jest`。
12 |
13 | ```shell
14 | # 创建项目
15 | mkdir jest-starter
16 | cd jest-starter
17 |
18 | # 初始化
19 | npm init -y
20 |
21 | # 安装依赖
22 | npm i -D jest@27.5.1
23 | ```
24 |
25 | ::: warning
26 | 目前 Jest 已经来到 28 版本了，但是我在实践中发现 `Jest@28` 和 `react@18` 以及 `@testing-library/react` 一起使用时会有冲突，建议大家跟着我使用 **稳定** 的版本。
27 | :::
28 |
29 | 安装 Jest 后，用 `jest-cli` 初始化 `jest` 配置文件：
30 |
31 | ```shell
32 | npx jest --init
33 | ```
34 |
35 | 初始化配置文件时，Jest 会问你一堆问题，可以先按我下面的图来选择（只打开覆盖率和自动清除 Mock），别的以后再说：
36 |
37 | 
38 |
39 | 执行完之后，就会看到有一个 `jest.config.js` 的配置文件：
40 |
41 | ```shell
42 | // jest.config.js
43 | module.exports = {
44 | // 自动清除 Mock
45 | clearMocks: true,
46 |
47 | // 开启覆盖率
48 | collectCoverage: true,
49 |
50 | // 指定生成覆盖率报告文件存放位置
51 | coverageDirectory: "coverage",
52 |
53 | // 不用管
54 | coverageProvider: "v8",
55 | };
56 | ```
57 |
58 | ::: tip
59 | 建议不要犯了强迫症把 `jest.config.js` 的注释去掉，它们可以作为配置 Jest 的简单版文档。
60 | :::
61 |
62 | ## 第一个测试
63 |
64 | 有了基本配置后，添加一个工具函数文件 `src/utils/sum.js` 作为我们第一个业务文件：
65 |
66 | ```js
67 | // src/utils/sum.js
68 | const sum = (a, b) => {
69 | return a + b;
70 | }
71 |
72 | module.exports = sum;
73 | ```
74 |
75 | 然后，添加我们项目的第一个测试用例 `tests/utils/sum.test.js`：
76 |
77 | ```js
78 | // tests/utils/sum.test.js
79 | const sum = require("../../src/utils/sum");
80 |
81 | describe('sum', () => {
82 | it('可以做加法', () => {
83 | expect(sum(1, 1)).toEqual(2);
84 | });
85 | })
86 | ```
87 |
88 | 项目结构如下：
89 |
90 | ```
91 | ├── jest.config.js
92 | ├── package-lock.json
93 | ├── package.json
94 | ├── src
95 | │ └── utils
96 | │ └── sum.js
97 | └── tests
98 | └── utils
99 | └── sum.test.js
100 | ```
101 |
102 | ## 执行测试
103 |
104 | 一切就绪，执行以下命令启动测试：
105 |
106 | ```shell
107 | # npx jest
108 | npm run test
109 | ```
110 |
111 | 执行结果如下：
112 |
113 | 
114 |
115 | ## 单文件测试
116 | 考虑如下场景，如果我们只想测试项目中某一个单独的文件。
117 | ```shell
118 | # npx jest
119 | npm run test <文件的相对路径>
120 | ```
121 |
122 | **🎉 成功 🎉**
123 |
124 | ## 覆盖率报告
125 |
126 | 上面终端里展示的就是覆盖率情况，只不过以终端的形式展示。现在我们打开根目录下的 `coverage` 目录，会发现生成很多覆盖率文件：
127 |
128 | ```
129 | ├── clover.xml # Clover XML 格式的覆盖率报告
130 | ├── coverage-final.json # JSON 格式的覆盖率报告
131 | ├── lcov-report # HTML 格式的覆盖率报告
132 | │ ├── base.css
133 | │ ├── block-navigation.js
134 | │ ├── favicon.png
135 | │ ├── index.html # 覆盖率根文件
136 | │ ├── prettify.css
137 | │ ├── prettify.js
138 | │ ├── sort-arrow-sprite.png
139 | │ ├── sorter.js
140 | │ └── sum.js.html # sum.js 的覆盖率情况
141 | └── lcov.info
142 | ```
143 |
144 | Jest 会在 `coverage` 目录下生成各种不同格式的覆盖率报告文件，有 `XML`，`JSON`，也有 `HTML` 的。生成这么多不同格式的测试报告只只是为了方便不同工具的读取，
145 | 比如 JS 读 JSON 就比读 XML 容易，它们描述的内容都是一样的。
146 |
147 | 无论哪种格式，我们都很难直观地看懂。因此，Jest 也支持生成网页的测试报告，打开 `lcov-report/index.html` 就可以看到网页版的测试报告了：
148 |
149 | 
150 |
151 | ## 总结
152 |
153 | 这一章里，我们创建了新项目，并成功编写并测试了第一个测试用例。
154 |
155 | 然而，这只是开始，后面还有很多问题等着我们解决，马上去看下一章吧。
156 |
--------------------------------------------------------------------------------
/docs/basic/getting-started/coverage.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/docs/basic/getting-started/coverage.png
--------------------------------------------------------------------------------
/docs/basic/getting-started/jest-config.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/docs/basic/getting-started/jest-config.png
--------------------------------------------------------------------------------
/docs/basic/getting-started/test-result.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/haixiangyan/jest-tutorial/4a9a89d24d7b4a614e156b83f02fbd224f094f8e/docs/basic/getting-started/test-result.png
--------------------------------------------------------------------------------
/docs/basic/hook-test/README.md:
--------------------------------------------------------------------------------
1 | ## React Hook 测试
2 |
3 | 上一章讲了如何给 Redux 代码写测试，我们日常写的 React App 还有一个很重要的部分：React Hooks，这一章就来讲讲如何测试这部分的代码。
4 |
5 | ## useCounter
6 |
7 | 我们依然从一个需求开始讲起。假如要实现一个 `useCounter` 的 Hook，在 `src/hooks/useCounter.ts` 添加：
8 |
9 | ```ts
10 | // src/hooks/useCounter.ts
11 | import { useState } from "react";
12 |
13 | export interface Options {
14 | min?: number;
15 | max?: number;
16 | }
17 |
18 | export type ValueParam = number | ((c: number) => number);
19 |
20 | function getTargetValue(val: number, options: Options = {}) {
21 | const { min, max } = options;
22 | let target = val;
23 | if (typeof max === "number") {
24 | target = Math.min(max, target);
25 | }
26 | if (typeof min === "number") {
27 | target = Math.max(min, target);
28 | }
29 | return target;
30 | }
31 |
32 | function useCounter(initialValue = 0, options: Options = {}) {
33 | const { min, max } = options;
34 |
35 | const [current, setCurrent] = useState(() => {
36 | return getTargetValue(initialValue, {
37 | min,
38 | max,
39 | });
40 | });
41 |
42 | const setValue = (value: ValueParam) => {
43 | setCurrent((c) => {
44 | const target = typeof value === "number" ? value : value(c);
45 | return getTargetValue(target, {
46 | max,
47 | min,
48 | });
49 | });
50 | };
51 |
52 | const inc = (delta = 1) => {
53 | setValue((c) => c + delta);
54 | };
55 |
56 | const dec = (delta = 1) => {
57 | setValue((c) => c - delta);
58 | };
59 |
60 | const set = (value: ValueParam) => {
61 | setValue(value);
62 | };
63 |
64 | const reset = () => {
65 | setValue(initialValue);
66 | };
67 |
68 | return [
69 | current,
70 | {
71 | inc,
72 | dec,
73 | set,
74 | reset,
75 | },
76 | ] as const;
77 | }
78 |
79 | export default useCounter;
80 | ```
81 |
82 | 这个 Hook 很简单，就是经典的计数器，拥有增加、减少、设置和重置 4 个操作。
83 |
84 | ## 误区
85 |
86 | 有些同学会觉得 `hook` 不就是纯函数么？为什么不能直接像纯函数那样去测呢？
87 |
88 | ```ts
89 | describe("useCounter", () => {
90 | it("可以加 1", () => {
91 | const [counter, utils] = useCounter(0);
92 |
93 | expect(counter).toEqual(0);
94 |
95 | utils.inc(1);
96 |
97 | expect(counter).toEqual(1);
98 | });
99 | });
100 | ```
101 |
102 | 由于这里用到了 `useState`，而 React 规定 **只有在组件中才能使用这些 Hooks**，所以这样测试的结果就会得到下面的报错：
103 |
104 | 
105 |
106 | 那我们是否可以通过前面讲的 Mock 手段来处理掉 `useState` 呢？**千万别这么做！** 假如 Hook 里不仅有 `useState`，还有 `useEffect` 这样的呢？
107 | 难道你要每个 React API 都要 Mock 一遍么？
108 |
109 | 想想我们做测试的初衷，我们做测试是为什么？ **测试的初衷是为了带我们带来强大的代码信心。** 好了，我知道你听这句话都听烦了，我自己都说烦了。
110 |
111 | 如果你把测试初衷忘掉，会很容易掉入测试代码细节的陷阱。一旦你的关注点不是代码的信心，而是测试代码细节，那么你的测试用例会变得非常脆弱，难以维护。
112 | 这样写出来的测试不仅不能给你带来代码信心，还会拖垮开发进程，真的不如不做测试。
113 |
114 | 不好意思，唠叨了一会，我们回来看看这个例子。要解决测试代码细节这个问题，唯一的办法就是把这个东西看成整体，比如......我们真的写一个组件来做测试？**可以！安排！**
115 |
116 | ## 测试组件
117 |
118 | 安装 [@testing-library/user-event](https://www.npmjs.com/package/@testing-library/user-event) ，用于处理点击事件：
119 |
120 | ```shell
121 | npm i -D @testing-library/user-event@14.1.0
122 | ```
123 |
124 | 添加 `tests/hooks/useCounter/TestComponent.test.tsx`：
125 |
126 | ```tsx
127 | import useCounter from "hooks/useCounter";
128 | import { render, screen } from "@testing-library/react";
129 | import userEvent from "@testing-library/user-event";
130 | import React from "react";
131 |
132 | // 测试组件
133 | const UseCounterTest = () => {
134 | const [counter, { inc, set, dec, reset }] = useCounter(0);
135 | return (
136 | Hello
165 | 166 |Counter: {counter}
138 |
139 |
140 |
141 |
142 | {query.get("id")}
390 | )
391 | }
392 | ```
393 |
394 | 这个例子的难点在于：我们的测试组件要和 React Router 做交互了，否则使用 `useLocation` 时会报错：
395 |
396 | 
397 |
398 | 要创建 React Router 环境，我们可以使用 `createMemoryHistory` 这个 API：
399 |
400 | ```tsx
401 | // tests/hooks/useQuery.test.tsx
402 | import React from "react";
403 | import useQuery from "hooks/useQuery";
404 | import { createMemoryHistory, InitialEntry } from "history";
405 | import { render } from "@testing-library/react";
406 | import { Router } from "react-router-dom";
407 |
408 | const setup = (initialEntries: InitialEntry[]) => {
409 | const history = createMemoryHistory({
410 | initialEntries,
411 | });
412 |
413 | const returnVal = {
414 | query: new URLSearchParams(),
415 | };
416 |
417 | const TestComponent = () => {
418 | const query = useQuery();
419 |
420 | Object.assign(returnVal, { query });
421 |
422 | return null;
423 | };
424 |
425 | // 此处为 react router v6 的写法
426 | render(
427 |
176 |
194 | );
195 | };
196 |
197 | export default User;
198 | ```
199 |
200 | 在 `App.tsx` 里使用它：
201 |
202 | ```tsx
203 | import User from "components/User";
204 |
205 | const App = () => {
206 | return (
207 | 用户信息
177 | 178 | {status === "loading" &&加载中...
} 179 | 180 | {user.id ? ( 181 |
182 |
186 | ) : (
187 | ID：{user.id}
183 |姓名：{user.name}
184 |年龄：{user.age}
185 |无用户信息
188 | )} 189 | 190 | 193 |
208 | {/*...*/}
209 |
210 |
212 |
213 | )
214 | }
215 | ```
216 |
217 | 最后在 `index.tsx` 入口里使用 `Provider` 来包裹整个 App：
218 |
219 | ```tsx
220 | import store from "./store";
221 |
222 | ReactDOM.render(
223 | {title}
; 43 | }; 44 | 45 | export default Title; 46 | ``` 47 | 48 | 然后在 `src/App.tsx` 里使用这个组件： 49 | 50 | ```tsx 51 | // src/App.tsx 52 | import React from 'react'; 53 | import Title from "components/Title"; 54 | 55 | const App = () => { 56 | return ( 57 |
58 |
59 |
62 |
63 | )
64 | }
65 |
66 | export default App;
67 | ```
68 |
69 | 在页面上可以看到这样的效果：
70 |
71 | 
72 |
73 | ## 第一个快照
74 |
75 | 在写测试前，我们要安装一下 React 的测试库。或许你听说过很多测试 React 的测试库，这里我只推荐 [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) ：
76 |
77 | ```shell
78 | npm i -D @testing-library/react@12.1.4
79 | ```
80 |
81 | 在 `tests/components/Title.test.tsx` 添加一个快照测试：
82 |
83 | ```tsx
84 | // tests/components/Title.test.tsx
85 | import React from "react";
86 | import { render } from "@testing-library/react";
87 | import Title from "components/Title";
88 |
89 | describe("Title", () => {
90 | it("可以正确渲染大字", () => {
91 | const { baseElement } = render(
111 |
117 |
118 | `;
119 |
120 | exports[`Title 可以正确渲染小字 1`] = `
121 |
122 | 114 | 大字 115 |
116 |
123 |
129 |
130 | `;
131 | ```
132 |
133 | ## 什么是快照测试
134 |
135 | 在讲 “什么是快照测试” 之前，我们先来说说 “为什么要有快照测试”。
136 |
137 | 使用 `jest` 和 `React Testing Library` 都能完成基础的交互测试以及功能测试，但是组件毕竟是组件，是有 HTML 结构的。
138 | 如果不对比一下 HTML 结构，很难说服自己组件没问题。但是这就引来了一个问题了：**要怎么对比 HTML 结构？**
139 |
140 | 最简单的方法就是把这个组件的 `HTML` 打印出来，拷贝到一个 `xxx.txt` 文件里，然后在下次跑用例时，把当前组件的 `HTML` 字符串和 `xxx.txt`
141 | 文件里的内容对比一下就知道哪里有被修改过。 **这就是快照测试的基本理念，即：先保存一份副本文件，下次测试时把当前输出和上次副本文件对比就知道此次重构是否破坏了某些东西。**
142 |
143 | 只不过 `jest` 的快照测试提供了更高级的功能：
144 | 1. 自动创建把输出内容写到 `.snap` 快照文件，下次测试时可以自动对比
145 | 2. 输出格式化的快照文件，阅读友好，开发者更容易看懂
146 | 3. 当在做 `diff` 对比时，`jest` 能高亮差异点，而且对比信息更容易阅读
147 |
148 | 现在我们来看上面这个例子：
149 |
150 | 1. 用例第一次执行时，把 `baseElement` 的结构记录到 `Title.test.tsx.snap`
151 | 2. 等下次再执行，Jest 会自动对比当前 `baseElement` DOM 快照以及上一次 `Title.test.tsx.snap` 的内容
152 |
153 | 快照测试通过说明渲染组件没有变，如果不通过则有两种可能：
154 |
155 | 1. **代码有 Bug。** 本来好好的，被你这么一改，改出了问题
156 | 3. **实现了新功能。** 新功能可能会改变原有的 DOM 结构，所以你要用 `jest --updateSnapshot` 来更新快照
157 |
158 | 这就是快照测试了......吗？当然不是！哦，我是说做法就是这么简单，但是思路上并不简单。
159 |
160 | ## 缺陷
161 |
162 | 快照测试虽然简单，但是它有非常多的问题。我搜罗了网上很多资料，这里稍微总结一下它的缺点以及应对思路。
163 |
164 | ### 避免大快照
165 |
166 | 现在 `Title` 比较简单，所以看起来还可以，但真实业务组件中动辄就有十几个标签，还带上很多乱七八糟的属性，生成的快照文件会变得无比巨大。
167 |
168 | 对于这个问题，**我们能做的就是避免大快照，不要无脑地记录整个组件的快照**，特别是有别的 UI 组件参与其中的时候：
169 |
170 | ```tsx
171 | const Title: FC126 | 小字 127 |
128 |{title}
181 |
182 |
216 |
234 |
235 | `;
236 | ```
237 |
238 | 杂揉了 `antd` 的 DOM 结构后，快照变得非常难读。**解决方法是只记录第二个 `Col` 的 DOM 结构就好：**
239 |
240 | ```tsx
241 | describe("Title", () => {
242 | it("可以正确渲染大字", () => {
243 | const { getByText } = render(
220 |
233 |
223 | 第一个 Col
224 |
225 |
228 |
232 |
229 | 大字
230 |
231 |
261 | 大字
262 |
263 | `;
264 |
265 | exports[`Title 可以正确渲染小字 1`] = `
266 |
267 | 小字
268 |
269 | `;
270 | ```
271 |
272 | 看这样的快照就清爽多了。**不过，快照并不是越小越好。因为如果快照太小你可能会想：这样的快照还不如我写 `expect(content.children).toEqual('大字')` 来得简单。**
273 |
274 | **所以，对于那种输出很复杂，而且不方便用 `expect` 做断言时，快照测试才算是一个好方法。**
275 | 这也是为什么组件 DOM 结构适合做快照，因为 DOM 结构有大量的大于、小于、引号这些字符。如果都用 `expect` 来断言，`expect` 的结果会写得非常痛苦。
276 | 不过，需要注意的是：**不要把无关的 DOM 也记录到快照里，这无法让人看懂。**
277 |
278 | ### 假错误
279 |
280 | 假如现在把 `title` 的 “大字” 改成 “我是一个大帅哥”：
281 |
282 | ```tsx
283 | describe("Title", () => {
284 | it("可以正确渲染大字", () => {
285 | const { getByText } = render(