Babel 插件开发与单元测试覆盖度检查
单元测试，对于控制项目代码质量，保障线上版本的安全性和稳定性，节省回归测试成本和降低风险，都有着非常重要的作用。
代码覆盖度（Code coverage） 是衡量单元测试有效程度的一个重要指标。
代码覆盖度也是持续集成质量把控的一个环节。coveralls 是一个非常好的代码覆盖度检查平台，它可以和我们的 github repo 以及 Travis CI 无缝集成在一起。
结合 node-coveralls，有很多 Node.js 工具可以生成并发送代码覆盖度报告（Code coverage report），相关的工具包括 Mocha、Nodeunit、Blanke.js、JSCoverage、Poncho、Lab 等等。
在本文中，我将介绍如何使用 Babel 来开发插件，将 js 原文件编译为可被 Mocha 等工具生成代码覆盖度报告的测试文件。使用这个插件，可以让 coveralls 相关的工具很好地支持对最新的 ES6+ 代码生成代码覆盖度报告。
长文预警：本文内容很长，我先介绍怎样使用相关工具生成代码覆盖度数据，如果对 coveralls、lcov data 已经有所了解，可以跳过这一部分，直接看 Babel 插件的部分。
coveralls 与 lcov data
coveralls 接收一个 lcov data 文件，它用这个文件来计算代码覆盖度。一个 lcov data 文件格式看起来如下：
SF:file1.js
DA:3,1
DA:4,19
DA:5,19
DA:6,19
DA:9,1
……
DA:115,2
DA:118,2
DA:121,1
end_of_record
SF:file2.js
DA:1,1
DA:2,1
……
end_of_record
这个文件格式还是比较简单的， SF: 与 end_of_record 之间表示文件的覆盖数据，格式为： DA:行号,执行次数，例如：DA:5,19 表示代码的第 5 行被执行了 19 次。
有了 lcov data 文件，我们就可以通过 node-coveralls 与 Travis CI 集成，得到代码覆盖率结果。
.travis.yml 大致的内容如下：
language: node_js
node_js:
- "4"
sudo: false
script:
- "npm run test-cov"
after_script: "npm install coveralls && cd test-cov && cat coverage.lcov | ../node_modules/coveralls/bin/coveralls.js && cd .. && rm -rf ./test-cov && rm -rf ./test-app"
如果不知道怎样集成 Travis CI 与 coveralls，可以参考这篇文章。
lcov data 文件
前面说过有很多工具可以配合单元测试工具生成 lcov data 文件。
喜欢用 Mocha 来做单元测试的同学，可以简单用 mocha-lcov-reporter 来生成 lcov data 文件：
安装 mocha 和 mocha-lcov-reporter：
$ npm install mocha --save-dev
$ npm install mocha-lcov-reporter --save-dev
安装一个断言库，我喜欢用 chai：
$ npm install chai --save-dev
写一段 js 文件和测试代码：
//src/person.js
function Person(name){
this.name = name;
}
Person.prototype.greeting = function(){
console.log("hello", this.name);
}
module.exports = Person;
//test/test.js
var Person = require("../src/person");
var chai = require("chai");
describe("test", function(){
var expect = chai.expect;
it("person name", function(){
var akira = new Person("akira");
expect(akira.name).to.equal("akira");
});
});
执行测试：
$ mocha --reporter=mocha-lcov-reporter > coverage.lcov
你会发现，目录下多了一个 coverage.lcov 文件，这是我们需要的代码覆盖度文件，然而，这个文件的内容现在什么也没有。
这是正常的，并不是出了什么错误。因为 Mocha 只负责单元测试，并不会修改和监控 person.js 的原始代码，因此，为了让它正常生成有内容的 coverage.lcov 文件，我们可以对 person.js 文件做"一点"修改：
/*function Person(name){
this.name = name;
}
Person.prototype.greeting = function(){
console.log("hello", this.name);
}
module.exports = Person;*/
global._$jscoverage = global._$jscoverage || {};
_$jscoverage["person.js"] = {};
_$jscoverage["person.js"][1] = 0;
_$jscoverage["person.js"][2] = 0;
_$jscoverage["person.js"][5] = 0;
_$jscoverage["person.js"][6] = 0;
_$jscoverage["person.js"][9] = 0;
_$jscoverage["person.js"].source = [
"",
"function Person(name){",
"this.name = name;",
"}",
"",
"Person.prototype.greeting = function(){",
"console.log("hello", this.name);",
"}",
"",
"module.exports = Person;"
];
_$jscoverage["person.js"][1]++;
function Person(name){
_$jscoverage["person.js"][2]++;
this.name = name;
}
_$jscoverage["person.js"][5]++;
Person.prototype.greeting = function(){
_$jscoverage["person.js"][6]++;
console.log("hello", this.name);
}
_$jscoverage["person.js"][9]++;
module.exports = Person;
上面这个修改看上去有点吓人，只是短短的几行代码的 js 文件要被改成这样，如果内容多一些，靠手工改肯定不行的。不过别担心，这只是示范，这么做确实有效，现在我们可以看到 coverage.lcov 文件中有内容了：
SF:person.js
DA:1,1
DA:2,1
DA:5,1
DA:6,0
DA:9,1
end_of_record
注意 DA:6,0 说明第 6 行代码我们没有测试到，原始文件的第 6 行是：
console.log("hello", this.name);
我们看到它确实没有被测试到，因为它在 .greeting 方法里，而我们根本就没有测试这个方法。好吧，现在我们添加一下测试用例：
var Person = require("../src/person");
var chai = require("chai");
describe("test", function(){
var expect = chai.expect;
it("person name", function(){
var akira = new Person("akira");
expect(akira.name).to.equal("akira");
});
it("greeting", function(){
var akira = new Person("akira");
akira.greeting();
});
});
在上面的代码里，我们添加了一个测试用例，在这个测试用例中，我们只是调用了一下 .greeting( ) 方法，我们现在再测一次：
$ mocha --reporter=mocha-lcov-reporter > coverage.lcov
这次生成的代码覆盖率报告如下：
hello akira
SF:person.js
DA:1,1
DA:2,2
DA:5,1
DA:6,1
DA:9,1
end_of_record
我们看到，除了原始代码的第二行被执行了 2 次，其余各行都被执行了一次。第二行为什么是 2 次呢？因为第二行是：
this.name = name;
这行代码在构造函数内部，由于我们两个 case 分别构造了一个对象，因此这段代码就被执行了 2 次。
用 jscover 生成 lcov data
上面的例子是我们手写的，这么做在实际项目中当然不可行。一般情况下，我们采用一些工具来生成 lcov data，这里用 jscover 作为例子。
我们先来安装 jscover：
$ npm install jscover --save-dev
我们将 person.js 的代码还原成原始版本：
function Person(name){
this.name = name;
}
Person.prototype.greeting = function(){
console.log("hello", this.name);
}
module.exports = Person;
现在我们使用 jscover 来"编译" person.js 代码：
$ node_modules/jscover/bin/jscover src app
这样我们将 src/person.js 编译成了 app/person.js，它看起来像下面这个样子：
//app/person.js
/* ****** automatically generated by jscover - do not edit ******/
if (typeof _$jscoverage === "undefined") { _$jscoverage = {}; }
/* ****** end - do not edit ******/
//...
if (! this._$jscoverage) {
this._$jscoverage = {};
this._$jscoverage.branchData = {};
}
if (! _$jscoverage["person.js"]) {
_$jscoverage["person.js"] = [];
_$jscoverage["person.js"][1] = 0;
_$jscoverage["person.js"][2] = 0;
_$jscoverage["person.js"][5] = 0;
_$jscoverage["person.js"][6] = 0;
_$jscoverage["person.js"][9] = 0;
}
_$jscoverage["person.js"].source = ["function Person(name){"," this.name = name;","}","","Person.prototype.greeting = function(){"," console.log("hello", this.name);","}","","module.exports = Person;"];
_$jscoverage["person.js"][1]++;
function Person(name) {
_$jscoverage["person.js"][2]++;
this.name = name;
}
_$jscoverage["person.js"][5]++;
Person.prototype.greeting = function() {
_$jscoverage["person.js"][6]++;
console.log("hello", this.name);
};
_$jscoverage["person.js"][9]++;
module.exports = Person;
这样，我们就可以同样用 Mocha 来生成 lcov 了，只需要更改模块加载：
var Person = require("../app/person");
得到我们的 lcov data 文件：
hello akira
SF:person.js
DA:1,1
DA:2,2
DA:5,1
DA:6,1
DA:9,1
end_of_record
注意到控制台的输出也进入到 lcov data 文件中来了，这是因为 mocha-lcov-reporter 默认输出到控制台，我们实际上只是把控制台输出完全写到文件中来。在一般情况下，实际项目中不会有 console.log，所以我们可以忽略它。如果需要处理的话，也很简单，我们将文件生成完成之后，把 SF: 与 end_of_record 配对之外的所有的内容删去即可。
使用 ES6 与 Babel
我们现在继续实验，刚才 person.js 采用的是标准的 ES5 写法，我们现在将它改成 ES6 的版本：
"use strcit";
class Person{
constructor(name){
this.name = name;
}
greeting(){
console.log("hello", this.name);
}
}
module.exports = Person;
我们用 Babel 来编译一下：
$ babel --presets es2015 src --out-dir app
然后我们再使用 jscover 来生成代码覆盖报告：
$ node_modules/jscover/bin/jscover app app
$ mocha --reporter=mocha-lcov-reporter > coverage.lcov
hello akira
SF:person.js
DA:1,1
DA:2,1
DA:4,1
DA:6,1
DA:8,1
DA:9,1
DA:10,2
DA:12,2
DA:15,1
DA:18,1
DA:22,1
DA:25,1
end_of_record
麻烦来了，因为我们处理的是 Babel 编译过的代码，因此它不能如实反映出代码原始行号和测试覆盖率。那么我们能不能在 Babel 编译之前先用 jscover 处理它呢？
$ node_modules/jscover/bin/jscover src app
很遗憾，jscover 会报错，因为它不认为 ES6 语法是合法的：
Exception in thread "main" org.mozilla.javascript.EvaluatorException: missing ; before statement (person.js#3)
at org.mozilla.javascript.DefaultErrorReporter.runtimeError(DefaultErrorReporter.java:77)
at org.mozilla.javascript.DefaultErrorReporter.error(DefaultErrorReporter.java:64)
……
那么为了解决这个问题，我们可能得换一个更新的工具来代替 jscover，这个工具需要支持 ES6 语法。但是，我们好像还有一个办法----我们为何不直接使用 Babel？
AST 与 Babel 插件
我们可以直接用 Babel 开发一个插件来编译代码准备生成 lcov data。这么做有以下几个好处：
- 可以与 Babel 的 ES6 编译过程直接合并在一起，不用分两次编译
- lcov data 的数据直接关联原始文件，行号和内容信息不会丢失，覆盖率也能准确计算
- 不用担心语法问题，只要 Babel 能处理的语法都能正常运行，也可以和其他插件组合使用。
抽象语法树（AST）
计算机相关专业的同学应该对语法树的概念并不陌生，对非计算机专业的同学，这里举一个简单的例子稍微解释一下。
考虑表达式 x = (1 + 2) * 3，计算机语言处理的时候将它"展开"成一个树状结构：
上面是一个简单的表达式语法树，注意到它的节点有不同的类型，圆形表示数值常量，圆角矩形表示操作符，菱形表示变量符号。
这就是基本原理，程序的所有的部分都可以表达为树的一部分，AST 更复杂一些，它的树节点类型更多，每个树结构结点中包含更多的信息，但基本结构也大概类似于下面这样：
Babel 与 AST
Babel 6 拥有非常强大的插件 API，通过它，我们可以简单直接地操作文件的 AST。Babel 官方文档给出开发 Babel 插件的简单模板。
export default function ({types: t}) {
return {
visitor: {
Identifier(path) {
let name = path.node.name;
// reverse the name: JavaScript -> tpircSavaJ
path.node.name = name.split("").reverse().join("");
}
}
};
}
更加详细的文档在：babel-handbook （包含中文版）。
设计插件：transform-coverage
现在，我们可以着手来进行插件的设计与开发。在深入进行之前，希望对 AST 和 Babel 插件进一步了解的同学，可以花一点时间浏览一下：Babel 插件手册 以及 babel-types。如果不想深入了解也没关系，因为这个插件并不会用到太复杂的功能。
根据前面我们通过生成 lcov data 所了解的原理，我们的 transform-coverage 需要在代码的每一条_语句之前插入一个形式如 `$jscoverage[文件名][行号]++的**计数代码**。同时，我们需要在代码文件的最前面加上_$jscoverage` 初始化的相关代码。
所以，我们可以来设计插件的基本结构：
module.exports = function(babel) {
var t = babel.types;
var covVisitor = {
Statement: {
exit: function(path){
//插入计数代码到每一条语句（Statement）前面
}
},
Program: {
enter: function(path, state){
//初始化
},
exit: function(path, state){
//添加代码到文件最前面
}
}
};
return {visitor: covVisitor};
};
以上就是插件的基本逻辑结构，这里只用到 Statement 和 Program 两个 visitor，它们分别表示程序的语句节点和根节点。
这里解释一下 Babel 插件的 visitor 机制，每一个 visitor 属性对应一个 AST 节点类型，我们可以认为 Babel 插件遍历当前 AST 上每一个对应类型的节点（这有点像是 CSS 选择器，可以这么理解），因此：
Statement: {
exit: function(){
}
}
后序遍历当前 AST 中每一个类型为 Statement 的节点。
这里需要注意每一类节点可以有 enter 和 exit 两个遍历时机，分别对应前序遍历和后续遍历，前序遍历指的是当程序进入这个节点的时候对节点做处理，后续遍历则是当程序退出这个节点的时候对节点做处理。前序和后续两种方式，在节点有嵌套的时候会影响到节点处理的顺序：
if(a > 0){
b++;
return;
}
产生的 AST：
{
Statement:{
enter: function(path){
console.log(path.node.type);
}
}
}
前序遍历依次输出：IfStatement、ExpressionStatement、BlockStatment、ExpressionStatement、ReturnStatement
{
Statement:{
exit: function(path){
console.log(path.node.type);
}
}
}
后续遍历依次输出：ExpressionStatement、ExpressionStatement、ReturnStatement、BlockStatement、IfStatement
Program 是一个文件的 AST 的根节点，我们在 Program 的 enter 中完成一些内容的初始化，比如拿到当前的文件名（插入检查覆盖的代码的时候要用），初始化一个 Set，用来收集每个 Statement 所在的行号：
module.exports = function(babel) {
var t = babel.types,
coverageSet,
filename;
var covVisitor = {
Statement: {
exit: function(path){
//插入计数代码到每一条语句（Statement）前面
}
},
Program: {
enter: function(path, state){
//初始化
filename = state.file.opts.filename.replace(/^[^\/]*\//,"");
coverageSet = new Set();
},
exit: function(path, state){
//添加代码到文件最前面
}
}
};
return {visitor: covVisitor};
};
文件名 filename 可以通过 state.file.opts.filename 拿到，这个 filename 生成计数语句的时候要用到。需要注意的是我们要把 filename 最外层的目录去除（那一层目录在编译的时候改变了），以使得文件相对路径正确。
这里的 coverageSet 为什么用 Set 而不用一个 Array 是因为与 jscover 一致，我们仅为一行生成一个计数代码，如果该行有多个语句，我们应该忽略多余的语句，在这里使用 Set 判断起来更加高效率。我们看一下具体的 Statement 实现：
处理 Statement
Statement: {
exit: function(path){
//插入计数代码到每一条语句（Statement）前面
var loc = path.node.loc;
//不用处理 BlockStatement
if(loc && path.node.type !== "BlockStatement"){
var line = loc.start.line;
//有行号的代码、并且当前行没有被处理过
if(line && !coverageSet.has(line)){
//构造计数语句
var node = t.expressionStatement(t.updateExpression(
"++",
t.memberExpression(
t.memberExpression(
t.identifier(jscover),
t.stringLiteral(filename), true
),
t.numericLiteral(line), true
)
));
//记录当前处理的行号
coverageSet.add(line);
//将计数语句插入到当前节点的前面
path.insertBefore(node);
}
}
}
}
以上代码比较简单，最主要的内容是构造计数语句和将语句插入到当前节点之前。
构造计数语句是通过 babel-types 的方法进行的，这里没有什么特别有难度的东西，唯一需要注意的是注意它们的嵌套结构，写起来略微繁琐一些而已。
插入计数语句更简单了，path.insertBefore(node) 即可。
处理前置的代码
最后我们需要创建前面初始化 _$jscoverage 的代码，这里有几个步骤要做。我们将它放在 Program 的 exit 中，因为我们需要先拿到 coverageSet，知道有多少行代码被我们处理并添加了计数，我们要初始化这些计数器：
Program: {
enter: function(path, state){
//filename = state.file.opts.sourceFileName;
filename = state.file.opts.filename.replace(/^[^\/]*\//,"");
coverageSet = new Set();
},
exit: function(path, state){
……
//获得代码中的第一条语句
var body = path.get("body")[0];
//如果代码为空的，不做处理，返回
if(!body) return;
……
//初始化每个计数器
var lines = Array.from(coverageSet).sort((a,b)=>a-b);
for(var i = 0; i < lines.length; i++){
var node = t.expressionStatement(t.assignmentExpression(
"=",
t.memberExpression(
t.memberExpression(
t.identifier(jscover),
t.stringLiteral(filename),
true
),
t.numericLiteral(lines[i]),
true
),
t.numericLiteral(0)
));
body.insertBefore(node);
}
……
}
}
剩下的代码包括初始化 _$jscoverage、_$jscoverage[filename] 以及 _$jscoverage[filename].source：
Program: {
enter: function(path, state){
//filename = state.file.opts.sourceFileName;
filename = state.file.opts.filename.replace(/^[^\/]*\//,"");
coverageSet = new Set();
},
exit: function(path, state){
//获得代码中的第一条语句
var body = path.get("body")[0];
//如果代码为空的，不做处理，返回
if(!body) return;
//初始化 _$jscoverage
var node = t.expressionStatement(t.assignmentExpression(
"=",
t.memberExpression(
t.identifier("global"),
t.identifier(jscover)
),
t.logicalExpression(
"||",
t.memberExpression(
t.identifier("global"),
t.identifier(jscover)
),
t.objectExpression([])
)
));
body.insertBefore(node);
//初始化计数器列表
var node = t.expressionStatement(t.assignmentExpression(
"=",
t.memberExpression(
t.identifier(jscover),
t.stringLiteral(filename),
true
),
t.arrayExpression([])
));
body.insertBefore(node);
//初始化每个计数器
var lines = Array.from(coverageSet).sort((a,b)=>a-b);
for(var i = 0; i < lines.length; i++){
var node = t.expressionStatement(t.assignmentExpression(
"=",
t.memberExpression(
t.memberExpression(
t.identifier(jscover),
t.stringLiteral(filename),
true
),
t.numericLiteral(lines[i]),
true
),
t.numericLiteral(0)
));
body.insertBefore(node);
}
//初始化 _$jscoverage[filename].source
var codeList = state.file.code.split(/\n/g);
for(var i = 0; i < codeList.length; i++){
codeList[i] = t.stringLiteral(codeList[i] || "");
}
var node = t.expressionStatement(t.assignmentExpression(
"=",
t.memberExpression(
t.memberExpression(
t.identifier(jscover),
t.stringLiteral(filename),
true
),
t.identifier("source")
),
t.arrayExpression(codeList)
));
body.insertBefore(node);
}
}
最终，这个 Babel 插件的全部代码如下：
module.exports = function(babel) {
var t = babel.types,
coverageSet,
filename;
const jscover = "_$jscoverage";
var covVisitor = {
Statement: {
exit: function(path){
//insert `_$jscoverage[{filename}][{line}]++` before each statement
var loc = path.node.loc;
//ignore BlockStatement
if(loc && path.node.type !== "BlockStatement"){
var line = loc.start.line;
if(line && !coverageSet.has(line)){
var node = t.expressionStatement(t.updateExpression(
"++",
t.memberExpression(
t.memberExpression(
t.identifier(jscover),
t.stringLiteral(filename), true
),
t.numericLiteral(line), true
)
));
coverageSet.add(line);
path.insertBefore(node);
//path.traverse(covVisitor);
}
}
}
},
Program: {
enter: function(path, state){
//filename = state.file.opts.sourceFileName;
filename = state.file.opts.filename.replace(/^[^\/]*\//,"");
coverageSet = new Set();
},
exit: function(path, state){
var body = path.get("body")[0];
//exit if file is empty
if(!body) return;
//global._$jscoverage = global._$jscoverage || {}
var node = t.expressionStatement(t.assignmentExpression(
"=",
t.memberExpression(
t.identifier("global"),
t.identifier(jscover)
),
t.logicalExpression(
"||",
t.memberExpression(
t.identifier("global"),
t.identifier(jscover)
),
t.objectExpression([])
)
));
body.insertBefore(node);
//_$jscoverage[{$filename}] = [];
var node = t.expressionStatement(t.assignmentExpression(
"=",
t.memberExpression(
t.identifier(jscover),
t.stringLiteral(filename),
true
),
t.arrayExpression([])
));
body.insertBefore(node);
/**
_$jscoverage[{$filename}][{$line}] = 0;
...
*/
var lines = Array.from(coverageSet).sort((a,b)=>a-b);
for(var i = 0; i < lines.length; i++){
var node = t.expressionStatement(t.assignmentExpression(
"=",
t.memberExpression(
t.memberExpression(
t.identifier(jscover),
t.stringLiteral(filename),
true
),
t.numericLiteral(lines[i]),
true
),
t.numericLiteral(0)
));
body.insertBefore(node);
}
//_$jscoverage[{$filename}].source = [...codes]
var codeList = state.file.code.split(/\n/g);
for(var i = 0; i < codeList.length; i++){
codeList[i] = t.stringLiteral(codeList[i] || "");
}
var node = t.expressionStatement(t.assignmentExpression(
"=",
t.memberExpression(
t.memberExpression(
t.identifier(jscover),
t.stringLiteral(filename),
true
),
t.identifier("source")
),
t.arrayExpression(codeList)
));
body.insertBefore(node);
}
}
};
return {visitor: covVisitor};
};
如何使用
我将插件发布到 npm 上，你可以安装然后通过 babel 命令来使用：
安装 babel-cli 和 插件
$ npm install babel-cli --save-dev
$ npm install babel-preset-es2015 --save-dev
$ npm install babel-plugin-transform-coverage --save-dev
运行插件：
$ babel --presets es2015 --plugins transform-coverage src --out-dir app
以上代码将 ES6 编译成 ES5 并添加代码覆盖计数。
mocha --reporter=mocha-lcov-reporter > coverage.lcov
生成代码覆盖率报告：
hello akira
SF:person.js
DA:4,1
DA:5,2
DA:8,1
DA:12,1
end_of_record
结论
由于 jscover 不支持生成 ES6 的代码覆盖计数，我写了一个插件 babel-plugin-transform-coverage（GitHub 仓库地址），用它可以在编译 ES6 代码的同时生成需要的 lcov 代码覆盖计数。我们可以将它用在项目的测试脚本中：
关于代码覆盖率和开发 Babel 插件有任何问题，欢迎讨论。