vue-cli 项目集成 Jest 单元测试

前言

前端单元测试对于保证代码质量和稳定性是非常重要的。

为什么需要单元测试：

• 检测bug;
• 提升回归效率；
• 保证代码质量。 

 一、框架对比

①、Mocha

比较灵活成熟，但没有内部集成，需要自主选择断言库和监听库。。

②、Jasmine

是 Jest 的底层库，助攻 BDD（即行为驱动开发）断言库与异步测试的自动化测试框架，没有外部依赖。运行在node.js 上，没有外部库，所以可以兼容所有的框架和库，但配置过程更加繁琐，使用较复杂。

③、Jest

由 FackBook 推出的，目前前端测试领域最火热的框架，它功能齐全，所需配置少，默认安装了 JSDOM，易于使用，支持异步测试，mock和快照等功能。

安全快速、开箱即用、守护模式（注重开发体验）、快照测试、文档齐全、强大的生态

④、Vue Test Utils

Vue.js 官方提供的测试工具库，它提供了一套 API 来编写和运行 Vue 组件测试用例。

二、安装

因项目是使用 vue-cli 构建的，所以这里直接使用 cli-plugin-unit-jest 插件来运行 Jest 测试。

vue add @vue/cli-plugin-unit-jest

安装之后，启动项目报错：Vue packages version mismatch，这是因为 vue 与 vue-template-compiler 版本不一致，所以这里需要修改下 vue-template-compiler 的版本，删除依赖，重新安装，或者使用下面命令。

npm install [email protected]

三、配置

执行命令 vue add @vue/cli-plugin-unit-jest 后，项目中会自动生成一个 jest.config.js 文件，自动创建了 tests/unit/example.spec.js 测试文件，以及在 package.json 文件中，自动加入了 eslint 所需配置。自动生成的代码具体如下：

// jest.config.js
module.exports = {
  preset: '@vue/cli-plugin-unit-jest'
}

// example.spec.js

import { shallowMount } from '@vue/test-utils'
import HelloWorld from '@/components/HelloWorld.vue'

describe('HelloWorld.vue', () => {
  it('renders props.msg when passed', () => {
    const msg = 'new message'
    const wrapper = shallowMount(HelloWorld, {
      propsData: { msg }
    })
    expect(wrapper.text()).toMatch(msg)
  })
})

// package.json

"eslintConfig": {
    "overrides": [
      {
        "files": [
          "**/__tests__/*.{j,t}s?(x)",
          "**/tests/unit/**/*.spec.{j,t}s?(x)"
        ],
        "env": {
          "jest": true
        }
      }
    ]
}

另外，命令在 package.json 中自动添加了启动命令，在控制台执行 npm run test:unit，就可以看到测试结果。

 "test:unit": "vue-cli-service test:unit",

四、jest.config.js 配置项

module.exports = {
  // 预设
  preset: '@vue/cli-plugin-unit-jest',
  // 多于一个测试文件运行时展示每个测试用例测试通过情况
  verbose: true,
  // 参数指定只要有一个测试用例没有通过，就停止执行后面的测试用例
  bail: true,
  // 测试环境，jsdom 可以在 Node 虚拟浏览器环境运行测试
  testEnvironment: 'jsdom',
  // 需要检测的文件类型(不需要配置)
  moduleFileExtensions: ['js', 'jsx', 'json', 'vue'],
  // 预处理器配置，匹配的文件要经过转译才能被识别，否则会报错(不需要配置)
  transform: {
    // 用 `vue-jest` 处理 `*.vue` 文件
    ".*\\.(vue)$": "/node_modules/vue-jest",
    // 用 `babel-jest` 处理 js
    "^.+\\.js$": "babel-jest"
  },
  // 转译时忽略 node_modules
  transformIgnorePatterns: ['/node_modules/'],
  // 从正则表达式到模块名称的映射，和webpack的alisa类似(不需要配置)
  moduleNameMapper: {
    '^@/(.*)$': '/src/$1'
  },
  // Jest用于检测测试的文件，可以用正则去匹配
  testMatch: [
    '**/tests/unit/**/*.spec.[jt]s?(x)',
    '**/__tests__/*.[jt]s?(x)'
  ],
  // 是否显示覆盖率报告，开启后显示代码覆盖率详细信息，将测试用例结果输出到终端
  collectCoverage: true,
  // 告诉 jest 哪些文件需要经过单元测试测试
  collectCoverageFrom: ["src/**/*.{js,vue}", "!**/node_modules/**"],
  // 覆盖率报告输出的目录
  coverageDirectory: 'tests/unit/coverage',
  // 报告的格式
  coverageReporters: ["html", "text-summary"],
  // 需要跳过覆盖率信息收集的文件目录
  coveragePathIgnorePatterns: ['/node_modules/'],
  // 设置单元测试覆盖率阈值, 如果未达到阈值，Jest 将返回失败
  coverageThreshold: {
    global: {
      statements: 90, // 保证每个语句都执行了
      functions: 90, // 保证每个函数都调用了
      branches: 90, // 保证每个 if 等分支代码都执行了
      lines: 90
    },
  },
  // Jest在快照测试中使用的快照序列化程序模块的路径列表
  snapshotSerializers: ["/node_modules/jest-serializer-vue"]
}

