JSON Output

The gcovr command can generate 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 JSON Format merging.

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

Changed in version 8.0: Order of keys changed from alphabetical to logical.

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-14.1.0/gcc/Invoking-Gcov.html.

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.

The current version is:

“0.14”

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],
    "gcovr/data_sources": [data_source]
}

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 ordered list of line coverage entries.
functions: list: An ordered list of function entries.
gcovr/data_sources: list: A list of files from which the coverage object was populated. This entry is only available if --verbose is given.

Changed in version 8.3: The gcovr/data_sources is added.

Line entries

Each line entry contains coverage data for one line:

{
    "line_number": line_number,
    "function_name": function_name,
    "block_ids", [block_id],
    "count": count,
    "branches": [branch],
    "conditions", [condition]
    "gcovr/decision": decision,
    "calls": calls,
    "gcovr/md5": md5,
    "gcovr/excluded": excluded,
    "gcovr/data_sources": [data_source]
}

The ordering and merge key is (line_number, function_name).

line_number: int: The 1-based line number to which this entry relates.
function_name: str: Contains the name of the function to which the line belongs to. If gcov JSON format is used it is always the mangled name. If the legacy gcov text format is used it contains the demangled name if supported by gcov, else the mangled name. Can be missing for a line with an inlined statement.
block_ids: list: The list of block ids defined in this line.
count: int: How often this line was executed.
branches: list: An ordered list of branch coverage entries.
conditions: list: Only available if GCOV JSON format is used it contains an ordered list of branch coverage entries.
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.
calls: object: The call for this line, if any. Absent if there is no call to report.
gcovr/md5: str: The MD5 sum of the line.
gcovr/excluded: boolean: True if coverage data for this line was explicitly excluded, in particular with Exclusion Markers. May be absent if false.
gcovr/data_sources: list: A list of files from which the coverage object was populated. This entry is only available if --verbose is given.

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/data_sources is added.

Changed in version 8.0: The conditions is added.

Changed in version 8.0: The block_ids is added.

Changed in version 8.0: The function_name is added.

Changed in version 8.0: The gcovr/md5 is added.

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

Changed in version 6.0: 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,
  "source_block_id": number,
  "destination_block_id": number,
  "gcovr/data_sources": [data_source]
}

The ordering and merge key is (branch_number, source_block_id, destination_block_id).

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.
source_block_id: int: The source block of this branch.
destination_block_id: int: The destination block of this branch. Only available if gcov JSON format is used.
gcovr/data_sources: list: A list of files from which the coverage object was populated. This entry is only available if --verbose is given.

Changed in version NEXT: The gcovr/data_sources is added.

Added in version 8.0: Added destination_blockno field.

Added in version 8.3: Added source_block_id field.

Changed in version 8.3: Renamed destination_blockno to destination_block_id field.

Condition entries

Each condition provides information about a condition on that line:

{
  "count": count,
  "covered": covered,
  "not_covered_false": not_covered_false,
  "not_covered_true": not_covered_true,
  "gcovr/excluded": excluded,
  "gcovr/data_sources": [data_source]
}

The ordering and merge key is (condition_number, count).

This exactly matches the GCC gcov format.

count: int: Number of condition outcomes in this expression.
covered: int: Number of covered condition outcomes in this expression.
not_covered_false: list[int]: Terms, by index, not seen as false in this expression.
not_covered_true: list[int]: Terms, by index, not seen as true in this expression.
gcovr/excluded: boolean: True if coverage data for this line was explicitly excluded, in particular with Exclusion Markers. May be absent if false.
gcovr/data_sources: list: A list of files from which the coverage object was populated. This entry is only available if --verbose is given.

Changed in version NEXT: New gcovr/excluded field.

Changed in version NEXT: The gcovr/data_sources is added.

Decision entries

Each decision summarizes the line’s branch coverage data:

{
  "type": "uncheckable",
  "gcovr/data_sources": [data_source]
}

{
  "type": "conditional",
  "count_true": count_true,
  "count_false": count_false,
  "gcovr/data_sources": [data_source]
}

{
  "type": "switch",
  "count": count,
  "gcovr/data_sources": [data_source]
}

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.

