pytest-markdown-summary

A pytest plugin that generates a Markdown summary table of your test results. Useful for CI pipelines, pull request comments, and automated reporting.

Features

• Generates a clean Markdown table with per-test or per-file result breakdown
• Tracks all outcome types: passed, failed, errored, skipped, xfail, and xpass
• Groups parametrized test variants into a single row
• Includes a TOTAL summary row with aggregated counts
• Automatically creates output directories if they don't exist
• Zero configuration needed beyond specifying the output file path

Installation

pip install pytest-markdown-summary

The plugin supports:

• Python: >=3.11
• pytest: >=7,<10

Usage

The plugin is activated by providing the --markdown-summary-file option to pytest:

pytest --markdown-summary-file=report.md

Command-Line Options

Per-File Grouping (Default)

By default, test results are grouped by file:

pytest --markdown-summary-file=report.md

Per-Test Grouping

To track each test function individually:

pytest --markdown-summary-file=report.md --markdown-summary-use-test-names

Output Example

Per-File Mode (Default)

pytest --markdown-summary-file=report.md

Per-Test Mode

pytest --markdown-summary-file=report.md --markdown-summary-use-test-names

Note: Parametrized tests (e.g., @pytest.mark.parametrize) are automatically grouped into a single row under the base test name.

CI Integration

GitHub Actions

Use the generated Markdown file in GitHub Actions job summaries:

- name: Run tests
  run: pytest --markdown-summary-file=report.md

- name: Add summary to job
  if: always()
  run: cat report.md >> $GITHUB_STEP_SUMMARY

As a PR Comment

You can also post the report as a pull request comment using actions like marocchino/sticky-pull-request-comment:

- name: Run tests
  run: pytest --markdown-summary-file=report.md

- name: Comment on PR
  if: always() && github.event_name == 'pull_request'
  uses: marocchino/sticky-pull-request-comment@v2
  with:
    path: report.md

Contribution

Contributions are always welcome! If you have an idea, it's best to float it by me before working on it to ensure no effort is wasted. If there's already an open issue for it, knock yourself out.

License