Metadata-Version: 2.4
Name: cfgcoverage
Version: 0.1
Summary: Structural coverage for Python
Author: Delamaro
Author-email: Delamaro <delamaro@icmc.usp.br>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: license-file

# 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

```bash
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`.

```bash
python -m cfgcoverage foo.py
```

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

```bash
python -m cfgcoverage --run foo.py
```

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

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

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

```bash
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.

```bash
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.

```bash
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`.

```bash
python -m cfgcoverage --html foo.py
```

```

## 🔍 Example

```bash
python3 -m cfgcoverage example.py
```

Example output:

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

```bash
python3 -m cfgcoverage --run example.py
```

Example output:

```text
Run time: 0.00071
```

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

Example output:

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

OK

Run time: 0.00110
```

```bash
python3 -m cfgcoverage --html example.py
```

Example output:

```text
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!
