15

I'd like to run the doctests from this file, and it's not clear to me out to accomplish it:

README.md:

# WELCOME!

This library is helpful and will help you in _many_ ways!

For example:

```
>>> import library
>>> library.helps()
True
```

(aside: can anyone help me get this to highlight as markdown?)

bukzor
  • 37,539
  • 11
  • 77
  • 111

4 Answers4

12

You can run doctest on your README on the command line using:

python -m doctest -v README.md

The -m parameter tells Python to run the following module as a script. When run as a script, the doctest module runs the doctest.testmod function on the following file. Lastly, the -v parameter makes doctest run in verbose mode; if it's turned off, doctest only produces output if at least one test fails (and will produce no output if everything is successful).

ubomb
  • 9,438
  • 2
  • 20
  • 26
  • 3
    Updating the code may easily make the documentation examples wrong. The test suite should / will tell us when this happens. – bukzor Apr 23 '14 at 16:52
  • 2
    Completely sure is preferable to pretty sure. – bukzor Apr 23 '14 at 17:42
  • 3
    @bukzor Hey, I just got a notification for this answer. I'm not sure why I was so snarky when I originally wrote it. Sorry about that. I just updated my answer to (hopefully) be more helpful/informative. – ubomb Jan 03 '18 at 01:31
6

As an alternative to doctest I wrote mkcodes, a script that pulls code blocks out of markdown files so they can be tested in a separate file.

Here's my actual test script using mkcodes:

mkcodes --github --output tests/docs/test_{name}.py docs
py.test tests
pyflakes tests
pep8 tests
Ryne Everett
  • 6,427
  • 3
  • 37
  • 49
0

Just found this phmdoctest package which seems to work fine with common python highlighting markdown:

Any text here for example...
```python
print(1+2)
```
sample output:
```
3
```

and a simple usage:

phmdoctest README.md --outfile tests/test_readme.py
python -m pytest tests -v

in the first line, you generate a new test file and later just run stand testing for whole your project...

Jirka
  • 1,126
  • 6
  • 25
0

I am the author/owner of phmdoctest mentioned above.

Edit the original question README.md and make sure the fence code blocks you want tested begin with

```python

Then run

phmutest README.md --replmode --log

phmutest

phmutest compared to phmdoctest has these new features:

  • Tests all FCBs in the Markdown file as a single example.
  • Runs tests internally with Python standard library test runners.
  • Caller can provide their own Python initialization and cleanup code.
  • Callable from a pytest test case.
  • A single example can extend across files.
tmarktaylor
  • 1
  • 2