JSON Output

The gcovr command can also generate a JSON output using the --json and --json-pretty options:

gcovr --json coverage.json

The --json-pretty option generates an indented JSON output that is easier to read.

If you just need a summary of the coverage information, similar to the tabulated text based output, you can use --json-summary instead (see JSON Summary Output).

Multiple JSON files can be merged into the coverage data with sum of lines and branches execution, see Merging Coverage Data.

See the JSON Format Reference for a description of the file format.

JSON Format Reference

The structure of the JSON input/output files is based on the GCC gcov JSON intermediate format, but with additional keys specific to gcovr. Field names use snake_case. Gcovr-specific fields are prefixed with gcovr/....

The GCC gcov JSON format is documented at https://gcc.gnu.org/onlinedocs/gcc/Invoking-Gcov.html#Invoking-Gcov.

The top level of the file looks like the following:

{
    "gcovr/format_version": version,
    "files": [file]
}
gcovr/format_version: string
A version number string for the gcovr JSON format. This is versioned independently from gcovr itself. Consumers of gcovr JSON reports should check that they are SemVer-compatible with the declared version. Gcovr itself will only consume input files that match the exact version.
files: list
An unordered list of file entries.

File entries

Each file entry contains coverage data for one source file:

{
    "file": filename,
    "lines": [line],
    "functions": [function]
}
file: string
Path to the source code file. If the source file is within the gcovr root directory, the path will be relative.
lines: list
An unordered list of line coverage entries.
functions: list
An unordered list of function entries.

Line entries

Each line entry contains coverage data for one line:

{
    "branches": [branch],
    "count": count,
    "line_number": line_number,
    "gcovr/excluded": excluded
    "gcovr/decision": decision
}
branches: list
A list of branch coverage entries.
count: int
How often this line was executed.
line_number: int
The 1-based line number to which this entry relates.
gcovr/excluded: boolean
True if coverage data for this line was explicitly excluded, in particular with Exclusion Markers. May be absent if false.
gcovr/decision: object
The decision entry for this line, if any. Absent if there is no decision to report. Requires that --decisions coverage analysis was enabled.

If there is no line entry for a source code line, it either means that the compiler did not generate any code for that line, or that gcovr ignored this coverage data due to heuristics.

The line entry should be interpreted as follows:

  • if gcovr/excluded is true, the line should not be included in coverage reports.
  • if count is 0, the line is uncovered
  • if count is nonzero, the line is covered

Changed in version NEXT: The gcovr/excluded field can be absent if false.

Changed in version NEXT: The gcovr/noncode field was removed. Instead of generating noncode entries, the entire line is skipped.

Branch entries

Each branch provides information about a branch on that line:

{
  "count": count,
  "fallthrough": fallthrough,
  "throw": throw
}

This exactly matches the GCC gcov format.

count: int
How often this branch was taken.
fallthrough: boolean
Whether this is the “fallthrough” branch.
throw: boolean
Whether this is an exception-only branch.

Decision entries

Each decision summarizes the line’s branch coverage data:

{
  "type": "uncheckable"
}

{
  "type": "conditional",
  "count_true": count_true,
  "count_false": count_false
}

{
  "type": "switch",
  "count": count
}
type: string
A tag/discriminator for the type of the decision.
type: “uncheckable”

Control flow was recognized on this line, but cannot be interpreted unambiguously.

No further fields.

type: “conditional”

This line represents simple control flow like an if or while.

count_true: int
How often the decision evaluated to “true”.
count_false: int
How often the decision evaluated to “false”.

Note that the true/false are heuristic guesses, and might also be inverted.

type: “switch”

This line is a switch-case.

count: int
How often this case was taken.

Function entries

Each function entry describes a line in the source file:

{
  "name": name,
  "lineno": lineno,
  "execution_count": count,
}
name: string
The name of the function, mangled or demangled depending on compiler version. May be incompatible with upstream GCC gcov JSON.
lineno: int
The line number (1-based) where this function was defined. Incompatible with GCC gcov JSON.
execution_count: int
How often this function was called.

JSON Summary Output

The --json-summary option output coverage summary in a machine-readable format for additional post processing. The format corresponds to the normal JSON output --json option, but without line-level details and with added aggregated statistics. The --json-summary-pretty option generates an indented JSON summary output that is easier to read. Consider the following command:

gcovr --json-summary-pretty --json-summary

This generates an indented JSON summary:

{
    "branch_covered": 1,
    "branch_percent": 50.0,
    "branch_total": 2,
    "files": [
        {
            "branch_covered": 1,
            "branch_percent": 50.0,
            "branch_total": 2,
            "filename": "example.cpp",
            "function_covered": 2,
            "function_percent": 100.0,
            "function_total": 2,
            "line_covered": 6,
            "line_percent": 85.7,
            "line_total": 7
        }
    ],
    "function_covered": 2,
    "function_percent": 100.0,
    "function_total": 2,
    "gcovr/summary_format_version": "0.5",
    "line_covered": 6,
    "line_percent": 85.7,
    "line_total": 7,
    "root": "."
}

New in version 5.0: Added --json-summary and --json-summary-pretty.

JSON Summary Format Reference

The summary format follows the general structure of the JSON Format Reference, but removes line-level information and adds aggregated statistics.

The top-level looks like:

{
  "gcovr/summary_format_version": version,
  "files: [file],
  "root": path,
  ...statistics
}
gcovr/summary_format_version: string
A version number string for the summary format. This is versioned independently from gcovr and the full JSON format. Consumers of gcovr JSON Summary reports should check that they are SemVer-compatible with the declared version.
files: list
Unordered list of file summary entries.
root: string
Path to the gcovr root directory, useful for reconstructing the absolute path of source files. This root path is relative to the output file, or to the current working directory if the report is printed to stdout.
…statistics
Project-level aggregated statistics. A NaN percentage (0/0) is reported as zero (0.0).

File summary entries

The file summary looks like:

{
  "filename": path,
  ...statistics
}
filename: string
Path to the source file, relative to the gcovr root directory.
…statistics
File-level aggregated statistics. A NaN percentage (0/0) is reported as null.

Summary statistics

The root and file summaries contain the following additional fields:

...
"branch_covered": ...,
"branch_total": ...,
"branch_percent": ...,

"line_covered": ...,
"line_total": ...,
"line_percent": ...,

"function_covered": ...,
"function_total": ...,
"function_percent": ...,
...

These fields can be described by the glob expression {branch,line,function}_{covered,total,percent}.

ELEMENT_covered: int
How many elements were covered or executed.
ELEMENT_total: int
How many elements there are in total.
ELEMENT_percent: float
Percentage of covered elements (covered/total) in the range 0 to 100. Note that the different contexts differ in their treatment of NaN values.