gcovr/data_sources: list

A list of files from which the coverage object was populated. This entry is only available if --verbose is given.

Changed in version NEXT: The gcovr/data_sources is added.

Call entries

Each call provides information about a call on that line:

{
  "source_block_id": source_block_id,
  "destination_block_id": destination_block_id,
  "returned": returned,
  "gcovr/excluded": excluded,
  "gcovr/data_sources": [data_source]
}

The ordering and merge key is call_number.

This exactly matches the GCC gcov format.

source_block_id: int: The source block number of the call.
destination_block_id: int: Only available if gcov JSON format is used.
returned: int: How often this call returned, if the value is 0 the call is uncovered.
gcovr/excluded: boolean: True if coverage data for this line was explicitly excluded, in particular with Exclusion Markers. May be absent if false.
gcovr/data_sources: list: A list of files from which the coverage object was populated. This entry is only available if --verbose is given.

Changed in version NEXT: New returned field is replacing the field covered.

Changed in version NEXT: New gcovr/excluded field.

Changed in version NEXT: The gcovr/data_sources is added.

Function entries

Each function entry describes a line in the source file:

{
  "name": name,
  "demangled_name": demangled_name,
  "lineno": lineno,
  "execution_count": count,
  "branch_percent": percent,
  "pos": [
    "<start line>:<start column>",
    "<end line>:<end column>"
  ]
  "gcovr/excluded": excluded,
  "gcovr/data_sources": [data_source]
}

The ordering and merge key is function_name.

name: string: The mangled name of the function if present. Is missing if GCOV text format is used and GCOV tool supports demangled names.
demangled_name: string: The demangled name of the function if present. Is missing if GCOV text format is used and GCOV tool doesn’t support demangled names.
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.
branch_percent: float: The branch coverage in percent (0.0 to 100.0).
pos: list: A list with start and end position of function (1-based). Both entries are string with line and column separated by :. Only available if gcov JSON format is used.
gcovr/excluded: boolean: True if coverage data for this function was explicitly excluded, in particular with Exclusion Markers. May be absent if false.
gcovr/data_sources: list: A list of files from which the coverage object was populated. This entry is only available if --verbose is given.

if gcovr/excluded is true, the line should not be included in coverage reports.

Changed in version NEXT: The gcovr/data_sources is added.

Added in version 8.0: Added pos field.

Changed in version 8.0: The name is changed to contain the mangled name previous content is now available as demangled_name as it is in GCOV JSON format.

Removed in version 8.0: Removed returned_count field because missing in gcov JSON format.

Added in version 7.0: New returned_count and branch_percent field.

Added in version 6.0: New gcovr/excluded field.

JSON Format merging

You can merge coverage data from multiple runs with --json-add-tracefile.

For each run, generate JSON output:

...  # compile and run first test case
gcovr ... --json run-1.json
...  # compile and run second test case
gcovr ... --json run-2.json

Next, merge the json files and generate the desired report:

gcovr --json-add-tracefile run-1.json --json-add-tracefile run-2.json --html-details coverage.html

You can also use unix style wildcards to merge the json files without duplicating --json-add-tracefile. With this option you have to place your pathnames with wildcards in double quotation marks:

gcovr --json-add-tracefile "run-*.json" --html-details coverage.html

If you want to merge coverage reports generated in different --root directories you can use the --json-base to get the same root directory for all reports.

If you have same function names defined on different line the default behavior is to abort. With the --merge-mode-functions you can change this:

strict: Abort if same function is defined on a different line (old behavior).
merge-use-line-0: Allow same function on different lines, in this case use line 0.
merge-use-line-min: Allow same function on different lines, in this case the minimum line.
merge-use-line-max: Allow same function on different lines, in this case use maximum line.
separate: Allow same function on different lines. Instead of merging keep the functions separate.

Removed in version NEXT: Removed the option --merge-mode-conditions option.

Added in version 8.3: The --merge-mode-conditions option.

Added in version 6.0: The gcovr --json-base option. The gcovr --merge-mode-functions option.

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 example_json_summary.json

This generates an indented JSON summary:

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

Added 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.

The current version is:

“0.6”

files: list

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.