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 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)

Add options to py.test for doctest_docutils.

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()

Unconfigure hook for pytest-doctest-docutils.

Return type:

None

pytest_doctest_docutils.pytest_collect_file(file_path, parent)

Test collector for pytest-doctest-docutils.

Return type:

DocTestDocutilsFile | _pytest.doctest.DoctestModule | None

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_allow_unicode_flag()

Register and return the ALLOW_UNICODE flag.

Return type:

int

pytest_doctest_docutils._get_allow_bytes_flag()

Register and return the ALLOW_BYTES flag.

Return type:

int

pytest_doctest_docutils._get_number_flag()

Register and return the NUMBER flag.

Return type:

int

pytest_doctest_docutils._get_flag_lookup()

Return type:

dict[str, int]

pytest_doctest_docutils.get_optionflags(config)

Fetch optionflags from pytest configuration.

Extracted from pytest.doctest 8.0 (license: MIT).

Return type:

int

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

DocTestRunner for doctest_docutils.

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)

Summarize the test runs.

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

Pytest module for doctest_docutils.

obj = None

collect()

Collect tests for pytest module.

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: pathlib.Path

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

_nodeid

_store

_abc_impl = <_abc._abc_data object>