pytest-readable 0.1.0

Pytest plugin that renders readable test specifications and exports documentation

pytest-readable

pytest-readable is a pytest plugin that renders collected tests as human-readable specifications and Markdown or CSV documentation.

It makes explicitly described tests easier to read in the terminal and easier to export as documentation.

Installation

pip install pytest-readable

Requirements

• Python 3.10+
• pytest 9.x

Example

from pytest_readable import readable


@readable(
    intention="User login succeeds with valid credentials",
    steps=[
        "Create a user",
        "Attempt login with the correct password",
    ],
    criteria=[
        "Login succeeds",
        "A session token is returned",
    ],
)
def test_user_login():
    ...

Run:

pytest --readable-detailed

Output:

Readable summary

- Total: 1
- collected: 1

Detailed list

- [unknown] tests/test_auth.py::test_user_login
    What it tests: User login succeeds with valid credentials
    Steps:
      1. Create a user
      2. Attempt login with the correct password
    Pass conditions:
      1. Login succeeds
      2. A session token is returned

Final summary: total=1, passed=0, failed=0, skipped=0

Quick Start

Readable terminal summary:

pytest --readable

This prints a summarized readable report without pytest's native header or footer noise.

Readable detailed report:

pytest --readable-detailed

Detailed aliases:

pytest --readable --detailed
pytest --readable -d

Readable verbose report:

pytest --readable-verbose

Verbose aliases:

pytest --readable --verbose
pytest --readable -v

Export Markdown documentation:

pytest --readable --export=markdown

Export CSV documentation:

pytest --readable --export=csv

Set a custom output path:

pytest --readable --export=markdown --readable-out=docs/tests-readable.md

Design Philosophy

pytest-readable is intentionally non-inferential.

The plugin does not attempt to interpret test code, infer behavior, or generate missing semantics. It renders only the metadata that the author explicitly declares.

This keeps the plugin:

• deterministic
• framework-agnostic
• compatible with both human-written and AI-generated tests

pytest-readable does not try to make tests better. It makes explicitly described tests more readable.

Scope

This project focuses on:

• readable test intention
• explicit steps
• explicit pass conditions
• pytest-aware rendering
• Markdown and CSV export

It does not aim to become:

• a TDD framework
• a test generator
• an AI interpreter
• a writable test authoring tool

CLI Helper

The package also installs a small readable helper command that forwards to pytest with readable defaults:

readable pytest tests/

Equivalent pytest invocation:

pytest --readable --color=yes tests/

Detailed readable output:

readable --detailed pytest tests/
readable pytest --detailed tests/
readable pytest -d tests/

Verbose readable output:

readable pytest -v tests/
readable pytest --verbose tests/

Mode equivalences:

readable pytest               -> pytest --readable
readable pytest -d           -> pytest --readable -d
readable pytest --detailed   -> pytest --readable --detailed
readable pytest -v           -> pytest --readable -v
readable pytest --verbose    -> pytest --readable --verbose

Note: -d works as a readable shorthand when used together with --readable, even though pytest --help lists the long-form detailed options.

Helper-specific commands:

readable --help
readable --find-missing
readable --find-missing --tests-root=tests

Decorator Metadata

Document tests with explicit metadata:

from pytest_readable import readable


@readable(
    intention="Search returns matching results",
    steps=[
        "User enters a search query",
        "The system queries the search index",
    ],
    criteria=[
        "The response status is 200",
        "The results contain matching items",
    ],
)
def test_search():
    ...

The preferred metadata shape is:

@readable(
    intention="What the test validates",
    steps=["Action performed"],
    criteria=["Expected observable outcome"],
)

Language Support

Supported output languages:

• English
• Spanish

Example:

pytest --readable-lang=es

Contributing

See CONTRIBUTING.md for contribution guidelines.

Changelog

See CHANGELOG.md for release history.

License

MIT License. See LICENSE for details.