五、常用API

①、test(name, fn, timeout)

test 有个别名 it，两个方法是一样的。

name：描述测试用例名称。

fn：期望测试的函数，也是测试用例的核心。

timeout（可选）：超时时间，也就是超过多久将会取消测试（默认是5秒钟）。

②、toBe(value)

toBe 是最简单最基础的匹配器，判定是否精确匹配，即 x === y。

test('two plus two is four', () => {
  expect(2 + 2).toBe(4);
});

• toBeNull：只匹配 null ；
• toBeNaN：只匹配 NaN ；
• toBeUndefined：只匹配 undefined ；
• toBeDefined：与 toBeUndefined 相反 ；
• toBeTruthy：匹配任何 if 语句为真 ；
• toBeFalsy：匹配任何 if 语句为假 ；
• toBeGreaterThan ：匹配数字时使用，期望大于，即 result > x ；
• toBeGreaterThanOrEqual ：匹配数字时使用，期望大于等于，即 result > = x ；
• toBeLessThan ：匹配数字时使用，期望小于，即 result < x ；
• toBeLessThanOrEqual ：匹配数字时使用，期望小于等于，即 result <= x ；
• toBeCloseTo：小数点精度问题匹配，例如 0.1+0.2 != 0.3，但我们期望它等于，就需要使用toBeCloseTo。

③、toEqual

对象、数组的深度匹配。递归检查对象或数组的每个字段。

和上面的 toBe 进行对比，toBe 匹配对象对比的是内存地址，toEqual 对比的是属性值。

test('object assignment', () => {
  const data1 = { one: 1, two: 2 };
  const data2 = { one: 1, two: 2 };
  expect(data1).toBe(data2); // 测试失败
  expect(data1).toEqual(data2);// 测试通过
});

④、not

不匹配，一般就是反向测试，后面可以跟其他匹配符，例如 

test('two plus two is four', () => {
  expect(2 + 2).not.toBe(4);
});

⑤、toMatch

 匹配字符串时使用，期望字符串包含另一个字符串。

expect("abc").toMatch("a")

⑥、toContain

 检查一个数组中是否包含一个值时使用。

const arr = ['a', 'b', 'c', 'd', 'e'];

test('the arr has a on it', () => {
  expect(arr).toContain('a');
});

 更多 API 可以参考官网：Expect 断言 · Jest

六、编写用例

 最基本的流程：输入 - 预期输出 - 验证结果

1. 引入要测试的函数
2. 给函数一个输入
3. 定义预期输出
4. 检查函数是否返回了预期的输出结果

Jest的单元测试核心就是在 test 方法的第二个参数里面，expect 方法返回一个期望对象，通过匹配器（例如toBe）进行断言，期望是否和你预期一致，和预期一致则单元测试通过，不一致则测试无法通过，需要排除问题然后继续进行单元测试。

// Counter.vue

// @/tests/unit/specs/Counter.spec.js
import { mount } from "@vue/test-utils";
import Counter from '@/components/Counter.vue'

