rsttst 0.1.5

rsttst makes your reStructuredText testable

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

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