原文链接:https://juejin.im/post/5d3ea1225188255d5d33a40b 作者:deqwin(沐童) Github Homepage:https://github.com/deqwin
项目Git地址:https://github.com/deqwin/simple-mocha.git
前言
Mocha 是目前最流行的 JavaScript 测试框架,理解 Mocha 的内部实现原理有助于我们更深入地了解和学习自动化测试。然而阅读源码一直是个让人望而生畏的过程,大量的高级写法经常是晦涩难懂,大量的边缘情况的处理也十分影响对核心代码的理解,以至于写一篇源码解析过后往往是连自己都看不懂。所以,这次我们不生啃 Mocha 源码,换个方式,从零开始一步步实现一个简易版的 Mocha。
一、我们将实现什么?
- Pre-Loader(预加载功能):通过 describe/it 函数定义一组或单个的测试用例,通过 loader 处理,可转化成一个树状结构的 object;
- Runner(执行器):object 可以通过 Runner 执行回归测试,输出测试结果(也是一个树状 object),且该 Runner 包含 Hook 机制(包括 before、after、beforeEach、afterEach);
- Reporter(报告器):利用测试结果,生成简单格式的测试报告输出。
二、Mocha 的 BDD 测试
Mocha 支持 BDD/TDD 等多种测试风格,默认使用 BDD 接口。BDD(行为驱动开发)是一种以需求为导向的敏捷开发方法,相比主张”测试先行“的 TDD(测试驱动开发)而言,它强调”需求先行“,从一个更加宏观的角度去关注包括开发、QA、需求方在内的多方利益相关者的协作关系,力求让开发者“做正确的事“。在 Mocha 中,一个简单的 BDD 式测试用例如下:
describe('Array', function() {describe('#indexOf()', function() {before(function() {// ...});it('should return -1 when not present', function() {// ...});it('should return the index when present', function() {// ...});after(function() {// ...});});});
Mocha 的 BDD 测试主要包括以下几个 API:
describe/context:行为描述,代表一个测试块,是一组测试单元的集合;it/specify:描述了一个测试单元,是最小的测试单位;before:Hook 函数,在执行该测试块之前执行;after:Hook 函数,在执行该测试块之后执行;beforeEach:Hook 函数,在执行该测试块中每个测试单元之前执行;afterEach:Hook 函数,在执行该测试块中每个测试单元之后执行。
三、开始
话不多说,我们直接开始。
3.1 目录设计
新建一个项目,命名为 simple-mocha。目录结构如下:
├─ mocha/│ ├─ index.js│ ├─ src/│ ├─ interfaces/│ └─ reporters/├─ test/└─ package.json
先对这个目录结构作简单解释:
mocha/:存放我们即将实现的 simple-mocha 的源代码mocha/index.js:simple-mocha 入口mocha/src/:simple-mocha 核心代码mocha/interfaces/:存放各类风格的测试接口,如 BDDmocha/reporters/:存放用于输出测试报告的各种 reporter,如 SPECtest/:存放我们编写的测试用例package.json
其中 package.json 内容如下:
{"name": "simple-mocha","version": "1.0.0","description": "a simple mocha for understanding the mechanism of mocha","main": "","scripts": {"test": "node mocha/index.js"},"author": "hankle","license": "ISC"}
执行 npm test 就可以启动执行测试用例。
3.2 模块设计
Mocha 的 BDD 测试应该是一个”先定义后执行“的过程,这样才能保证其 Hook 机制正确执行,而与代码编写顺序无关,因此我们把整个测试流程分为两个阶段:收集测试用例(定义)和执行测试用例(执行)。我们构造了一个 Mocha 类来完成这两个过程,同时这个类也负责统筹协调其他各模块的执行,因此它是整个测试流程的核心。
// mocha/src/mocha.jsclass Mocha {constructor() {}run() {}}module.exports = Mocha;
// mocha/index.jsconst Mocha = require('./src/mocha');const mocha = new Mocha();mocha.run();
另一方面我们知道,describe 函数描述了一个测试集合,这个测试集合除包括若干测试单元外,还拥有着一些自身的 Hook 函数,维护了一套严格的执行流。it 函数描述了一个测试单元,它需要执行测试用例,并且接收断言结果。这是两个逻辑复杂的单元,同时需要维护一定的内部状态,我们用两个类(Suite/Test)来分别构造它们。此外我们可以看出,BDD 风格的测试用例是一个典型的树形结构,describe 定义的测试块可以包含测试块,也可以包含 it 定义的测试单元。所以 Suite/Test 实例还将作为节点,构造出一棵 suite-test 树。比如下边这个测试用例:
describe('Array', function () {describe('#indexOf()', function () {it('should return -1 when not present', function () {// ...})it('should return the index when present', function () {// ...})})describe('#every()', function () {it('should return true when all items are satisfied', function () {// ...})})})
由它构造出来的 suite-test 树是这样的:
┌────────────────────────────────────────────────────────┐┌─┤ test:"should return -1 when not present" │┌────────────────────┐ │ └────────────────────────────────────────────────────────┘┌─┤ suite:"#indexOf()" ├─┤│ └────────────────────┘ │ ┌────────────────────────────────────────────────────────┐┌───────────────┐ │ └─┤ test:"should return the index when present" ││ suite:"Array" ├─┤ └────────────────────────────────────────────────────────┘└───────────────┘ ││ ┌────────────────────┐ ┌────────────────────────────────────────────────────────┐└─┤ suite:"#every()" ├───┤ test:"should return true when all items are satisfied" │└────────────────────┘ └────────────────────────────────────────────────────────┘
因此,Suite/Test 除了要能够表示 describe/it 之外,还应该能够诠释这种树状结构的父子级关系:
// mocha/src/suite.jsclass Suite {constructor(props) {this.title = props.title; // Suite名称,即describe传入的第一个参数this.suites = []; // 子级suitethis.tests = []; // 包含的testthis.parent = props.parent; // 父suitethis._beforeAll = []; // before hookthis._afterAll = []; // after hookthis._beforeEach = []; // beforeEach hookthis._afterEach = []; // afterEach hookif (props.parent instanceof Suite) {props.parent.suites.push(this);}}}module.exports = Suite;
// mocha/src/test.jsclass Test {constructor(props) {this.title = props.title; // Test名称,即it传入的第一个参数this.fn = props.fn; // Test的执行函数,即it传入的第二个参数}}module.exports = Test;
因此,我们需要完善一下目录结构:
├─ mocha/│ ├─ index.js│ ├─ src/│ │ ├─ mocha.js│ │ ├─ runner.js│ │ ├─ suite.js│ │ ├─ test.js│ │ └─ utils.js│ ├─ interfaces/│ │ ├─ bdd.js│ │ └─ index.js│ └─ reporters/│ ├─ spec.js│ └─ index.js├─ test/└─ package.json
考虑到执行测试用例的过程较为复杂,我们把这块逻辑单独抽离到 runner.js,它将在执行阶段负责调度 suite 和 test 节点并运行测试用例,后续会详细说到。
3.3 收集测试用例
收集测试用例环节首先需要创建一个 suite 根节点,并将 API 挂载到全局,然后再执行测试用例文件 *.spec.js 进行用例收集,最终将生成一棵与之结构对应的 suite-test 树。
3.3.1 suite 根节点
我们先创建一个 suite 实例,作为整棵 suite-test 树的根节点,同时它也是我们收集和执行测试用例的起点。
// mocha/src/mocha.jsconst Suite = require('./suite');class Mocha {constructor() {// 创建一个suite根节点this.rootSuite = new Suite({title: '',parent: null});}// ...}
3.3.2 BDD API 的全局挂载
在我们使用 Mocha 编写测试用例时,我们不需要手动引入 Mocha 提供的任何模块,就能够直接使用 describe、it 等一系列 API。那怎么样才能实现这一点呢?很简单,把 API 挂载到 global 对象上就行。因此,我们需要在执行测试用例文件之前,先将 BDD 风格的 API 全部作全局挂载。
// mocha/src/mocha.js// ...const interfaces = require('../interfaces');class Mocha {constructor() {// 创建一个根suite// ...// 使用bdd测试风格,将API挂载到global对象上const ui = 'bdd';interfaces[ui](global, this.rootSuite);}// ...}
// mocha/interfaces/index.jsmodule.exports.bdd = require('./bdd');
// mocha/interfaces/bdd.jsmodule.exports = function (context, root) {context.describe = context.context = function (title, fn) {}context.it = context.specify = function (title, fn) {}context.before = function (fn) {}context.after = function (fn) {}context.beforeEach = function (fn) {}context.afterEach = function (fn) {}}
3.3.3 BDD API 的具体实现
我们先看看 describe 函数怎么实现。
describe 传入的 fn 参数是一个函数,它描述了一个测试块,测试块包含了若干子测试块和测试单元。因此我们需要执行 describe 传入的 fn 函数,才能够获知到它的子层结构,从而构造出一棵完整的 suite-test 树。而逐层执行 describe 的 fn 函数,本质上就是一个深度优先遍历的过程,因此我们需要利用一个栈(stack)来记录 suite 根节点到当前节点的路径。
// mocha/interfaces/bdd.jsconst Suite = require('../src/suite');const Test = require('../src/test');module.exports = function (context, root) {// 记录 suite 根节点到当前节点的路径const suites = [root];context.describe = context.context = function (title, fn) {const parent = suites[0];const suite = new Suite({title,parent});suites.unshift(suite);fn.call(suite);suites.shift(suite);}}
每次处理一个 describe 时,我们都会构建一个 Suite 实例来表示它,并且在执行 fn 前入栈,执行 fn 后出栈,保证 suites[0] 始终是当前正在处理的 suite 节点。利用这个栈列表,我们可以在遍历过程中构建出 suite 的树级关系。
同样的,其他 API 也都需要依赖这个栈列表来实现:
// mocha/interfaces/bdd.jsmodule.exports = function (context, root) {// 记录 suite 根节点到当前节点的路径const suites = [root];// context.describe = ...context.it = context.specify = function (title, fn) {const parent = suites[0];const test = new Test({title,fn});parent.tests.push(test);}context.before = function (fn) {const cur = suites[0];cur._beforeAll.push(fn);}context.after = function (fn) {const cur = suites[0];cur._afterAll.push(fn);}context.beforeEach = function (fn) {const cur = suites[0];cur._beforeEach.push(fn);}context.afterEach = function (fn) {const cur = suites[0];cur._afterEach.push(fn);}}
3.3.4 执行测试用例文件
一切准备就绪,我们开始 require 测试用例文件。要完成这个步骤,我们需要一个函数来协助完成,它负责解析 test 路径下的资源,返回一个文件列表,并且能够支持 test 路径为文件和为目录的两种情况。
// mocha/src/utils.jsconst path = require('path');const fs = require('fs');module.exports.lookupFiles = function lookupFiles(filepath) {let stat;// 假设路径是文件try {stat = fs.statSync(`${filepath}.js`);if (stat.isFile()) {// 确实是文件,直接以数组形式返回return [filepath];}} catch(e) {}// 假设路径是目录let files = []; // 存放目录下的所有文件fs.readdirSync(filepath).forEach(function(dirent) {let pathname = path.join(filepath, dirent);try {stat = fs.statSync(pathname);if (stat.isDirectory()) {// 是目录,进一步递归files = files.concat(lookupFiles(pathname));} else if (stat.isFile()) {// 是文件,补充到待返回的文件列表中files.push(pathname);}} catch(e) {}});return files;}
// mocha/src/mocha.js// ...const path = require('path');const utils = require('./utils');class Mocha {constructor() {// 创建一个根suite// ...// 使用bdd测试风格,将API挂载到global对象上// ...// 执行测试用例文件,构建suite-test树const spec = path.resolve(__dirname, '../../test');const files = utils.lookupFiles(spec);files.forEach(file => {require(file);});}// ...}
3.4 执行测试用例
在这个环节中,我们需要通过遍历 suite-test 树来递归执行 suite 节点和 test 节点,并同步地输出测试报告。
3.4.1 异步执行
Mocha 的测试用例和 Hook 函数是支持异步执行的。异步执行的写法有两种,一种是函数返回值为一个 promise 对象,另一种是函数接收一个入参 done,并由开发者在异步代码中手动调用 done(error) 来向 Mocha 传递断言结果。所以,在执行测试用例之前,我们需要一个包装函数,将开发者传入的函数 promise 化:
// mocha/src/utils.js// ...module.exports.adaptPromise = function(fn) {return () => new Promise(resolve => {if (fn.length == 0) { // 不使用参数 donetry {const ret = fn();// 判断是否返回promiseif (ret instanceof Promise) {return ret.then(resolve, resolve);} else {resolve();}} catch (error) {resolve(error);}} else { // 使用参数 donefunction done(error) {resolve(error);}fn(done);}})}
这个工具函数传入一个函数 fn 并返回另外一个函数,执行返回的函数能够以 promise 的形式去运行 fn。这样一来,我们需要稍微修改一下之前的代码:
// mocha/interfaces/bdd.js// ...const { adaptPromise } = require('../src/utils');module.exports = function (context, root) {// ...context.it = context.specify = function (title, fn) {// ...const test = new Test({title,fn: adaptPromise(fn)});// ...}context.before = function (fn) {// ...cur._beforeAll.push(adaptPromise(fn));}context.after = function (fn) {// ...cur._afterAll.push(adaptPromise(fn));}context.beforeEach = function (fn) {// ...cur._beforeEach.push(adaptPromise(fn));}context.afterEach = function (fn) {// ...cur._afterEach.push(adaptPromise(fn));}}
3.4.2 测试用例执行器
执行测试用例需要调度 suite 和 test 节点,因此我们需要一个执行器(runner)来统一负责执行过程。这是执行阶段的核心,我们先直接贴代码:
// mocha/src/runner.jsconst EventEmitter = require('events').EventEmitter;// 监听事件的标识const constants = {EVENT_RUN_BEGIN: 'EVENT_RUN_BEGIN', // 执行流程开始EVENT_RUN_END: 'EVENT_RUN_END', // 执行流程结束EVENT_SUITE_BEGIN: 'EVENT_SUITE_BEGIN', // 执行suite开始EVENT_SUITE_END: 'EVENT_SUITE_END', // 执行suite开始EVENT_FAIL: 'EVENT_FAIL', // 执行用例失败EVENT_PASS: 'EVENT_PASS' // 执行用例成功}class Runner extends EventEmitter {constructor() {super();// 记录 suite 根节点到当前节点的路径this.suites = [];}/** 主入口*/async run(root) {this.emit(constants.EVENT_RUN_BEGIN);await this.runSuite(root);this.emit(constants.EVENT_RUN_END);}/** 执行suite*/async runSuite(suite) {// suite执行开始this.emit(constants.EVENT_SUITE_BEGIN, suite);// 1)执行before钩子函数if (suite._beforeAll.length) {for (const fn of suite._beforeAll) {const result = await fn();if (result instanceof Error) {this.emit(constants.EVENT_FAIL, `"before all" hook in ${suite.title}: ${result.message}`);// suite执行结束this.emit(constants.EVENT_SUITE_END);return;}}}// 路径栈推入当前节点this.suites.unshift(suite);// 2)执行testif (suite.tests.length) {for (const test of suite.tests) {await this.runTest(test);}}// 3)执行子级suiteif (suite.suites.length) {for (const child of suite.suites) {await this.runSuite(child);}}// 路径栈推出当前节点this.suites.shift(suite);// 4)执行after钩子函数if (suite._afterAll.length) {for (const fn of suite._afterAll) {const result = await fn();if (result instanceof Error) {this.emit(constants.EVENT_FAIL, `"after all" hook in ${suite.title}: ${result.message}`);// suite执行结束this.emit(constants.EVENT_SUITE_END);return;}}}// suite结束this.emit(constants.EVENT_SUITE_END);}/** 执行suite*/async runTest(test) {// 1)由suite根节点向当前suite节点,依次执行beforeEach钩子函数const _beforeEach = [].concat(this.suites).reverse().reduce((list, suite) => list.concat(suite._beforeEach), []);if (_beforeEach.length) {for (const fn of _beforeEach) {const result = await fn();if (result instanceof Error) {return this.emit(constants.EVENT_FAIL, `"before each" hook for ${test.title}: ${result.message}`)}}}// 2)执行测试用例const result = await test.fn();if (result instanceof Error) {return this.emit(constants.EVENT_FAIL, `${test.title}`);} else {this.emit(constants.EVENT_PASS, `${test.title}`);}// 3)由当前suite节点向suite根节点,依次执行afterEach钩子函数const _afterEach = [].concat(this.suites).reduce((list, suite) => list.concat(suite._afterEach), []);if (_afterEach.length) {for (const fn of _afterEach) {const result = await fn();if (result instanceof Error) {return this.emit(constants.EVENT_FAIL, `"after each" hook for ${test.title}: ${result.message}`)}}}}}Runner.constants = constants;module.exports = Runner
代码很长,我们稍微捋一下。
首先,我们构造一个 Runner 类,利用两个 async 方法来完成对 suite-test 树的遍历:
runSuite:负责执行 suite 节点。它不仅需要调用 runTest 执行该 suite 节点上的若干 test 节点,还需要调用 runSuite 执行下一级的若干 suite 节点来实现遍历,同时,before/after 也将在这里得到调用。执行顺序依次是:before -> runTest -> runSuite -> after。runTest:负责执行 test 节点,主要是执行该 test 对象上定义的测试用例。另外,beforeEach/afterEach 的执行有一个类似浏览器事件捕获和冒泡的过程,我们需要沿节点路径向当前 suite 节点方向和向 suite 根节点方向分别执行各 suite 的 beforeEach/afterEach 钩子函数。执行顺序依次是:beforeEach -> run test case -> afterEach。
在遍历过程中,我们依然是利用一个栈列表来维护 suite 根节点到当前节点的路径。同时,这两个流程都用 async/await 写法来组织,保证所有任务在异步场景下依然是按序执行的。
其次,测试结论是“边执行边输出”的。为了在执行过程中能向 reporter 实时通知执行结果和执行状态,我们让 Runner 类继承自 EventEmitter 类,使其具备了事件订阅/发布的能力,这个后续会细讲。
最后,我们在 Mocha 实例的 run 方法中去实例化 Runner 并调用它:
// mocha/src/mocha.js
// ...
const Runner = require('./runner');
class Mocha {
// ...
run() {
const runner = new Runner();
runner.run(this.rootSuite);
}
}
3.4.3 输出测试报告
reporter 负责测试报告输出,这个过程是在执行测试用例的过程中同步进行的,因此我们利用 EventEmitter 让 reporter 和 runner 保持通信。在 runner 中我们已经在各个关键节点都作了 event emit,所以我们只需要在 reporter 中加上相应的事件监听即可:
// mocha/reporters/index.js
module.exports.spec = require('./spec');
// mocha/reporters/spec.js
const constants = require('../src/runner').constants;
module.exports = function (runner) {
// 执行开始
runner.on(constants.EVENT_RUN_BEGIN, function() {});
// suite执行开始
runner.on(constants.EVENT_SUITE_BEGIN, function(suite) {});
// suite执行结束
runner.on(constants.EVENT_SUITE_END, function() {});
// 用例通过
runner.on(constants.EVENT_PASS, function(title) {});
// 用例失败
runner.on(constants.EVENT_FAIL, function(title) {});
// 执行结束
runner.once(constants.EVENT_RUN_END, function() {});
}
Mocha 类中引入 reporter,执行事件订阅,就能让 runner 将测试的状态结果实时推送给 reporter 了:
// mocha/src/mocha.js
const reporters = require('../reporters');
// ...
class Mocha {
// ...
run() {
const runner = new Runner();
reporters['spec'](runner);
runner.run(this.rootSuite);
}
}
reporter 中可以任意构造你想要的报告样式输出,例如这样:
// mocha/reporters/spec.js
const constants = require('../src/runner').constants;
const colors = {
pass: 90,
fail: 31,
green: 32,
}
function color(type, str) {
return '\u001b[' + colors[type] + 'm' + str + '\u001b[0m';
}
module.exports = function (runner) {
let indents = 0;
let passes = 0;
let failures = 0;
function indent(i = 0) {
return Array(indents + i).join(' ');
}
// 执行开始
runner.on(constants.EVENT_RUN_BEGIN, function() {
console.log();
});
// suite执行开始
runner.on(constants.EVENT_SUITE_BEGIN, function(suite) {
console.log();
++indents;
console.log(indent(), suite.title);
});
// suite执行结束
runner.on(constants.EVENT_SUITE_END, function() {
--indents;
if (indents == 1) console.log();
});
// 用例通过
runner.on(constants.EVENT_PASS, function(title) {
passes++;
const fmt = indent(1) + color('green', ' ✓') + color('pass', ' %s');
console.log(fmt, title);
});
// 用例失败
runner.on(constants.EVENT_FAIL, function(title) {
failures++;
const fmt = indent(1) + color('fail', ' × %s');
console.log(fmt, title);
});
// 执行结束
runner.once(constants.EVENT_RUN_END, function() {
console.log(color('green', ' %d passing'), passes);
console.log(color('fail', ' %d failing'), failures);
});
}
3.5 验证
到这里,我们的 simple-mocha 就基本完成了,我们可以编写一个测试用例来简单验证一下:
// test/test.spec.js
const assert = require('assert');
describe('Array', function () {
describe('#indexOf()', function () {
it('should return -1 when not present', function () {
assert.equal(-1, [1, 2, 3].indexOf(4))
})
it('should return the index when present', function () {
assert.equal(-1, [1, 2, 3].indexOf(3))
})
})
describe('#every()', function () {
it('should return true when all items are satisfied', function () {
assert.equal(true, [1, 2, 3].every(item => !isNaN(item)))
})
})
})
describe('Srting', function () {
describe('#replace', function () {
it('should return a string that has been replaced', function () {
assert.equal('hey Hankle', 'hey Densy'.replace('Densy', 'Hankle'))
})
})
})
这里我们用 node 内置的 assert 模块来执行断言测试。下边是执行结果:
npm test
> simple-mocha@1.0.0 test /Documents/simple-mocha
> node mocha
Array
#indexOf()
✓ should return -1 when not present
× should return the index when present
#every()
✓ should return true when all items are satisfied
String
#replace
✓ should return a string that has been replaced
3 passing
1 failing
测试用例执行成功。附上完整的流程图:
四、结尾
如果你看到了这里,看完并看懂了上边实现 simple-mocha 的整个流程,那么很高兴地告诉你,你已经掌握了 Mocha 最核心的运行机理。simple-mocha 的整个实现过程其实就是 Mocha 实现的一个简化。而为了让大家在看完这篇文章后再去阅读 Mocha 源码时能够更快速地理解,我在简化和浅化 Mocha 实现流程的同时,也尽可能地保留了其中的一些命名和实现细节。有差别的地方,如执行测试用例环节,Mocha 源码构造了一个复杂的 Hook 机制来实现异步测试的依序执行,而我为了方便理解,用 async/await 来替代实现。当然这不是说 Mocha 实现得繁琐,在更加复杂的测试场景下,这套 Hook 机制是十分必要的。所以,这篇文章仅仅希望能够帮助我们攻克 Mocha 源码阅读的第一道陡坡,而要理解 Mocha 的精髓,光看这篇文章是远远不够的,还得深入阅读 Mocha 源码。
