Metadata-Version: 2.4
Name: chumicro-pytest-device-experimental
Version: 0.17.6
Summary: Pytest plugin that runs library functional tests on connected CircuitPython and MicroPython boards.
Project-URL: Homepage, https://github.com/ChuMicro/ChuMicro
Project-URL: Source, https://github.com/ChuMicro/ChuMicro/tree/main/workbench/pytest-device
Project-URL: Issues, https://github.com/ChuMicro/ChuMicro/issues
Author: ChuMicro
License-Expression: MIT
Keywords: circuitpython,device,embedded,hardware-testing,microcontroller,micropython,plugin,pytest
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: chumicro-deploy-experimental>=0.1.0
Requires-Dist: chumicro-workspace-experimental
Requires-Dist: cryptography>=42.0
Requires-Dist: msgpack>=1.0
Requires-Dist: pytest>=8.0
Description-Content-Type: text/markdown

# chumicro-pytest-device

<img src="https://raw.githubusercontent.com/ChuMicro/ChuMicro/main/support/docs/chumicro_tip.png"
align="left" width="64" style="margin-right: 16px; margin-bottom: 8px;">

**Pytest plugin that runs your tests on a real CircuitPython or MicroPython board.**

Drop tests under any `functional_tests/` directory and the plugin intercepts collection: stages your library + test source onto the connected board via `chumicro-deploy`, executes the test in the device runtime, parses the result back, and fails / passes the host-side pytest with the on-device outcome.  Reads device targets from your `devices.yml`; respects the same workspace conventions the rest of the ChuMicro tooling uses.

<br clear="left">

> Part of the [ChuMicro](https://github.com/ChuMicro/ChuMicro) family — small, focused Python libraries for microcontrollers and laptops. [Browse all workbench tools.](https://github.com/ChuMicro/ChuMicro/tree/main/workbench)
> This is a [workbench tool](https://github.com/ChuMicro/ChuMicro/blob/main/docs/contributing/workbench.md) — runs on your laptop, drives the boards over serial.

## Install

```bash
pip install chumicro-pytest-device-experimental
```

`chumicro-deploy` (and its `pyserial` / `mpremote` deps) come along.  Auto-registers via the `pytest11` entry point — no `pytest_plugins = [...]` line in `conftest.py` needed.  Native Windows isn't currently supported (the underlying `chumicro-deploy` raises `WindowsNotSupportedError`); WSL2 works.

## Quick example

A functional test reads like a normal unit test — it just runs on the board:

```python
# libraries/timing/functional_tests/test_heartbeat.py
import time
from chumicro_timing import Heartbeat
from chumicro_timing.ticks import ticks_ms


def test_heartbeat_fires_on_real_clock() -> None:
    heartbeat = Heartbeat(period_ms=10)
    deadline = time.monotonic() + 1.0
    fires = 0
    while time.monotonic() < deadline:
        if heartbeat.poll(ticks_ms()):
            fires += 1
    assert fires > 50
```

Run on every device targeted by your `devices.yml` defaults:

```bash
pytest libraries/timing/functional_tests --runtime both
```

The plugin discovers the board, stages `chumicro_timing/src/` + the test, executes on-device, parses the on-device pytest result back, and reports PASS / FAIL through host-side pytest.

## What's included

### Plugin modules

| Module | Purpose |
|---|---|
| `chumicro_pytest_device.plugin` | The pytest plugin entry-point module — collection interception, deploy orchestration, result reporting |
| `chumicro_pytest_device.result_parser` | Parses on-device test output back into `TestResult` objects |
| `chumicro_pytest_device.pr_summary` | Renders a markdown PR-summary block from captured run results — drop into a CI step |

### Pytest options

| Option | Effect |
|---|---|
| `--runtime {micropython,circuitpython,both}` | Override `defaults.ide_runtime` |
| `--micropython-device <id>` | Override `defaults.micropython` |
| `--circuitpython-device <id>` | Override `defaults.circuitpython` |
| `--deploy-mode {ram,flash}` | Override the per-device deploy mode |
| `--pr-summary` | Append a markdown summary block to stdout at end of session |
| `--pr-summary-command <text>` | The command that re-runs the failed tests, included in the summary |

## Where this fits

Depends on [`chumicro-deploy`](https://github.com/ChuMicro/ChuMicro/tree/main/workbench/deploy) for staging tests on a board.  Auto-registers via `pytest11`; reads `devices.yml` written by [`chumicro-workspace`](https://github.com/ChuMicro/ChuMicro/tree/main/workbench/workspace).

## Companions

| Workbench tool | Why you'd use it alongside |
|---|---|
| [`chumicro-deploy`](https://github.com/ChuMicro/ChuMicro/tree/main/workbench/deploy) | The transport layer the plugin uses for staging.  Useful directly when you want to drive a board outside of pytest |
| [`chumicro-repl`](https://github.com/ChuMicro/ChuMicro/tree/main/workbench/repl) | Tail a board's REPL after a deploy — handy for follow-up debugging when a functional test surprises you |
| [`chumicro-workspace`](https://github.com/ChuMicro/ChuMicro/tree/main/workbench/workspace) | The host CLI for project workspaces.  Reads the same `devices.yml` schema |

## Contributing

Working on `chumicro-pytest-device` itself?  Clone the [mono-repo](https://github.com/ChuMicro/ChuMicro) if you haven't already — the rest of the workflow assumes you're inside that workspace.

```bash
pip install -e .[test]
pytest tests/                  # host-side tests
```

No hardware-side functional tests for this package itself — its job is to drive consumer libraries' functional tests via `pytest libraries/<name>/functional_tests/` against a board registered in `devices.yml`.

## Find this library

- **PyPI:** [chumicro-pytest-device](https://pypi.org/project/chumicro-pytest-device/)
- **Source:** [workbench/pytest-device](https://github.com/ChuMicro/ChuMicro/tree/main/workbench/pytest-device)

## License

[MIT](https://github.com/ChuMicro/ChuMicro/blob/main/LICENSE)
