JSON Report Format Documentation

The preferred reporting format for Purrpackage generates several file of JSON data containing the data, then renders these with static DHTML templates. This makes it a simple matter to produce new style and types of re-usable reports, just by copying static files. This document describes the JSON data produced by the report.

The JSON report produces two types of files.

coverageData.json
This contains coverage data in a tree down to the Class level, but not to the method level.
(package-name).(sourceFileName).json
This contains coverage data for a source file, down to the line level, and also contains text of that source file, if it is available.

Each type has a different format. They have in common a format for the hierarchy of summary coverage data.

Coverage Data JSON format

filesRead
Array of the names of files used in building the report. These are cobertura ".ser" files, plus the "purrpackage.db" properties file.
errorFree
Boolean value. If the readerErrors or calculatorErrors are not both empty, this will be false.
readerErrors
Array of human readable strings describing errors in reading the files produced by purrpackage, if there were any. This usually indicates some failure in the build process, perhaps from not writing the coverage data to an empty directory.
calculatorErrors
Array of readable strings describing unexpected problems in the data, if any. These errors usually indiciate some failure in the build process, especially mixing old and new coverage data in the same directory.
data
The root node of the coverage data tree for the project, see below.

Coverage Data Tree Node Format

The "data" property of the project data and the "coverage" property of the source files have the following format.

name
The key of this node in its parent's children map
displayName
The string best for display
orderingObject
Object that represents the most natural sorted order. Usually, it is just the value of "name" as a String. However, for Source Files, this is the base name, without the package. For methods, it is the number of the first line of the method.
childKeys
Iterable list of the keys in the "children" property, below, in the order prescribed by their orderingObject values.
children
Map (associative array) of child nodes. The keys are the elements of the childKeys array, and the values are tree node objects with properties like this one for elements of a finer granularity. The parent/child heirarchy is as follows:
  • Project
  • Package
  • Source File
  • Class (there maybe more than one class per Source File.)
  • Method
  • Line
The depths of the hierarchy in the "coverageData.json" file is from Project to Class. (Finer granularity in this format would require this file to be several megabytes for a project like the Apache Commons Math example.) The source file JSON "coverage" property contains data for that source file down to the lines.
lineCounts
A javascript object representing the line coverage for this node. The properties are:
valid
Number of valid lines
covered
Number of lines covered by all tests
missed
Number of lines missed by all tests
rate
Coverage rate for all tests as a double. Null if there are no valid lines.
samePackageCovered
Number of lines covered by tests in the same pacakge.
samePackageMissed
Number of lines missed by tests in the same pacakge.
samePackageRate
Coverage rate for tests in the same package. Null if there are not valid lines.
allCovered
Boolean value of "missed == 0," provided for convenience.
allSamePackageCovered
Boolean value of "samePackageMissed == 0," provided for convenience.
branchCounts
Like lineCounts, but representing branch coverage. The properties are the same as for lineCounts, but the values are with respect to branches rather than lines. Lines with no branches are not counted, of course.
elementCounts
A javascript object representing line and branch coverage together. Here, an "element" is a line or a branch on a line: a line with an if/then branch counts for 3 elements. The properties are the same as for lineCounts, but values are with respect to elements.
complexity
For Project, Package, and Source File data only, a measure of the complexity of the code. This is as in plain Cobertura reports, computed from JavaNCSS.
hits
For Line data only, the number of times this line was covered by all tests.
samePackageHits
As hits, but for tests in the same package.
branchHits
For Line data only, array of the number of times each branch on the line was hit by all tests.
samePackageBranchHits
As branchHits, but for tests in the same package.
sourceFileLineCount
For Source Files only, the number of lines that can be read from the source, or 0 if the source cannot be read. (This is useful for building a link to a method's position in a source file, and needs to be here in order to not have to load all the source files to build the links.)

Additional coverage node properties

The following properties are computed when the JSON files are loaded by coverageDataSupport.js.
parent
A link to the parent node in the coverage data tree.
allTestResults
If a coverage policy is successfully applied, the root, package, and source file nodes have this property that describes the results of applying the policy to this node. It is an associative array; at the moment, the only key is "main," reflecting the results of the main policy. The value of "allTestResults['main']" is an object with the following properties:
passedWithChildren()
Boolean valued function that is true if the node and all its descendents satisfied the policy
passed
Boolean: Did this node satisfy the policy, irrespective of its children?
allChildrenPassed
Boolean: Did every descendent node satisfy the policy?
results
Array of results of individual tests defined in the policy, in the order that they are defined by the "toHave(...)" clauses. Each has two properties: "passed" to indicate whether the clause was satisfied of not; and "exceptionRule" which is the index of the decisive "exceptIf" clause, 0 meaning the main clause, 1, the first exception, etc..

Source File JSON Format

A JSON file is generated for each Java Source file, with the following properties.

name
Name of the source file.
package
Package that this source file belongs to. Enables a link back to the main coverage data tree.
coverage
The coverage data tree node for this source file, with nodes as described above. The root is the source file's node, with class nodes below it (often 1, but more if there are inner classes), then method nodes, and line nodes.
lines
Associative array of line data for the source file. Key is string value of the line number. Value is an object with the following properties:
number
Integer line number.
html
Text of the line, with html annotations for Java key-words, comments, and string constants.
coverage
Line coverage data. This is provided only for source lines with coverage data. This is provided for convenience, since it is 3 generations removed from the source file's coverage root.
issue
There are a variety of issues in the build that can affect this object, which is contains a brief description of the short-coming, if there is one. For example, the coverage data may be computed, but perhaps the text of the source file cannot be found. It is possible that line data are not available. If there are issues, the lines property may not be populated even if the coverage property is.