istanbuljs Coverage Data Dictionary

Overview

istanbuljs is the gold standard for JavaScript code coverage. This data dictionary describes the main structure and fields of coverage data.

Main Data Structures

1. Coverage Object

Top-level coverage data structure containing coverage information for all files.


{
  "path/to/file.js": {
    // FileCoverage object
  }
}

2. FileCoverage

Complete coverage data for a single file.

Field	Type	Description
`path`	string	Absolute path of the file
`statementMap`	Object	Statement mapping table
`fnMap`	Object	Function mapping table
`branchMap`	Object	Branch mapping table
`s`	Object	Statement execution count
`f`	Object	Function execution count
`b`	Object	Branch execution count

3. StatementMap

Describes the location information of each statement in the code.

Field	Type	Description
`start`	Location	Statement start position
`end`	Location	Statement end position

4. FunctionMap

Describes information about each function in the code.

Field	Type	Description
`name`	string	Function name (anonymous functions are “(anonymous_N)“)
`decl`	Location	Function declaration position
`loc`	Location	Function body position
`line`	number	Function declaration line number

5. BranchMap

Describes information about each branch in the code.

Field	Type	Description
`loc`	Location	Branch position
`type`	string	Branch type (if, switch, cond-expr, binary-expr)
`locations`	Array<Location>	All possible positions of branch conditions

6. Location

Describes a position in source code.

Field	Type	Description
`start`	Position	Start position
`end`	Position	End position

7. Position

Specific coordinates in source code.

Field	Type	Description
`line`	number	Line number (starts from 1)
`column`	number	Column number (starts from 0)

Counter Objects

8. Statement Counters

Records the execution count of each statement.


{
  "0": 5,    // Statement ID 0 executed 5 times
  "1": 0,    // Statement ID 1 not executed
  "2": 3     // Statement ID 2 executed 3 times
}

9. Function Counters

Records the call count of each function.


{
  "0": 2,    // Function ID 0 called 2 times
  "1": 0,    // Function ID 1 not called
  "2": 1     // Function ID 2 called 1 time
}

10. Branch Counters

Records the execution count of each branch condition.


{
  "0": [5, 2],    // Branch ID 0: true branch 5 times, false branch 2 times
  "1": [0, 3],    // Branch ID 1: true branch 0 times, false branch 3 times
  "2": [1, 1]     // Branch ID 2: both branches executed 1 time each
}

Branch Type Descriptions

Branch Types

Type	Description	Example
`if`	if statement	`if (condition) { ... }`
`switch`	switch statement	`switch (value) { case 1: ... }`
`cond-expr`	Ternary operator	`condition ? value1 : value2`
`binary-expr`	Logical operator	`a && b`, `x \|\| y`

Report Summary Data

11. Summary

Statistical summary for each coverage type.

Field	Type	Description
`total`	number	Total count
`covered`	number	Covered count
`skipped`	number	Skipped count
`pct`	number	Coverage percentage

12. Coverage Summary

Coverage summary for files or overall.

Field	Type	Description
`lines`	Summary	Line coverage summary
`functions`	Summary	Function coverage summary
`statements`	Summary	Statement coverage summary
`branches`	Summary	Branch coverage summary

实际示例

math.js 文件内容


function add(a, b) {
  return a + b;
}
 
function subtract(a, b) {
  if (a > b) {
    return a - b;
  } else {
    return b - a;
  }
}
 
function multiply(a, b) {
  return a * b;
}
 
function divide(a, b) {
  if (b === 0) {
    throw new Error('Division by zero');
  }
  return a / b;
}
 
module.exports = { add, subtract, multiply, divide };

完整的FileCoverage示例


{
  "path": "/project/src/math.js",
  "statementMap": {
    "0": {"start": {"line": 1, "column": 0}, "end": {"line": 1, "column": 25}},
    "1": {"start": {"line": 2, "column": 2}, "end": {"line": 2, "column": 13}},
    "2": {"start": {"line": 5, "column": 0}, "end": {"line": 5, "column": 30}},
    "3": {"start": {"line": 6, "column": 2}, "end": {"line": 6, "column": 25}},
    "4": {"start": {"line": 8, "column": 4}, "end": {"line": 8, "column": 15}},
    "5": {"start": {"line": 10, "column": 4}, "end": {"line": 10, "column": 15}},
    "6": {"start": {"line": 13, "column": 0}, "end": {"line": 13, "column": 25}},
    "7": {"start": {"line": 14, "column": 2}, "end": {"line": 14, "column": 13}},
    "8": {"start": {"line": 17, "column": 0}, "end": {"line": 17, "column": 30}},
    "9": {"start": {"line": 18, "column": 2}, "end": {"line": 18, "column": 25}},
    "10": {"start": {"line": 20, "column": 4}, "end": {"line": 20, "column": 15}},
    "11": {"start": {"line": 22, "column": 4}, "end": {"line": 22, "column": 15}},
    "12": {"start": {"line": 25, "column": 0}, "end": {"line": 25, "column": 25}}
  },
  "fnMap": {
    "0": {
      "name": "add",
      "decl": {"start": {"line": 1, "column": 9}, "end": {"line": 1, "column": 12}},
      "loc": {"start": {"line": 1, "column": 20}, "end": {"line": 3, "column": 1}},
      "line": 1
    },
    "1": {
      "name": "subtract",
      "decl": {"start": {"line": 5, "column": 9}, "end": {"line": 5, "column": 17}},
      "loc": {"start": {"line": 5, "column": 25}, "end": {"line": 12, "column": 1}},
      "line": 5
    },
    "2": {
      "name": "multiply",
      "decl": {"start": {"line": 13, "column": 9}, "end": {"line": 13, "column": 16}},
      "loc": {"start": {"line": 13, "column": 24}, "end": {"line": 15, "column": 1}},
      "line": 13
    },
    "3": {
      "name": "divide",
      "decl": {"start": {"line": 17, "column": 9}, "end": {"line": 17, "column": 15}},
      "loc": {"start": {"line": 17, "column": 23}, "end": {"line": 24, "column": 1}},
      "line": 17
    }
  },
  "branchMap": {
    "0": {
      "loc": {"start": {"line": 6, "column": 2}, "end": {"line": 6, "column": 25}},
      "type": "if",
      "locations": [
        {"start": {"line": 6, "column": 2}, "end": {"line": 6, "column": 25}},
        {"start": {"line": 6, "column": 2}, "end": {"line": 6, "column": 25}}
      ]
    },
    "1": {
      "loc": {"start": {"line": 18, "column": 2}, "end": {"line": 18, "column": 25}},
      "type": "if",
      "locations": [
        {"start": {"line": 18, "column": 2}, "end": {"line": 18, "column": 25}},
        {"start": {"line": 18, "column": 2}, "end": {"line": 18, "column": 25}}
      ]
    }
  },
  "s": {"0": 1, "1": 1, "2": 1, "3": 1, "4": 3, "5": 2, "6": 1, "7": 1, "8": 1, "9": 1, "10": 1, "11": 1, "12": 1},
  "f": {"0": 5, "1": 3, "2": 2, "3": 1},
  "b": {"0": [3, 2], "1": [1, 0]}
}