cmimport -- import utility

cmimport converts external code coverage reports into Coco's internal .csmes format.

The following are supported external sources of coverage data:

• Python: Coverage.py JSON reports

Syntax

cmimport -o <output_csmes_file> -t <execution_title> <source_specific_options>

Options

• -o <outfile> | --output=<outfile>: Output .csmes file name. (Required.)
• -t <execution-title> | --title=<execution-title>: Default execution title used when none is provided. (Required.)
• --python-source=<dir>: Root directory of the Python source code. Source content is read from here.
• --python-json=<file>: JSON report generated by Coverage.py.
• --help: Print help message.

Python Code Coverage

cmimport can be used to import data from Python projects that use Coverage.py. The testing framework pytest is commonly used in conjunction with Coverage.py to run tests and collect coverage data.

The workflow for generating coverage data for a Python project and importing it into Coco generally involves the following steps:

# 1) Generate coverage data using pytest and Coverage.py
pytest --cov=.

# 2) Generate a JSON report
coverage json

# 3) Import into Coco
cmimport \
    -o output.csmes \
    -t "default" \
    --python-source=/path/to/source \
    --python-json=coverage.json

The resulting output.csmes can be analyzed with Coco tools and merged with other coverage data from other programming languages supported by Coco.

Demo Project

For a complete example of using cmimport to import Python coverage data, see the sample project:

• Windows: <Coco installation>/demo_python_import
• Linux/Mac: <Coco installation>/samples/demo_python_import

Follow the instructions in the README.md file in that directory to run the demo.

Requirements for Python Coverage Import

To successfully import Python coverage data using cmimport, the following requirements must be met when generating the coverage report with Coverage.py:

• The JSON report format must be used. This can be produced by using the coverage json command. It can also be enabled in pytest by adding --cov-report=json option.
• Dynamic contexts must be activated to distinguish between different test runs. This can be done by setting the dynamic_context = test_function option in the .coveragerc configuration file. In pytest, this can also be enabled by adding --cov-context=test_function option.
• Contexts must be included in the JSON report. This can be enabled by setting show_contexts = True in the .coveragerc file.
• Branch coverage should be enabled to capture branch execution data. This can be done by setting branch = True in the .coveragerc file.

For best results, use Coverage.py version 7.10 or later, as earlier versions may lack some of the required features or have different report structures.

See the demo project for an example configuration.

Mapping Coverage.py Data to Coco

The following table summarizes how coverage data from Coverage.py maps to Coco's internal representation:

Due to differences in how Coverage.py and Coco define and measure statement and branch coverage, some discrepancies may occur in coverage percentages.

For more information on Coverage.py concepts, see the official documentation:

• Branch Coverage
• Contexts

Availability

cmimport is not available in Coco builds for the following legacy operating systems:

• CentOS 7
• Debian 7
• Debian 9