describe('Counter.vue', () => {
  const wrapper = mount(Counter)

  // 渲染
  it('renders', () => {
    expect(wrapper.html()).toContain('
0
')
  })

  // 是否有按钮
  it('has a button', () => {
    expect(wrapper.find('button').exists()).toBeTruthy()
  })

  // 模拟用户交互
  // 使用 nextTick 与 await
  it('button click', async () => {
    expect(wrapper.vm.count).toBe(0)
    const button = wrapper.find('button')
    await button.trigger('click')
    expect(wrapper.vm.count).toBe(1)
  })
})

七、生成测试覆盖率报告

单元测试覆盖率是一种软件测试的度量指标，指在所有功能代码中，完成了单元测试的代码所占的比例。最基础的计算方式为：

单元测试覆盖率 = 被测代码行数 / 参测代码总行数 * 100%

可以通过修改 package.json 命令行来生成

"test:unit": "vue-cli-service test:unit --coverage",

或者可以修改 jest.config.js 文件，加入配置项：

module.exports = {
  ...
  // 是否显示覆盖率报告
  collectCoverage: true
}

执行效果如下：

 具体参数含义:

参数名	含义	说明
% stmts	语句覆盖率	是不是每个语句都执行了
% Branch	分支覆盖率	是不是每个 if 代码块都执行了
% Funcs	函数覆盖率	是不是每个函数都调用了
% Lines	行覆盖率	是不是每一行都执行了
Uncovered Line #s	未覆盖行数	哪些行代码没有执行

设置单元测试覆盖率阈值

测试覆盖率一定程度上客观反应了单元测试的质量，可以通过设置单元测试阈值来提示用户是否达到了预期质量。

module.exports = {
  preset: '@vue/cli-plugin-unit-jest',
  // 是否显示覆盖率报告
  collectCoverage: true,
  // 告诉 jest 哪些文件需要经过单元测试测试
  collectCoverageFrom: ['src/utils/**/*'],
  // 设置单元测试覆盖率阈值
  coverageThreshold: {
    global: {
      statements: 90, // 保证每个语句都执行了
      functions: 90, // 保证每个函数都调用了
      branches: 90, // 保证每个 if 等分支代码都执行了
    },
  }
}

 如果我们的测试用例没有足够充分，会有报错提示帮助我们去完善。

八、持续监听 

为了提高效率，可以通过加启动参数的方式让 jest 持续监听文件的修改，而不需要每次修改完再重新执行测试用例。修改 package.json

"test:unit": "vue-cli-service test:unit --watchAll",

然后执行命令，控制台会出现 watch usage 菜单，其中包含将在特定按键按下时执行不同命令。

 也可以在 jest.config.js 中配置 watch 插件

// jest.config.js
module.exports = {
  ...,
  watchPlugins: [ // jest监视插件
    require.resolve('jest-watch-typeahead/filename'),
    require.resolve('jest-watch-typeahead/testname')
  ]
}

九、异步测试

先来写一个简单的测试用例，定义一个接收 callback 函数为参数的 fetchData 函数，会在一段时间后调用 callback，并在回调函数的参数中传入数据 hello jest。具体代码如下

const fetchData = callback =>  {
  setTimeout(() => {
    callback('hello jest')
  }, 1000)
}

describe('fetchData', () => {
  it('测试返回值是否一致', () => {
    const callback = data => {
      expect(data).toBe('hello')
    }
  
    fetchData(callback)
  })
})

上述代码应该是验证不通过的，因为我们传入的值与断言语句期望的值是不一致的，但是 Jest 却测试通过了。

这是因为默认情况下，Jest 测试一旦执行到末尾就会完成，因此上面的代码中执行到 fetchData(callback) 就直接结束了，回调函数中的断言语句根本没有执行。

解决这个问题，有几种方法，下面进行逐一讲解。

①、done

将 it 函数的第二个参数由无参回调改为一个接收一个 done 参数的回调，Jest 会等 done 回调函数执行结束后，结束测试。

describe('fetchData', () => {
  it('测试返回值是否一致', (done) => {
    const callback = data => {
      expect(data).toBe('hello')
      done()
    }
  
    fetchData(callback)
  })
})

修改为上述代码，测试用例断言语句被执行，控制台报错。

若 done 函数从未被调用，测试用例执行将会失败，同时输出超时错误。

如果需要明确知道测试用例失败的原因，需要将 expect 放入 try 中，然后将 error 传递给 catch 中的 done 函数。

describe('fetchData', () => {
  it('测试返回值是否一致', (done) => {
    const callback = data => {
      try {
        expect(data).toBe('hello')
        done()
      } catch (error) {
        done(error)
      }
    }
  
    fetchData(callback)
  })
})

②、Promise

如果异步代码中使用了 Promise，需要在测试用例中将 Promise 对象返回。

const fetchData = () =>  {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve('hello jest')
    }, 1000)
  })
  
}

describe('fetchData', () => {
  it('测试返回值是否一致', () => {
    // 一定记得加上 return，否则测试在 fetchData 执行完成之前就已经结束，随后then中的expect也不会执行，会导致超时错误
    return fetchData().then(data => {
      expect(data).toBe('hello jest')
    })
  })
})

如果需要测试 reject 状态的 Promise，除了需要在 catch 方法中执行断言外，还需要使用 expect.assertions 来验证是否调用了指定次数的断言，以确保测试用例中的所有断言都已被执行。如果没有指定断言数量，测试用例中的任何一个断言都可能被忽略，这会导致测试结果不准确。

const fetchData = condition => {
  return condition ? Promise.resolve('success message') : Promise.reject('error message')
}

// 正常 catch 时没有问题
test('Promise rejected 1', () => {
  return fetchData(false).catch(error => {
    expect(error).toBe('error message')  // 测试通过
  })
})

test('Promise rejected 2', () => {
  // 接口成功，因为不会执行catch
  return fetchData(true).catch(error => {
    expect(error).toBe('error message')  // 测试通过
  })
})

