rsttst makes your reStructuredText testable
Project description
rsttst makes your reStructuredText documentation testable.
In fact, this README file is testable and is used to test rsttst.
Below is an example:
2 + 2 = 4
The title “2 + 2 = 4” becomes the test name after being converted to a Python friendly identifier (ie. 2_plus_2_equals_4).
The bash code in the below code block will be run…
echo '2 + 2' | bc
…and the resulting stdout will be compared to the following code block:
4
The test fails if stdout doesn’t match the block above.
Dotted notation
Sometimes you want to be flexible with the output you accept.
You can use “.” and the “:class: dotted” rst directive option to support this.
echo Date: $(date)
echo '\ok'
The below code block uses the “:class: dotted” option.
Date: ............................
\ok
Three dots match in a similiar way to what you’d expect for a regex pattern of “.+” to work:
echo '<NZ>'
echo $(date "+DATE: %Y-%m-%d%nTIME: %H:%M:%S")
The below code block uses the “:class: dotted” option.
<...>
DATE: ... TIME: ...
Generating tests
Under the hood rsttst generates Python code which is executable with py.test. Here’s how we generate the Python test code:
rsttst README.rst
cat test_readme.py | head -n 31
The resulting test code looks like the following:
# -*- coding: utf-8 -*-
import subprocess, rsttst.core
def run(cmd):
return subprocess.check_output(cmd, shell=True).decode('utf-8').strip()
def test_2_plus_2_equals_4():
output = run(u"""echo '2 + 2' | bc""")
assert output == u"""4"""
def test_dotted_notation():
output = run(u"""echo Date: $(date)
echo '\\ok'""")
expected = rsttst.core.Dotted(u"""Date: ............................
\\ok""")
cmp(output, expected)
expected = u"{0}".format(expected)
assert output == expected
def test_dotted_notation__2():
output = run(u"""echo '<NZ>'
echo $(date "+DATE: %Y-%m-%d%nTIME: %H:%M:%S")""")
expected = rsttst.core.Dotted(u"""<...>
DATE: ... TIME: ...""")
cmp(output, expected)
expected = u"{0}".format(expected)
assert output == expected
def test_generating_tests():
output = run(u"""rsttst README.rst
cat test_readme.py | head -n 31""")
Running the tests
You could probably use another test runner, but pytest works quite well:
py.test -k 'not test_running_the_tests' | grep -v seconds
Note: we had to exclude ‘test_running_the_tests’, otherwise it’s turtles all the way down.
============================= test session starts ==============================
platform ...
collected 5 items
test_readme.py ....
============= 1 tests deselected by '-knot test_running_the_tests' =============
Functionality
Right now rsttst only supports bash testing.
FAQ
Why does pytest throw an “IndexError: list index out of range” exception for my JSON tests?
Please upgrade to the latest version of pytest
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for rsttst-0.1.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0051cb05b8b1b41687e71d889e28c5dcb0d0918c516fe480a73bd6ac044738ce |
|
MD5 | 1dd76aef63dddac0c7cf08fc4538e0fc |
|
BLAKE2b-256 | 9192e44c102b2ba31b1cc7de0f7338cee2d55ed8368a2393d6fd12014a116be6 |