https://github.com/boxed/pytest-readme

Make sure your README doesn't contain broken code
https://github.com/boxed/pytest-readme

Last synced: 14 days ago
JSON representation

Make sure your README doesn't contain broken code

• Host: GitHub
• URL: https://github.com/boxed/pytest-readme
• Owner: boxed
• License: bsd-3-clause
• Created: 2014-12-26T18:26:37.000Z (almost 10 years ago)
• Default Branch: master
• Last Pushed: 2022-09-02T06:28:27.000Z (about 2 years ago)
• Last Synced: 2024-10-04T15:55:20.482Z (about 1 month ago)
• Language: Python
• Homepage:
• Size: 3.91 KB
• Stars: 14
• Watchers: 3
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
pytest-readme

=============

A pytest plugin to pull out tests from your README.md into pytest automatically. This will make it easy to make sure your readme doesn't contain any errors.

Usage

=====

First `pip install pytest-readme`, then create a `conftest.py` file in the same directory as your README.md and put the following two lines in it:

```python

from pytest_readme import setup

setup()

```

pytest-readme will generate a file called `test_readme.py`, so you probably want to add that to your `.gitignore` file. 

pytest-readme supports two formats of tests: 

* doctest style

* pytest style

Note also that any blocks of python code without asserts is treated as pytest style test, so the code will be executed in a test. This is useful for at least checking that the functions exists, the parameters are in the correct order and that exceptions aren't raised.

Doctest style:

You will need to add the `doctest-modules` flag to your test runs. I recommend creating a pytest.ini file and having the following contents in it to make this automatic: 

```

[pytest]

addopts = --doctest-modules

```

Example:

```python

>>> 1 + 1

2

```

Pytest style example:

```python

assert 1 + 1 == 2

```

To avoid running a block of code from your readme, just make sure you have an empty line first. This won't show in in the markdown render and pytest-readme will skip the block.

Badge

=====

You can show that your README is tested with this badge: [![Examples tested with pytest-readme](http://img.shields.io/badge/readme-tested-brightgreen.svg)](https://github.com/boxed/pytest-readme) Copy paste the markdown syntax below:

    [![Examples tested with pytest-readme](http://img.shields.io/badge/readme-tested-brightgreen.svg)](https://github.com/boxed/pytest-readme)