test('Promise rejected 3', () => {
  expect.assertions(1) // 至少执行一次 expect
  // 将fetchData(true)改为fetchData(false)，接口失败才能执行catch里面的断言
  return fetchData(true).catch(error => { // 测试失败
    expect(error).toBe('error message')  
  })
})

③、.resolves / .rejects 匹配器

使用 Promise 时，也可以在 expect 语句中使用 .resolves 匹配器，Jest 将等待此 Promise 被处理，如果 Promise 被拒绝，测试将自动失败。

test('Promise resolves', () => {
  return expect(fetchData(true)).resolves.toBe('success message')
})

与之对应，可以使用 .rejects 测试被拒绝的 Promise。

test('Promise rejects', () => {
  return expect(fetchData(false)).rejects.toBe('error message')
})

④、async await 

也可以在测试中使用 async 和 await，代码如下：

test('success', async () => {
  const data = await fetchData(true)
  expect(data).toBe('success message')
})

test('error', async () => {
  expect.assertions(1)
  try {
    await fetchData(false)
  } catch (error) {
    expect(error).toBe('error message')
  }
})

也可以将 async / await 和 .resolves / .rejects 一起使用。

test('success', async () => {
  await expect(fetchData(true)).resolves.toBe('success message')
})

test('error', async () => {
  await expect(fetchData(false)).rejects.toBe('error message')
})

十、全局钩子

①、beforeAll(fn, timeout)

文件内所有测试开始前执行的钩子函数。

使用 beforeAll 设置一些在测试用例之间共享的全局状态。

②、afterAll(fn, timeout)

文件内所有测试完成后执行的钩子函数。

使用 afterAll 清理一些在测试用例之间共享的全局状态。

③、beforeEach(fn, timeout)

文件内所有测试开始前执行的钩子函数。

使用 beforeAll 设置一些在测试用例之间共享的全局状态。

④、afterEach(fn, timeout)

文件内每个测试完成后执行的钩子函数。

使用 afterEach 清理一些在每个测试中创建的临时状态。

注：以上所有钩子函数，如果传入的回调函数返回值是 promise 或者 generator，Jest 会等待 promise resolve 再继续执行。

第二个可选参数 timeout（毫秒） 指定函数执行超时时间

执行顺序如下：

// 预设和清理
beforeAll(() => {
  console.log('beforeAll')
})

beforeEach(() => {
  console.log('beforeEach')
})

afterEach(() => {
  console.log('afterEach')
})

afterAll(() => {
  console.log('afterAll')
})

⑤、describe(name, fn)

describe 是一个将多个相关的测试组合在一起的块。一个 describe 代表一个作用域。当上述钩子函数定义在 describe 块内部时，则其只适用于该 describe 块内的测试。

十一、全局插件

如果需要安装所有 test 都使用到的全局插件，例如 element-ui，可以使用 setupFiles，首先需要在 jest.config.js 文件中指定 setup 文件。

// jest.config.js
module.exports = {
  setupFiles: ['/tests/unit/specs/setup.js']
}

 然后在 tests/unit/specs 目录下创建 setup.js 文件

import Vue from 'vue'

// 以下全局注册的插件在jest中不生效，必须使用localVue
import ElementUI from 'element-ui'

Vue.use(ElementUI)

// 阻止启动生产消息，常用作指令。
Vue.config.productionTip = false

当你只想在某些 test 中安装全局插件时，可以使用 localVue 来创建一个临时的 Vue 实例。

import { createLocalVue, mount } from '@vue/test-utils'
import ElementUI from 'element-ui'
// 引入组件
import ELFormInput from '@/components/ELFormInput.vue'

// createLocalVue 返回一个 Vue 的类供你添加组件、混入和安装插件而不会污染全局的 Vue 类。
const localVue = createLocalVue()
localVue.use(ElementUI)

// describe 代表一个作用域 
describe('ELFormInput.vue', () => {
  // 创建一个包含被挂载和渲染的 Vue 组件的 Wrapper
  // 在挂载选项中传入 localVue
  const wrapper = mount(ELFormInput, {
    localVue,
    propsData: {

    }
  })
  // input create 这里是一个自定义的描述性文字
  it('input create', async ()=> {
    expect(wrapper.find('input').exists()).toBeTruthy()
    // classes() 方法，返回 class 名称的数组。或在提供 class 名的时候返回一个布尔值
    // toBe 和toEqual 类似，区别在于toBe 更严格限于同一个对象，如果是基本类型则没什么区别
    expect(wrapper.classes('el-input')).toBe(true)
  })
})

十二、mock函数

十三、用例规范

• 测试脚本都要放在 tests/unit/specs 目录下
• 脚本命名方式为[组件名].spec.js
• 测试脚本由多个 describe 组成，每个 describe 由多个 it 组成
• 测试脚本 describe 描述填写组件名，it 描述需要简洁清晰直观

持续更新中。。。。