Code Coverage Tool Istanbul Getting Started Tutorial
When testing, we often care about whether all the code has been tested.
This indicator is called “code coverage” (code coverage). It has four measurement dimensions.
- Line coverage : Has every line been executed?
- Function coverage : Is every function called?
- Branch coverage : Is every if code block executed?
- Statement coverage : Is every statement executed?
Istanbul is a code coverage tool for JavaScript programs. This article introduces its usage.
This software is named after Istanbul, Turkey’s largest city, because Turkish carpets are world-famous, and carpets are used for covering.
1. Installation
Istanbul is an npm module, installation is very simple, just one line of command.
$ npm install -g istanbul
2. Coverage test
Let’s look at an example, how to use Istanbul. Below is the script file simple.js.
var a = 1; var b = 1; if ((a + b) > 2) { console.log('more than two'); }
Use the istanbul cover command to get the coverage.
$ istanbul cover simple.js ===== Coverage summary ===== Statements : 75% ( 3/4 ) Branches : 50% ( 1/2 ) Functions : 100% ( 0/0 ) Lines : 75% ( 3/4 ) =============================
The returned result shows that simple.js has 4 statements and 3 are executed; there are 2 branches, and 1 is executed; there are 0 functions, and 0 is called; there are 4 lines of code, and they are executed 3 lines.
This command also generates a coverage subdirectory. The coverage.json file contains the original coverage data. Coverage/lcov-report is a coverage report that can be opened in the browser. It contains detailed information and which codes are not. Covered to.
3. Coverage threshold
The perfect coverage is of course 100%, but it is difficult to achieve in reality. There needs to be a threshold to measure whether the coverage rate is up to standard.
The istanbul check-coverage command is used to set the threshold and check whether the current code meets the standard.
$ istanbul check-coverage --statement 90 ERROR: Coverage for statements (75%) does not meet global threshold (90%)
The above command sets the threshold of statement coverage to 90%, and the result is an error, because the actual coverage is only 75%.
In addition to the percentage threshold, we can also set the absolute threshold, for example, only one sentence is not covered.
$ istanbul check-coverage --statement -1
The above command uses negative numbers to indicate the absolute value threshold. In this way, the above example passes the coverage test and no more errors will be reported.
Percentage threshold and absolute value threshold can be used in combination.
$ istanbul check-coverage --statement -5 --branch -3 --function 100
The above command sets 3 coverage thresholds: 5 statements, 3 if code blocks, and 100% functions. Note that these three thresholds are “and” (and), as long as one does not meet the standard, an error will be reported.
Fourth, the combination with the test framework
In actual development, istanbul is always used in conjunction with the test framework. The following takes the commonly used Mocha framework as an example.
sqrt.js is a script that calculates the square root.
var My = { sqrt: function(x) { if (x < 0) throw new Error("负值没有平方根"); return Math.exp(Math.log(x)/2); } }; module.exports = My;
Its test script test.sqrt.js is placed in the test subdirectory.
var chai = require('chai'); var expect = chai.expect; var My = require('../sqrt.js'); describe("sqrt", function() { it("4的平方根应该等于2", function() { expect(My.sqrt(4)).to.equal(2); }); it("参数为负值时应该报错", function() { expect(function(){ My.sqrt(-1); }).to.throw("负值没有平方根"); }); });
Then, execute the following command to get the code coverage.
$ istanbul cover _mocha // or $ istanbul cover _mocha test/test.sqrt.js sqrt ✓ 4的平方根应该等于2 ✓ 参数为负值时应该报错 2 passing (7ms) ===== Coverage summary ===== Statements : 100% ( 5/5 ) Branches : 100% ( 2/2 ) Functions : 100% ( 1/1 ) Lines : 100% ( 4/4 ) =============================
In the above command, the istanbul cover command is followed by the _mocha command, and the preceding underscore cannot be omitted.
Because mocha and _mocha are two different commands , the former will create a new process to execute the test, and the latter will execute the test in the current process (that is, the process where istanbul is located). Only in this way will istanbul capture the coverage data. The same is true for other test frameworks, and tests must be performed in the same process.
If you want to pass in parameters to mocha, you can write it as follows.
$ istanbul cover _mocha -- tests/test.sqrt.js -R spec
In the above command, the part after the two connecting lines will be passed to Mocha as a parameter. If you don’t add those two conjunction lines, they will be treated as istanbul’s parameters (refer to links 1 , 2 ).
If you want to run Istanbul in your browser, you can refer to this article .
Five, ignore some codes
istanbul provides comment syntax , allowing certain codes to be excluded from coverage.
var object = parameter || /* istanbul ignore next */ {};
The above code specifies the default value (an empty object) for object. If, for various reasons, no test is written for the case where the object is an empty object, you can use comments to not count this case into the coverage rate. Note that the comment should be written after the “or” operator.
/* istanbul ignore if */ if (hardToReproduceError)) { return callback(hardToReproduceError); }
The if block of the code above will be ignored when calculating coverage.
(over)