pytest plugin

Note

This plugin disables pytest’s standard doctest plugin.

The pytest plugin is built on top of the Doctest w/ docutils module, which is in turn compatible with doctest.

Using fixtures

Normal pytest convention apply, a visible conftest.py must be available for the file being tested.

This requires a understanding of confest.py - in the same way pytest’s vanilla doctest plugin does.

You know your project’s package structure best, the follow just serve as examples of new places conftest.py will be needed:

Example: Root-level README

In other words, if you want to test a project’s README.md in the project root, a conftest.py would be needed at the root-level. This also has the benefit of reducing duplication:

conftest.py
    # content of conftest.py
    import pytest

    @pytest.fixture
    def username():
        return 'username'

README.rst
    Our project
    -----------

    .. doctest::

        # content of tests/test_something.py
        def test_username(username):
            assert username == 'username'

Now you can do:

$ pytest README.rst

Examples: docs/

Let’s assume .md and .rst files in docs/, this means you need to import conftest.py

docs/
	conftest.py
		# import conftest of project
		import pytest

		@pytest.fixture
		def username():
			return 'username'

	usage.rst
		Our project
		-----------

		.. doctest::

			# content of tests/test_something.py
			def test_username(username):
				assert username == 'username'

Now you can do:

$ pytest docs/

File support

reStructuredText (.rst)

$ pytest README.rst

$ pytest docs/

Markdown (.md)

If you install myst-parser, doctest will run on .md files.

$ pytest README.md

$ pytest docs/

Scanning python files

You can retain pytest’s standard doctest plugin of running doctests in .py by passing --doctest-docutils-modules:

$ py.test src/ --doctest-docutils-modules

You can disable it via --no-doctest-docutils-modules:

$ py.test src/ --no-doctest-docutils-modules

Case examples

• libtmux (source):

  • Documentation w/ docutils:

    • README.md (raw)

      Note: pytest README.md requires you have a conftest.py directly in the project root

    • docs/topics/traversal.md (raw)

  • Configuration:

    • Doctests support pytest fixtures through doctest_namespace

      See add_doctest_fixtures() in src/libtmux/conftest.py

API

pytest_doctest_docutils

pytest plugin for doctest w/ reStructuredText and markdown

See also

• http://www.sphinx-doc.org/en/stable/ext/doctest.html

• https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/doctest.py

This is a derivative of my PR https://github.com/thisch/pytest-sphinx/pull/38 to pytest-sphinx (BSD 3-clause), 2022-09-03.

pytest_doctest_docutils.pytest_addoption(parser)

Return type:

None

pytest_doctest_docutils.pytest_configure(config)

Disable pytest.doctest to prevent running tests twice.

Todo: Find a way to make these plugins cooperate without collecting twice.

Return type:

None

pytest_doctest_docutils.pytest_unconfigure()

Return type:

None

pytest_doctest_docutils.pytest_collect_file(file_path, parent)

Return type:

Optional[Tuple[DocTestDocutilsFile, DoctestModule]]

pytest_doctest_docutils._is_doctest(config, path, parent)

Return type:

bool

pytest_doctest_docutils._init_runner_class()

Return type:

Type[DocTestRunner]

pytest_doctest_docutils._get_runner(checker=None, verbose=None, optionflags=0, continue_on_failure=True)

Return type:

DocTestRunner

class pytest_doctest_docutils.DocutilsDocTestRunner(checker=None, verbose=None, optionflags=0)

Bases: DocTestRunner

Create a new test runner.

Optional keyword arg checker is the OutputChecker that should be used to compare the expected outputs and actual outputs of doctest examples.

Optional keyword arg ‘verbose’ prints lots of stuff if true, only failures if false; by default, it’s true iff ‘-v’ is in sys.argv.

Optional argument optionflags can be used to control how the test runner compares expected output to actual output, and how it displays failures. See the documentation for testmod for more information.

summarize(out, verbose=None)

Print a summary of all the test cases that have been run by this DocTestRunner, and return a tuple (f, t), where f is the total number of failed examples, and t is the total number of tried examples.

The optional verbose argument controls how detailed the summary is. If the verbosity is not specified, then the DocTestRunner’s verbosity is used.

Return type:

Tuple[int, int]

class pytest_doctest_docutils.DocTestDocutilsFile(fspath=None, path_or_parent=None, path=None, name=None, parent=None, config=None, session=None, nodeid=None)

Bases: Module

collect()

Return a list of children (items and collectors) for this collection node.

Return type:

Iterable[DoctestItem]

name: str

A unique name within the scope of the parent node.

parent

The parent collector node.

config: Config

The pytest config object.

session: Session

The pytest session this node is part of.

path: Path

Filesystem path where this node was collected from (can be None).

_nodeid

_store