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
```
Add a comment
|
4 Answers
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).
5 Comments
bukzor
Updating the code may easily make the documentation examples wrong. The test suite should / will tell us when this happens.
bukzor
Completely sure is preferable to pretty sure.
ubomb
@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.
BlackJack
This doesn't work with Markdown's fenced code blocks because the ”closing fence” is considered as part of the output/result by the
doctest module and generates one failure per block.
Azat Ibrakov
just add an empty line before closing code block, it works
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...
Comments
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 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.
