Skip to content

Instantly share code, notes, and snippets.

@twidi
Last active June 13, 2018 12:50
Show Gist options
  • Save twidi/9ce8ed0e8f92788031daaa78a765da75 to your computer and use it in GitHub Desktop.
Save twidi/9ce8ed0e8f92788031daaa78a765da75 to your computer and use it in GitHub Desktop.
Run tests for code example in README.rst (for django)
# Real name of this file is README.rst but I don't want github to render the rst ;)
Blah blah blah
.. testsetup::
# This prepare the django environment to run all the "testcode" in this file
# This is not visible in the rendered README
import os
os.environ['DJANGO_SETTINGS_MODULE'] = 'tests.settings'
import django
django.setup()
from django.db import connection
connection.creation.create_test_db(verbosity=0) # I use sqlite3 inmemory
.. testcode::
print('this python code will be tested because in `testcode`, but not displayed by github")
.. code-block::
print('this python code will be tested because in `code-block` which is replaced by `testcode` in our bash cript")
.. code:: python
print("this python code won't be tested because in `code`")
#!/usr/bin/env bash
# Run the tests included in the README.rst file
# Temporary directory to be used by sphinx
TMPDIR=.tmpdocs
# Will reset it before
rm -rf $TMPDIR
mkdir $TMPDIR
# We copy in it our file to be tested, replacing "code-block" by "testcode" (we need to do it
# because github don't display the "testcode" sections, but we want them to be displayed, and
# the tests only work on "testcode" sections.
sed -e 's/.. code-block:: python/.. testcode::/' README.rst > $TMPDIR/README.rst
# Create the smallest configuration file possible for shpinx
cat > $TMPDIR/conf.py <<EOF
extensions = ['sphinx.ext.doctest']
master_doc = 'README'
EOF
# And we can run the tests
sphinx-build -q -c $TMPDIR -b doctest $TMPDIR $TMPDIR $TMPDIR/README.rst
# Save the exit status to return it at the end
ERROR=$?
# Clean our mess
rm -fr $TMPDIR
# We want to tell the world if something was wrong
exit $ERROR
"""Test all examples from the README.rst file"""
import os
import subprocess
from unittest import TestCase
class ExamplesTestCase(TestCase):
"""Run all the example in the readme file"""
def test_all(self):
"""The example are tested by running sphinx with the doctest plugin
And it's done by running the ``test-readme.sh`` file, and in case of errors, the whole
output is displayed and the test marked as failed.
"""
test_file_dir = os.path.join(os.path.dirname(__file__), '..')
test_file_path = os.path.join(test_file_dir, 'test-readme.sh')
try:
subprocess.check_output(
[test_file_path],
shell=True,
stderr=subprocess.STDOUT,
cwd=test_file_dir,
)
except subprocess.CalledProcessError as exception:
try:
output = 'Error while running examples in README.rst :\n\n%s' % \
exception.output.decode('utf-8')
except Exception: # pylint: disable=broad-except
output = exception.output
self.fail(output)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment