mpy-coverage 1.0.0__tar.gz

mpy_coverage-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --only-group dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run pytest tests/test_mpy_analysis.py -v
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv run mpy-coverage --help
+      - run: uv run python -m mpy_coverage --help
+
+  integration:
+    runs-on: ubuntu-latest
+    needs: test
+    container:
+      image: micropython/unix:coverage_v1.27.0
+    steps:
+      - uses: actions/checkout@v4
+      - run: apt-get update && apt-get install -y python3 python3-pip python3-venv curl
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run pytest tests/ -v
+        env:
+          MPY_BINARY: /usr/local/bin/micropython

mpy_coverage-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

mpy_coverage-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.mpy_coverage/
+*.mpy
+src/mpy_coverage/_version.py

mpy_coverage-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

mpy_coverage-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Leech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mpy_coverage-1.0.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: mpy-coverage
+Version: 1.0.0
+Summary: Code coverage for MicroPython
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: coverage
+Requires-Dist: mpy-cross

mpy_coverage-1.0.0/README.md

@@ -0,0 +1,293 @@
+# mpy-coverage
+
+Code coverage for MicroPython. Lightweight on-device tracer using `sys.settrace`, with host-side reporting via coverage.py.
+
+The tracer runs on the MicroPython target (unix port or real hardware with settrace enabled), collects executed line data, and exports it as JSON. The host-side tooling then merges multiple runs and generates reports using coverage.py's reporting engine.
+
+## Install
+
+```bash
+pip install mpy-coverage
+```
+
+This pulls in `coverage` and `mpy-cross` automatically.
+
+Dev setup:
+```bash
+git clone git@github.com:andrewleech/mpy-coverage.git
+cd mpy-coverage
+uv sync
+```
+
+## Getting started
+
+You need a micropython binary with settrace support. The quickest way is the unix coverage variant:
+```bash
+cd ports/unix && make submodules && make VARIANT=coverage
+```
+
+Say you have a module `myapp.py` and a test script `test_myapp.py` that exercises it:
+
+```python
+# test_myapp.py
+import myapp
+myapp.run()
+```
+
+Collect coverage and generate a report:
+```bash
+mpy-coverage run test_myapp.py --include myapp
+mpy-coverage report --show-missing
+```
+
+That's it. The run command executes `test_myapp.py` under micropython with the tracer active, saves a JSON data file to `.mpy_coverage/`, and the report command reads it and prints a coverage summary.
+
+For an HTML report instead:
+```bash
+mpy-coverage report --format html --output-dir htmlcov
+```
+
+If you have multiple test files, run each one separately then generate a single merged report:
+```bash
+mpy-coverage run tests/test_network.py --include myapp
+mpy-coverage run tests/test_storage.py --include myapp
+mpy-coverage report --show-missing
+```
+
+## Prerequisites
+
+For unix-port testing you need a micropython coverage build:
+```bash
+cd ports/unix && make submodules && make VARIANT=coverage
+```
+
+Hardware targets need firmware built with `MICROPY_PY_SYS_SETTRACE=1`.
+
+## Usage
+
+Each test run stores a timestamped JSON file, the report command merges all collected data.
+
+```bash
+mpy-coverage run test_foo.py --include myapp
+mpy-coverage run test_bar.py --include myapp
+mpy-coverage report --method auto --show-missing
+```
+
+micropython binary is auto-detected from PATH or `ports/unix/build-coverage/micropython` relative to CWD. Override with `--micropython`. Also works as `python -m mpy_coverage`.
+
+### Hardware
+
+```bash
+# deploys tracer to device automatically, runs test, collects data
+mpy-coverage run test_foo.py --device /dev/serial/by-id/usb-... --include myapp
+
+# skip deploy if mpy_coverage.py is already on device
+mpy-coverage run test_foo.py --device /dev/serial/by-id/usb-... --no-deploy --include myapp
+```
+
+### Multi-pass
+
+Run tests separately, accumulate data, generate one merged report:
+```bash
+mpy-coverage run tests/test_network.py --include myapp --branch
+mpy-coverage run tests/test_storage.py --include myapp --branch
+mpy-coverage run tests/test_ui.py --include myapp --branch
+mpy-coverage report --show-missing --format html --output-dir htmlcov
+```
+
+Data stored in `.mpy_coverage/` by default, override with `--data-dir`.
+
+Other subcommands: `mpy-coverage list` and `mpy-coverage clean`.
+
+## Branch coverage
+
+Branch coverage follows the same pattern as [coverage.py's branch measurement](https://coverage.readthedocs.io/en/latest/branch.html): `--branch` is a collection-time flag on `run`. Report commands auto-detect branch data from the JSON files and include branch columns when arc data is present — no `--branch` flag on `report`.
+
+```bash
+# Collect with arcs
+mpy-coverage run test_myapp.py --include myapp --branch
+
+# Report auto-detects arc data and shows branch columns
+mpy-coverage report --show-missing
+
+# Force line-only report even when arc data exists
+mpy-coverage report --show-missing --no-branch
+```
+
+This matches [coverage.py's CLI](https://coverage.readthedocs.io/en/latest/commands/cmd_run.html) where `coverage run --branch` enables collection and `coverage report` auto-detects.
+
+## Test map
+
+Show which tests cover which application files:
+
+```bash
+mpy-coverage run tests/test_a.py --include myapp
+mpy-coverage run tests/test_b.py --include myapp
+mpy-coverage test-map
+```
+
+Output:
+```
+app_file    , test
+myapp.py    , test_a
+myapp.py    , test_b
+helpers.py  , test_a
+```
+
+For per-line detail:
+```bash
+mpy-coverage test-map --line-detail
+```
+
+Output:
+```
+app_file    , line, test
+myapp.py    , 1   , test_a
+myapp.py    , 1   , test_b
+myapp.py    , 5   , test_a
+```
+
+Test names are extracted from `_metadata.test_script` in the JSON (set automatically by the CLI), with a filename-based fallback for older data files.
+
+## Report formats
+
+Reports are generated by coverage.py's reporting infrastructure, so all standard formats are supported with identical output to `coverage report`, `coverage html`, etc. See coverage.py's documentation for format details:
+
+| Format | Flag | Description | coverage.py docs |
+|--------|------|-------------|-----------------|
+| `text` | `--format text` (default) | Terminal summary table | [cmd_report](https://coverage.readthedocs.io/en/latest/commands/cmd_report.html) |
+| `html` | `--format html` | Annotated source HTML | [cmd_html](https://coverage.readthedocs.io/en/latest/commands/cmd_html.html) |
+| `json` | `--format json` | Machine-readable JSON | [cmd_json](https://coverage.readthedocs.io/en/latest/commands/cmd_json.html) |
+| `xml` | `--format xml` | Cobertura XML for CI | [cmd_xml](https://coverage.readthedocs.io/en/latest/commands/cmd_xml.html) |
+| `lcov` | `--format lcov` | LCOV tracefile | [cmd_lcov](https://coverage.readthedocs.io/en/latest/commands/cmd_lcov.html) |
+
+Multiple formats in one invocation: `--format text --format html --format xml`
+
+## Tracer API
+
+For direct use without the CLI wrapper. This runs on the MicroPython device, not the host.
+
+```python
+import mpy_coverage
+
+# Functional API
+mpy_coverage.start(
+    include=['mymod'],          # filename substring filters (list or None)
+    exclude=['test_'],          # exclusion filters (list or None)
+    collect_executable=False,   # collect co_lines data for pathway A
+    collect_arcs=False,         # collect line-to-line arcs for branch coverage
+)
+# ... run code under test ...
+mpy_coverage.stop()
+data = mpy_coverage.get_data()       # returns dict
+mpy_coverage.export_json('out.json') # to file
+mpy_coverage.export_json()           # to stdout with serial delimiters
+
+# Context manager
+with mpy_coverage.coverage(include=['mymod'], collect_arcs=True):
+    import mymod
+    mymod.run()
+```
+
+Filtering uses substring matching on filenames. The tracer always excludes itself.
+
+Then on the host:
+```bash
+python -m mpy_coverage.report coverage.json --method ast --show-missing
+```
+
+## Executable line detection
+
+Three methods for determining which lines are executable:
+
+| Method | Where | Pros | Cons |
+|--------|-------|------|------|
+| `co_lines` | On-device | No host tools needed, exact MicroPython view | Only sees called functions; uncalled code is invisible |
+| `ast` | Host CPython | Sees all code, same parser as coverage.py | May differ from MicroPython's view on edge cases |
+| `mpy` | Host via mpy-cross | Exact MicroPython bytecode view, sees all code | Requires mpy-cross binary |
+
+`--method auto` (default) tries `mpy` first, falling back through the others. For cross-validation against coverage.py, `ast` is preferred since both sides use the same `PythonParser` — any differences in executed/missing lines reveal genuine tracing divergences rather than parser disagreements.
+
+## JSON format
+
+```json
+{
+  "_metadata": {"test_script": "test_myapp"},
+  "executed": {"filename.py": [1, 3, 5, 7]},
+  "executable": {"filename.py": [1, 2, 3, 5, 6, 7, 10]},
+  "arcs": {"filename.py": [[-1, 1], [1, 3], [3, 5], [5, -1]]}
+}
+```
+
+- `executed`: always present — lines traced during execution
+- `executable`: only present when `collect_executable=True` (co_lines pathway)
+- `arcs`: only present when `collect_arcs=True` or `--branch` was used — each arc is `[from_line, to_line]` where negative values encode function entry/exit boundaries
+- `_metadata`: added by the CLI wrapper, includes `test_script` name for test-map
+
+## Data directory structure
+
+```
+.mpy_coverage/
+  20260213_143022_test_foo.json
+  20260213_143025_test_bar.json
+  20260213_143030_test_baz.json
+```
+
+Files are named `<YYYYMMDD_HHMMSS>_<script_basename>.json`. The `report` command merges all JSON files in the directory.
+
+## Divergences from CPython / coverage.py
+
+### `--branch` flag placement
+
+In [coverage.py](https://coverage.readthedocs.io/en/latest/branch.html), `--branch` is a collection-time flag on `coverage run`. Report commands auto-detect branch data. This toolchain follows the same pattern: `--branch` on `run`, auto-detect on `report`.
+
+### except-header line tracing
+
+MicroPython's compiler emits `set_source_line` for `except XxxError:` handler lines even when the exception path is not taken. CPython only traces these lines when the handler actually executes. This causes MicroPython to report one extra "executed" line per unvisited except clause.
+
+In practice this means slightly higher coverage percentages for code with exception handlers that aren't exercised. The cross-validation tests document this as a known divergence.
+
+### Arc encoding conventions
+
+MicroPython's settrace produces raw line-to-line transition arcs recorded as `(previous_line, current_line)` pairs. coverage.py's `PythonParser` models arcs using AST-derived conventions where negative line numbers encode function entry (`-co_firstlineno -> first_body_line`) and exit (`last_line -> -co_firstlineno`).
+
+These representations don't map 1:1:
+- Function entry arcs: MicroPython records `(def_line, first_body_line)` as a positive transition; coverage.py uses `(-def_line, first_body_line)`
+- While/for loop arcs: MicroPython's bytecode produces different line-to-line transitions than CPython's AST-derived arc model
+- Class body: Sequential class body lines appear as interior arcs in MicroPython but are modeled as entry arcs by coverage.py
+
+Line-level coverage metrics (statements, executed, missing, percentage) are unaffected by these arc convention differences and match exactly between the two systems when using the `ast` method.
+
+### Constructs not cross-validated
+
+The following constructs are excluded from cross-validation tests due to known irreconcilable differences:
+
+- **List comprehensions**: CPython 3.12+ creates a hidden function scope; MicroPython doesn't. This produces different arc structures.
+- **Generators/yield**: arc encoding for yield vs return differs between VMs.
+- **Boolean short-circuit**: arc differences within a single line aren't detectable at line-level coverage.
+
+## Cross-validation tests
+
+`test_coverage.py` includes 4 cross-validation trials that run the same code under both CPython+coverage.py and MicroPython+mpy_coverage, then compare metrics:
+
+| Trial | Description |
+|-------|-------------|
+| `trial_xval_lines` | Line coverage with partial path execution (~66%) |
+| `trial_xval_lines_full` | Line coverage with full path execution (100%) |
+| `trial_xval_branches` | Branch data collection with partial paths |
+| `trial_xval_branches_full` | Branch data collection with full paths |
+
+The test target (`test_target_xval.py`) covers: if/elif/else, for+break+else, while, try/except/finally, nested closures, classes with methods, ternary expressions, multiple return points, and with-statements.
+
+Run all trials:
+```bash
+MPY_BINARY=path/to/micropython python tests/test_coverage.py
+```
+
+## Limitations
+
+- settrace adds significant runtime overhead, not suitable for timing-sensitive code
+- `co_lines` method only reports executable lines for functions that were entered, uncalled functions are invisible rather than showing 0%
+- native/viper functions are not traced by settrace
+- large `_executed` dicts may hit memory limits on constrained devices
+- report integration overrides `Coverage._get_file_reporter()` which is a private API and may change across coverage.py versions

mpy_coverage-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mpy-coverage"
+dynamic = ["version"]
+description = "Code coverage for MicroPython"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = ["coverage", "mpy-cross"]
+
+[project.scripts]
+mpy-coverage = "mpy_coverage.cli:main"
+
+[dependency-groups]
+dev = ["pytest", "ruff"]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/mpy_coverage/_version.py"
+
+[tool.ruff]
+line-length = 99
+extend-exclude = ["src/mpy_coverage/_vendor"]

mpy_coverage-1.0.0/src/mpy_coverage/__init__.py

@@ -0,0 +1,14 @@
+"""MicroPython code coverage toolchain."""
+
+from mpy_coverage._version import __version__  # noqa: F401
+
+
+def __getattr__(name):
+    if name in ("merge_coverage_data", "run_report"):
+        from mpy_coverage.report import merge_coverage_data, run_report
+
+        return {"merge_coverage_data": merge_coverage_data, "run_report": run_report}[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["merge_coverage_data", "run_report", "__version__"]

mpy_coverage-1.0.0/src/mpy_coverage/__main__.py

@@ -0,0 +1,3 @@
+from mpy_coverage.cli import main
+
+main()