This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

rsttst makes your reStructuredText documentation testable.

In fact, this README file is testable and is used to test rsttst.

If your tests document how your system works, why not formally combine your tests and documentation into one?

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

Release History

Release History

0.3.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
rsttst-0.3.0-py2.py3-none-any.whl (11.1 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Sep 23, 2015
rsttst-0.3.0.tar.gz (7.6 kB) Copy SHA256 Checksum SHA256 Source Sep 23, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting