# pytest-json-report

> A pytest plugin to report test results as JSON files

- **URL**: https://www.freshcrate.ai/projects/pytest-json-report
- **Author**: numirias
- **Category**: Frameworks
- **Latest version**: `1.5.0` (2026-04-21)
- **License**: MIT
- **Source**: https://github.com/numirias/pytest-json-report
- **Language**: Python
- **GitHub**: 155 stars, 46 forks
- **Registry**: pypi (`pytest-json-report`)
- **Tags**: `pypi`

## Description

# Pytest JSON Report

[![CI](https://github.com/numirias/pytest-json-report/actions/workflows/main.yml/badge.svg)](https://github.com/numirias/pytest-json-report/actions/workflows/main.yml)
[![PyPI Version](https://img.shields.io/pypi/v/pytest-json-report.svg)](https://pypi.python.org/pypi/pytest-json-report)
[![Python Versions](https://img.shields.io/pypi/pyversions/pytest-json-report.svg)](https://pypi.python.org/pypi/pytest-json-report)

This pytest plugin creates test reports as JSON. This makes it easy to process test results in other applications.

It can report a summary, test details, captured output, logs, exception tracebacks and more. Additionally, you can use the available fixtures and hooks to [add metadata](#metadata) and [customize](#modifying-the-report) the report as you like.

## Table of contents

* [Installation](#installation)
* [Options](#options)
* [Usage](#usage)
   * [Metadata](#metadata)
   * [Modifying the report](#modifying-the-report)
   * [Direct invocation](#direct-invocation)
* [Format](#format)
   * [Summary](#summary)
   * [Environment](#environment)
   * [Collectors](#collectors)
   * [Tests](#tests)
   * [Test stage](#test-stage)
   * [Log](#log)
   * [Warnings](#warnings)
* [Related tools](#related-tools)

## Installation

```
pip install pytest-json-report --upgrade 
```

## Options

| Option | Description |
| --- | --- |
| `--json-report` | Create JSON report |
| `--json-report-file=PATH` | Target path to save JSON report (use "none" to not save the report) |
| `--json-report-summary` | Just create a summary without per-test details |
| `--json-report-omit=FIELD_LIST` | List of fields to omit in the report (choose from: `collectors`, `log`, `traceback`, `streams`, `warnings`, `keywords`) |
| `--json-report-indent=LEVEL` | Pretty-print JSON with specified indentation level |
| `--json-report-verbosity=LEVEL` | Set verbosity (default is value of `--verbosity`) |

## Usage

Just run pytest with `--json-report`. The report is saved in `.report.json` by default.

```bash
$ pytest --json-report -v tests/
$ cat .report.json
{"created": 1518371686.7981803, ... "tests":[{"nodeid": "test_foo.py", "outcome": "passed", ...}, ...]}
```

If you just need to know how many tests passed or failed and don't care about details, you can produce a summary only:

```bash
$ pytest --json-report --json-report-summary
```

Many fields can be omitted to keep the report size small. E.g., this will leave out keywords and stdout/stderr output:

```bash
$ pytest --json-report --json-report-omit keywords streams
```

If you don't like to have the report saved, you can specify `none` as the target file name:

```bash
$ pytest --json-report --json-report-file none
```

## Advanced usage

### Metadata

The easiest way to add your own metadata to a test item is by using the `json_metadata` [test fixture](https://docs.pytest.org/en/stable/fixture.html):

```python
def test_something(json_metadata):
    json_metadata['foo'] = {"some": "thing"}
    json_metadata['bar'] = 123
```

Or use the `pytest_json_runtest_metadata` [hook](https://docs.pytest.org/en/stable/reference.html#hooks) (in your `conftest.py`) to add metadata based on the current test run. The dict returned will automatically be merged with any existing metadata. E.g., this adds the start and stop time of each test's `call` stage:

```python
def pytest_json_runtest_metadata(item, call):
    if call.when != 'call':
        return {}
    return {'start': call.start, 'stop': call.stop}
```

Also, you could add metadata using [pytest-metadata's `--metadata` switch](https://github.com/pytest-dev/pytest-metadata#additional-metadata) which will add metadata to the report's `environment` section, but not to a specific test item. You need to make sure all your metadata is JSON-serializable.

### A note on hooks

If you're using a `pytest_json_*` hook although the plugin is not installed or not active (not using `--json-report`), pytest doesn't recognize it and may fail with an internal error like this:
```
INTERNALERROR> pluggy.manager.PluginValidationError: unknown hook 'pytest_json_runtest_metadata' in plugin <module 'conftest' from 'conftest.py'>
```
You can avoid this by declaring the hook implementation optional:

```python
import pytest
@pytest.hookimpl(optionalhook=True)
def pytest_json_runtest_metadata(item, call):
    ...
```

### Modifying the report

You can modify the entire report before it's saved by using the `pytest_json_modifyreport` hook.

Just implement the hook in your `conftest.py`, e.g.:

```python
def pytest_json_modifyreport(json_report):
    # Add a key to the report
    json_report['foo'] = 'bar'
    # Delete the summary from the report
    del json_report['summary']
```

After `pytest_sessionfinish`, the report object is also directly available to script via `config._json_report.report`. So you can access it using some built-in hook:

```python
def pytest_sessionfinish(session):
    report = session.config._json_report.report

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `1.5.0` | 2026-04-21 | Low | Imported from PyPI (1.5.0) |
| `v1.5.0` | 2022-03-15 | Low | ### Added - `deselected` count in summary  ### Changed - Supported Python versions are now 3.7 - 3.10  ### Fixed - #73: Fix `collected` count in summary (previously reported number of *selected* items) - #75: Handle xdist worker crashes gracefully |
| `v1.5.0` | 2022-03-15 | Low | ### Added - `deselected` count in summary  ### Changed - Supported Python versions are now 3.7 - 3.10  ### Fixed - #73: Fix `collected` count in summary (previously reported number of *selected* items) - #75: Handle xdist worker crashes gracefully |
| `v1.5.0` | 2022-03-15 | Low | ### Added - `deselected` count in summary  ### Changed - Supported Python versions are now 3.7 - 3.10  ### Fixed - #73: Fix `collected` count in summary (previously reported number of *selected* items) - #75: Handle xdist worker crashes gracefully |
| `v1.5.0` | 2022-03-15 | Low | ### Added - `deselected` count in summary  ### Changed - Supported Python versions are now 3.7 - 3.10  ### Fixed - #73: Fix `collected` count in summary (previously reported number of *selected* items) - #75: Handle xdist worker crashes gracefully |
| `v1.5.0` | 2022-03-15 | Low | ### Added - `deselected` count in summary  ### Changed - Supported Python versions are now 3.7 - 3.10  ### Fixed - #73: Fix `collected` count in summary (previously reported number of *selected* items) - #75: Handle xdist worker crashes gracefully |
| `v1.5.0` | 2022-03-15 | Low | ### Added - `deselected` count in summary  ### Changed - Supported Python versions are now 3.7 - 3.10  ### Fixed - #73: Fix `collected` count in summary (previously reported number of *selected* items) - #75: Handle xdist worker crashes gracefully |
| `v1.5.0` | 2022-03-15 | Low | ### Added - `deselected` count in summary  ### Changed - Supported Python versions are now 3.7 - 3.10  ### Fixed - #73: Fix `collected` count in summary (previously reported number of *selected* items) - #75: Handle xdist worker crashes gracefully |
| `v1.5.0` | 2022-03-15 | Low | ### Added - `deselected` count in summary  ### Changed - Supported Python versions are now 3.7 - 3.10  ### Fixed - #73: Fix `collected` count in summary (previously reported number of *selected* items) - #75: Handle xdist worker crashes gracefully |
| `v1.5.0` | 2022-03-15 | Low | ### Added - `deselected` count in summary  ### Changed - Supported Python versions are now 3.7 - 3.10  ### Fixed - #73: Fix `collected` count in summary (previously reported number of *selected* items) - #75: Handle xdist worker crashes gracefully |

## Citation

- HTML: https://www.freshcrate.ai/projects/pytest-json-report
- Markdown: https://www.freshcrate.ai/projects/pytest-json-report.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/pytest-json-report/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._