How to unit test a sphinx/docutils directive

Question

I have created a Sphinx extension containing a directive.

Now I want to include unit tests before I start to refactor it. So using pytest I created a test file containing this fixture:

wide_format = __import__('sphinx-jsonschema.wide_format')

@pytest.fixture
def wideformat():
    state = Body(StateMachine(None, None))
    lineno = 1
    app = None

    return wide_format.WideFormat(state, lineno, app)

Which when used to create tests fails with errors complaining about the Nones in the instantiation of the StateMachine. I've tried to install some dummies, looked through docutil samples but can't find a working solution.

The problem is that State and StateMachine contain references to each other and I can't find a way to break that loop.

Answer 1

Docutils directives are tested in docutils/test/test_parser/test_rst/test_directives/. The main idea is to set up an rST parser and test it with rST input samples. A simple example is:

from docutils.frontend import get_default_settings
from docutils.parsers.rst import Parser
from docutils.utils import new_document

# setUp
parser = Parser()
settings = get_default_settings(Parser)  # required settings
settings.warning_stream = ''  # customize settings

# test data
source = '.. note:: this is an rST input sample'
expected = """\
<document source="test data">
    <note>
        <paragraph>
            this is an rST input sample
"""

# test case
document = new_document('test data', settings.copy())
parser.parse(source, document)
output = document.pformat()  # pseudoxml representation
assert output == expected