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 28
The resulting test code looks like the following:
# -*- coding: utf-8 -*-
from rsttst.core import run, Dotted
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 = 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 = 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 28""")
Windows new lines
^M characters are automatically removed.
printf 'supports\012\015windows new lines'
supports
windows new lines
Ignore code-blocks
Sometimes you want to use a code-block without it being tested by rsttst.
You can use the “:class: ignore” directive to ignore this code-block:
.. code-block:: bash
:class: ignore
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 6 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.2.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 93ad6630d296400fc841018eeb9ed0776241a24a9ebecea6ce5f224690e1984b |
|
MD5 | a7cbda5189692b2841f1bae5a4893896 |
|
BLAKE2b-256 | ef18dd725521f81dbc49044089fbecfcd2930ce6a780b4d467b65d750ce62c2b |