""" sphinx.testing.fixtures ~~~~~~~~~~~~~~~~~~~~~~~ Sphinx test fixtures for pytest :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ import os import subprocess import sys from collections import namedtuple from io import StringIO from subprocess import PIPE from typing import Any, Callable, Dict, Generator, Tuple import pytest from sphinx.testing import util from sphinx.testing.util import SphinxTestApp, SphinxTestAppWrapperForSkipBuilding DEFAULT_ENABLED_MARKERS = [ ( 'sphinx(builder, testroot=None, freshenv=False, confoverrides=None, tags=None,' ' docutilsconf=None, parallel=0): arguments to initialize the sphinx test application.' ), 'test_params(shared_result=...): test parameters.', ] def pytest_configure(config): # register custom markers for marker in DEFAULT_ENABLED_MARKERS: config.addinivalue_line('markers', marker) @pytest.fixture(scope='session') def rootdir() -> str: return None class SharedResult: cache = {} # type: Dict[str, Dict[str, str]] def store(self, key: str, app_: SphinxTestApp) -> Any: if key in self.cache: return data = { 'status': app_._status.getvalue(), 'warning': app_._warning.getvalue(), } self.cache[key] = data def restore(self, key: str) -> Dict[str, StringIO]: if key not in self.cache: return {} data = self.cache[key] return { 'status': StringIO(data['status']), 'warning': StringIO(data['warning']), } @pytest.fixture def app_params(request: Any, test_params: Dict, shared_result: SharedResult, sphinx_test_tempdir: str, rootdir: str) -> Tuple[Dict, Dict]: """ parameters that is specified by 'pytest.mark.sphinx' for sphinx.application.Sphinx initialization """ # ##### process pytest.mark.sphinx if hasattr(request.node, 'iter_markers'): # pytest-3.6.0 or newer markers = request.node.iter_markers("sphinx") else: markers = request.node.get_marker("sphinx") pargs = {} kwargs = {} # type: Dict[str, Any] if markers is not None: # to avoid stacking positional args for info in reversed(list(markers)): for i, a in enumerate(info.args): pargs[i] = a kwargs.update(info.kwargs) args = [pargs[i] for i in sorted(pargs.keys())] # ##### process pytest.mark.test_params if test_params['shared_result']: if 'srcdir' in kwargs: raise pytest.Exception('You can not specify shared_result and ' 'srcdir in same time.') kwargs['srcdir'] = test_params['shared_result'] restore = shared_result.restore(test_params['shared_result']) kwargs.update(restore) # ##### prepare Application params testroot = kwargs.pop('testroot', 'root') kwargs['srcdir'] = srcdir = sphinx_test_tempdir / kwargs.get('srcdir', testroot) # special support for sphinx/tests if rootdir and not srcdir.exists(): testroot_path = rootdir / ('test-' + testroot) testroot_path.copytree(srcdir) return namedtuple('app_params', 'args,kwargs')(args, kwargs) # type: ignore @pytest.fixture def test_params(request: Any) -> Dict: """ test parameters that is specified by 'pytest.mark.test_params' :param Union[str] shared_result: If the value is provided, app._status and app._warning objects will be shared in the parametrized test functions and/or test functions that have same 'shared_result' value. **NOTE**: You can not specify shared_result and srcdir in same time. """ if hasattr(request.node, 'get_closest_marker'): # pytest-3.6.0 or newer env = request.node.get_closest_marker('test_params') else: env = request.node.get_marker('test_params') kwargs = env.kwargs if env else {} result = { 'shared_result': None, } result.update(kwargs) if (result['shared_result'] and not isinstance(result['shared_result'], str)): raise pytest.Exception('You can only provide a string type of value ' 'for "shared_result" ') return result @pytest.fixture(scope='function') def app(test_params: Dict, app_params: Tuple[Dict, Dict], make_app: Callable, shared_result: SharedResult) -> Generator[SphinxTestApp, None, None]: """ provides sphinx.application.Sphinx object """ args, kwargs = app_params app_ = make_app(*args, **kwargs) yield app_ print('# testroot:', kwargs.get('testroot', 'root')) print('# builder:', app_.builder.name) print('# srcdir:', app_.srcdir) print('# outdir:', app_.outdir) print('# status:', '\n' + app_._status.getvalue()) print('# warning:', '\n' + app_._warning.getvalue()) if test_params['shared_result']: shared_result.store(test_params['shared_result'], app_) @pytest.fixture(scope='function') def status(app: SphinxTestApp) -> StringIO: """ compat for testing with previous @with_app decorator """ return app._status @pytest.fixture(scope='function') def warning(app: SphinxTestApp) -> StringIO: """ compat for testing with previous @with_app decorator """ return app._warning @pytest.fixture() def make_app(test_params: Dict, monkeypatch: Any) -> Generator[Callable, None, None]: """ provides make_app function to initialize SphinxTestApp instance. if you want to initialize 'app' in your test function. please use this instead of using SphinxTestApp class directory. """ monkeypatch.setattr('sphinx.application.abspath', lambda x: x) apps = [] syspath = sys.path[:] def make(*args, **kwargs): status, warning = StringIO(), StringIO() kwargs.setdefault('status', status) kwargs.setdefault('warning', warning) app_ = SphinxTestApp(*args, **kwargs) # type: Any apps.append(app_) if test_params['shared_result']: app_ = SphinxTestAppWrapperForSkipBuilding(app_) return app_ yield make sys.path[:] = syspath for app_ in reversed(apps): # clean up applications from the new ones app_.cleanup() @pytest.fixture def shared_result() -> SharedResult: return SharedResult() @pytest.fixture(scope='module', autouse=True) def _shared_result_cache() -> None: SharedResult.cache.clear() @pytest.fixture def if_graphviz_found(app: SphinxTestApp) -> None: """ The test will be skipped when using 'if_graphviz_found' fixture and graphviz dot command is not found. """ graphviz_dot = getattr(app.config, 'graphviz_dot', '') try: if graphviz_dot: subprocess.run([graphviz_dot, '-V'], stdout=PIPE, stderr=PIPE) # show version return except OSError: # No such file or directory pass pytest.skip('graphviz "dot" is not available') @pytest.fixture(scope='session') def sphinx_test_tempdir(tmpdir_factory: Any) -> "util.path": """ temporary directory that wrapped with `path` class. """ tmpdir = os.environ.get('SPHINX_TEST_TEMPDIR') # RemovedInSphinx40Warning if tmpdir is None: tmpdir = tmpdir_factory.getbasetemp() return util.path(tmpdir).abspath() @pytest.fixture def tempdir(tmpdir: str) -> "util.path": """ temporary directory that wrapped with `path` class. this fixture is for compat with old test implementation. """ return util.path(tmpdir)