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)

function

Add options to py.test for doctest_docutils.

Parameters:

parser (Parser)

Return type:

None

pytest_doctest_docutils.pytest_configure(config)

function

Disable pytest.doctest to prevent running tests twice.

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

Parameters:

config (Config)

Return type:

None

pytest_doctest_docutils._unblock_doctest(config)

function

Unblock doctest plugin (pytest 8.1+ only).

Re-enables the built-in doctest plugin after it was blocked by pytest_configure. Uses the public unblock() API introduced in pytest 8.1.0.

Parameters:

config (pytest.Config) – The pytest configuration object

Returns:

True if unblocked successfully, False if API not available

Return type:

bool

pytest_doctest_docutils.pytest_unconfigure()

function

Unconfigure hook for pytest-doctest-docutils.

Return type:

None

pytest_doctest_docutils.pytest_collect_file(file_path, parent)

function

Test collector for pytest-doctest-docutils.

Parameters:

• file_path (Path)

• parent (Collector)

Return type:

DocTestDocutilsFile | DoctestModule | None

pytest_doctest_docutils._is_doctest(config, path, parent)

function

Parameters:

• config (Config)

• path (Path)

• parent (Collector)

Return type:

bool

pytest_doctest_docutils._init_runner_class()

function

Return type:

type[DocTestRunner]

pytest_doctest_docutils._get_allow_unicode_flag()

function

Register and return the ALLOW_UNICODE flag.

Return type:

int

pytest_doctest_docutils._get_allow_bytes_flag()

function

Register and return the ALLOW_BYTES flag.

Return type:

int

pytest_doctest_docutils._get_number_flag()

function

Register and return the NUMBER flag.

Return type:

int

pytest_doctest_docutils._get_flag_lookup()

function

Return type:

dict[str, int]

pytest_doctest_docutils.get_optionflags(config)

function

Fetch optionflags from pytest configuration.

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

Parameters:

config (Config)

Return type:

int

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

function

Parameters:

• checker (OutputChecker | None)

• verbose (bool | None)

• optionflags (int)

• continue_on_failure (bool)

Return type:

DocTestRunner

class pytest_doctest_docutils.DocutilsDocTestRunner

class

Bases: DocTestRunner

DocTestRunner for doctest_docutils.

summarize(out, verbose=None)

method

Summarize the test runs.

Parameters:

• out (_Out)

• verbose (bool | None)

Return type:

tuple[int, int]

class pytest_doctest_docutils.DocTestDocutilsFile

class

Bases: Module

Pytest module for doctest_docutils.

obj = None

attribute

collect()

method

Collect tests for pytest module.

Return type:

Iterable[DoctestItem]

_nodeid

attribute

_store

attribute

config: Config

attribute

The pytest config object.

name: str

attribute

A unique name within the scope of the parent node.

parent

attribute

The parent collector node.

path: pathlib.Path

attribute

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

session: Session

attribute

The pytest session this node is part of.

_abc_impl = <_abc._abc_data object>

attribute