Combining data files: coverage combine

Often test suites are run under different conditions, for example, with different versions of Python, or dependencies, or on different operating systems. In these cases, you can collect coverage data for each test run, and then combine all the separate data files into one combined file for reporting.

The combine command reads a number of separate data files, matches the data by source file name, and writes a combined data file with all of the data.

Coverage normally writes data to a filed named ".coverage". The run --parallel-mode switch (or [run] parallel=True configuration option) tells coverage to expand the file name to include machine name, process id, and a random number so that every data file is distinct:

.coverage.Neds-MacBook-Pro.local.88335.316857
.coverage.Geometer.8044.799674

You can also define a new data file name with the [run] data_file option.

Once you have created a number of these files, you can copy them all to a single directory, and use the combine command to combine them into one .coverage data file:

$ coverage combine

You can also name directories or files to be combined on the command line:

$ coverage combine data1.dat windows_data_files/

Coverage.py will collect the data from those places and combine them. The current directory isn’t searched if you use command-line arguments. If you also want data from the current directory, name it explicitly on the command line.

When coverage.py combines data files, it looks for files named the same as the data file (defaulting to ".coverage"), with a dotted suffix. Here are some examples of data files that can be combined:

.coverage.machine1
.coverage.20120807T212300
.coverage.last_good_run.ok

An existing combined data file is ignored and re-written. If you want to use combine to accumulate results into the .coverage data file over a number of runs, use the --append switch on the combine command. This behavior was the default before version 4.2.

If any of the data files can’t be read, coverage.py will print a warning indicating the file and the problem.

The original input data files are deleted once they’ve been combined. If you want to keep those files, use the --keep command-line option.

$ coverage combine --help
Usage: coverage combine [options] <path1> <path2> ... <pathN>
Combine data from multiple coverage files. The combined results are written to
a single file representing the union of the data. The positional arguments are
data files or directories containing data files. If no paths are provided,
data files in the default data file's directory are combined.
Options:
 -a, --append Append data to the data file. Otherwise it starts
 clean each time.
 --data-file=DATAFILE Base name of the data files to operate on. Defaults to
 '.coverage'. [env: COVERAGE_FILE]
 --keep Keep original coverage files, otherwise they are
 deleted.
 -q, --quiet Don't print messages about what is happening.
 --debug=OPTS Debug options, separated by commas. [env:
 COVERAGE_DEBUG]
 -h, --help Get help on this command.
 --rcfile=RCFILE Specify configuration file. By default '.coveragerc',
 'setup.cfg', 'tox.ini', and 'pyproject.toml' are
 tried. [env: COVERAGE_RCFILE]