Skip to main content

Utilities for testing Sphinx extensions

Project description

Quickstart

If you have a directory containing a sphinx project, test that it builds with something like:

class TestMyProject(SourcesBuilder):

    page_source_template = 'path/to/sphinx_dir'

    def test_basic_build(self):
        # Get doctree for page "a_page.rst"
        doctree = self.get_doctree('a_page')
        # Assert stuff about doctree version of page
        html = self.get_built_file('a_page.html')
        # Assert stuff about html version of page

You can try adding other page content by using the rst_sources dictionary:

class TestChangedProject(SourcesBuilder):

    page_source_template = 'path/to/sphinx_dir'
    rst_sources = {'a_page': """Replacement text for page""",
                   'b_page': """An entirely new page"""}

    def test_basic_build(self):
        a_doctree = self.get_doctree('a_page')
        b_doctree = self.get_doctree('b_page')
        # Your tests for the new page content here

Set the text of the conf.py file with the conf_source attribute:

class TestConfeddProject(SourcesBuilder):

    page_source_template = 'path/to/sphinx_dir'
    rst_sources = {'a_page': """Replacement text for page""",
                   'b_page': """An entirely new page"""}
    conf_source = """ # This overwrites existing conf.py """

    def test_basic_build(self):
        a_doctree = self.get_doctree('a_page')
        b_doctree = self.get_doctree('b_page')
        # Your tests for the new page content here

You don’t need to set page_source_template; if you don’t, you start with a fresh project, where the only pages are the ones you specify in rst_sources.

class TestFreshProject(SourcesBuilder):

    rst_sources = {'a_page': """A new page""",
                   'b_page': """Another new page"""}
    conf_source = """ # Stuff for the conf.py file """

    def test_basic_build(self):
        a_doctree = self.get_doctree('a_page')
        b_doctree = self.get_doctree('b_page')
        # Your tests for the new page content here

See the tests for examples of using Sphinxtesters for testing builds of Sphinx projects.

Installation

pip install sphinxtesters

Code

See https://github.com/matthew-brett/sphinxtesters

Released under the BSD two-clause license - see the file LICENSE in the source distribution.

travis-ci kindly tests the code automatically under Python versions 2.7, and 3.3 through 3.6.

The latest released version is at https://pypi.python.org/pypi/sphinxtesters

Tests

  • Install sphinxtesters

  • Install the pytest testing framework:

    pip install pytest
    
  • Run the tests with:

    pytest sphinxtesters
    

Support

Please put up issues on the sphinxtesters issue tracker.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sphinxtesters, version 0.2
Filename, size File type Python version Upload date Hashes
Filename, size sphinxtesters-0.2.tar.gz (28.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page