Metadata-Version: 2.4
Name: pytest-readable
Version: 0.1.0
Summary: Pytest plugin that renders readable test specifications and exports documentation
Author: LuigiD5555
License: MIT License
        
        Copyright (c) 2026 LuigiD5555
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/LuigiD5555/pytest-readable
Project-URL: Repository, https://github.com/LuigiD5555/pytest-readable
Project-URL: Issues, https://github.com/LuigiD5555/pytest-readable/issues
Keywords: pytest,testing,documentation,plugin,specifications
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytest<10.0,>=9.0
Dynamic: license-file

# pytest-readable

![PyPI](https://img.shields.io/pypi/v/pytest-readable)
![Python](https://img.shields.io/pypi/pyversions/pytest-readable)
![License](https://img.shields.io/badge/license-MIT-blue)

`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

```bash
pip install pytest-readable
```

## Requirements

- Python 3.10+
- pytest 9.x

## Example

```python
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:

```bash
pytest --readable-detailed
```

Output:

```text
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:

```bash
pytest --readable
```

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

Readable detailed report:

```bash
pytest --readable-detailed
```

Detailed aliases:

```bash
pytest --readable --detailed
pytest --readable -d
```

Readable verbose report:

```bash
pytest --readable-verbose
```

Verbose aliases:

```bash
pytest --readable --verbose
pytest --readable -v
```

Export Markdown documentation:

```bash
pytest --readable --export=markdown
```

Export CSV documentation:

```bash
pytest --readable --export=csv
```

Set a custom output path:

```bash
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:

```bash
readable pytest tests/
```

Equivalent pytest invocation:

```bash
pytest --readable --color=yes tests/
```

Detailed readable output:

```bash
readable --detailed pytest tests/
readable pytest --detailed tests/
readable pytest -d tests/
```

Verbose readable output:

```bash
readable pytest -v tests/
readable pytest --verbose tests/
```

Mode equivalences:

```bash
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:

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

## Decorator Metadata

Document tests with explicit metadata:

```python
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:

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

## Language Support

Supported output languages:

- English
- Spanish

Example:

```bash
pytest --readable-lang=es
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.

## License

MIT License. See [LICENSE](LICENSE) for details.
