cfgcoverage 0.1

Structural coverage for Python

cfgcoverage

A Python package to analyze and verify structural coverage criteria for Python programs using control-flow graphs (CFGs).

V0.1 — This is a very early, highly experimental version.

Installation

pip install cfgcoverage

🚀 How to Use

Analyzes the file foo.py, builds its control-flow graphs, and stores the internal analysis data in foo.py.cfg.

python -m cfgcoverage foo.py

Executes foo.py with instrumentation and records covered blocks and edges.

python -m cfgcoverage --run foo.py

Executes foo.py with arguments ['bar', '1972'] and records the covered structural requirements.

python -m cfgcoverage --run --args "bar 1972" foo.py

Cumulatively runs foo.py and aggregates structural coverage results across multiple executions.

python -m cfgcoverage --run --append foo.py

Runs foo.py using the test cases defined in test_foo.py.
The --unittest argument can be used multiple times. The --append option is also supported here.

python -m cfgcoverage --unittest test_foo.py foo.py
python -m cfgcoverage --unittest tests/test_foo.py src/foo.py
python -m cfgcoverage --unittest test_a.py --unittest test_b.py foo.py

You can also use one or more --path <folder path> arguments to include additional folders in sys.path when executing unit tests. In this way, imports will also be searched in these folders.

python -m cfgcoverage --path src --unittest tests/test_foo.py src/foo.py
python -m cfgcoverage --path src --path tests --unittest tests/test_foo.py src/foo.py

Creates an HTML report in html/foo.py/index.html using the data stored in foo.py.cfg.

python -m cfgcoverage --html foo.py

## 🔍 Example

```bash
python3 -m cfgcoverage example.py

Example output:

Function: foo -- 1
Function: foo.inner -- 2
Run time: 0.00052

python3 -m cfgcoverage --run example.py

Example output:

Run time: 0.00071

python3 -m cfgcoverage --unittest test_example.py example.py

Example output:

.
----------------------------------------------------------------------
Ran 1 test in 0.000s

OK

Run time: 0.00110

python3 -m cfgcoverage --html example.py

Example output:

File generated at: html/example.py/index.html

📊 Coverage Criteria

The current HTML report includes the following criteria for each analyzed function:

• Blocks
• Edges
• Edge Pairs

📝 Notes

1. The analysis stores its internal data in a file named <source_file>.cfg.
2. HTML reports depend on previously generated .cfg data.
3. The tool analyzes functions and nested functions found in the source file.
4. When using --append, coverage data from previous executions is accumulated instead of replaced.
5. The HTML report is generated per source file and organized under the html/ folder.

👤 Author

Marcio Delamaro

📄 License

MIT

🤝 Contributions

Feel free to open issues or submit pull requests!