# pytest-discover

A plugin to write pytest collect output to either a [JSON](https://www.json.org/json-en.html) file or a [JSON lines](https://jsonlines.org/) file.

## Install

```bash
pip install pytest-discover
```

## Usage

- Use the `--collect-report` together with `--collect-only` option to collect tests and generate a JSON file:

```bash
pytest --collect-only --collect-report=collect.json
```

- Use the `--collect-log` together with `--collect-only` option to collect tests and generate a JSON lines file:

```bash
pytest --collect-only --collect-log=collect.jsonl
```

## Produced JSON output

The JSON file generated by `--collect-report` option follows the [DiscoveryResult JSON Schema](./schemas/discovery_result.json).

Python tools can also use the [`DiscoveryResult` dataclass](./src/pytest_discover/models/discovery_result.py) to parse the JSON file.


## Produced JSON Lines output

The JSON lines file generated by `--collect-log` option contains one JSON object per line. Each line is a JSON object that follows the [DiscoveryEvent JSON Schema](./schemas/discovery_event.json).

This schema is the union of the different events that can be emitted by the discovery process:

- [`SessionStart` JSON Schema](./schemas/session_start.json)
- [`WarningMessage` JSON Schema](./schemas/warning_message.json)
- [`ErrorMessage` JSON Schema](./schemas/error_message.json)
- [`CollectReport` JSON Schema](./schemas/collect_report.json)
- [`SessionFinish` JSON Schema](./schemas/session_finish.json)

Python tools can also use the [`DiscoveryEvent` dataclass](./src/pytest_discover/models/discovery_event.py) to parse the JSON lines file, as well as the differnt event classes:

- [`SessionStart` dataclass](./src/pytest_discover/models/session_start.py)
- [`WarningMessage` dataclass](./src/pytest_discover/models/warning_message.py)
- [`ErrorMessage` dataclass](./src/pytest_discover/models/error_message.py)
- [`CollectReport` dataclass](./src/pytest_discover/models/collect_report.py)
- [`SessionFinish` dataclass](./src/pytest_discover/models/session_finish.py)
- [`TestItem` dataclass](./src/pytest_discover/models/test_item.py)

> Note: The code generation task is automated using `rye run generate-models` project script.

## Alternatives

- [pytest-json-report](https://github.com/numirias/pytest-json-report): This plugin not only generates a JSON report with collected nodes, but also with test results. It is a more complete solution than `pytest-discover`. However, there is no JSON schema to validate the output, nor JSON lines output.

## Credits

- [pytest-report-log](https://github.com/pytest-dev/pytest-reportlog): This package was heavily inspired by the `report-log` plugin.
- [pytest-csv](https://github.com/nicoulaj/pytest-csv): The `pytest-csv` plugin was also a source of inspiration.
- [`datamodel-code-generator`](https://github.com/koxudaxi/datamodel-code-generator): The dataclasses generation from JSON schemas is performed using `datamodel-code-generator`.
- [rye](https://rye-up.com/): Project management is easy thanks to `rye`.
