sphinx.testing is undocumented

[goerz]

https://github.com/sphinx-doc/sphinx-testing is marked deprecated and points to sphinx.testing as a replacement. However, the only documentation for this is https://www.sphinx-doc.org/en/master/devguide.html#unit-testing, which does not provide any details.

My first assumption was that maybe it's sufficient to replace from sphinx_testing import with_app with from sphinx.testing import with_app, but that does not seem to be the case:
~
ImportError: cannot import name 'with_app' from 'sphinx.testing'
~

I can sort of figure out the use of sphinx.testing by looking at the source code for Sphinx' own tests, but nonetheless there should be proper documentation. The (closed) issue #3458 already pointed out that documentation is still a todo item.

[tk0miya]

Absolutely. It must be a task for us!

[tk0miya]

As a quick note:

• Please create tests/conftest.py with following content:

import pytest

from sphinx.testing.path import path

pytest_plugins = 'sphinx.testing.fixtures'


@pytest.fixture(scope='session')
def rootdir():
    return path(__file__).parent.abspath() / 'roots'

• It provides absolute path of root directory of sphinx projects for testing as rootdir(). With above settings, they are placed under tests/roots.
• Please put sphinx projects for testing under tests/roots/test-*. By default, test-root is used for testing.
• Please write your test code.

import pytest

def test(app):
    # app is a Sphinx application object for default sphinx project (`tests/roots/test-root`).
    app.build()

@pytest.mark.sphinx(buildername='latex')
def test_latex(app):
     # latex builder is chosen here.
     app.build()

@pytest.mark.sphinx(testroot='case1')
def test_case1(app):
    # app is Sphinx application for case1 sphinx project (`tests/roots/test-case1`)
    app.build()

@pytest.mark.sphinx(confoverrides={'master_doc': 'content'})
def test_confoverrides(app):
    # a Sphinx application configured with given setting
    app.build()

I'll make a document in detail if I have time...