mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
361 lines
11 KiB
Python
361 lines
11 KiB
Python
# -*- coding: utf-8 -*-
|
|
"""
|
|
Sphinx test suite utilities
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
|
|
:license: BSD, see LICENSE for details.
|
|
"""
|
|
|
|
import os
|
|
import re
|
|
import sys
|
|
import warnings
|
|
from functools import wraps
|
|
from xml.etree import ElementTree
|
|
|
|
from six import string_types
|
|
from six import StringIO
|
|
|
|
import pytest
|
|
|
|
from docutils import nodes
|
|
from docutils.parsers.rst import directives, roles
|
|
|
|
from sphinx import application
|
|
from sphinx.builders.latex import LaTeXBuilder
|
|
from sphinx.ext.autodoc import AutoDirective
|
|
from sphinx.pycode import ModuleAnalyzer
|
|
from sphinx.deprecation import RemovedInSphinx17Warning
|
|
|
|
from path import path
|
|
|
|
|
|
__all__ = [
|
|
'rootdir', 'tempdir',
|
|
'skip_unless_importable', 'Struct',
|
|
'SphinxTestApp',
|
|
'path',
|
|
'remove_unicode_literals',
|
|
]
|
|
|
|
|
|
rootdir = path(os.path.dirname(__file__) or '.').abspath()
|
|
tempdir = path(os.environ['SPHINX_TEST_TEMPDIR']).abspath()
|
|
|
|
|
|
def assert_re_search(regex, text, flags=0):
|
|
if not re.search(regex, text, flags):
|
|
assert False, '%r did not match %r' % (regex, text)
|
|
|
|
|
|
def assert_not_re_search(regex, text, flags=0):
|
|
if re.search(regex, text, flags):
|
|
assert False, '%r did match %r' % (regex, text)
|
|
|
|
|
|
def assert_startswith(thing, prefix):
|
|
if not thing.startswith(prefix):
|
|
assert False, '%r does not start with %r' % (thing, prefix)
|
|
|
|
|
|
def assert_node(node, cls=None, xpath="", **kwargs):
|
|
if cls:
|
|
if isinstance(cls, list):
|
|
assert_node(node, cls[0], xpath=xpath, **kwargs)
|
|
if cls[1:]:
|
|
if isinstance(cls[1], tuple):
|
|
assert_node(node, cls[1], xpath=xpath, **kwargs)
|
|
else:
|
|
assert len(node) == 1, \
|
|
'The node%s has %d child nodes, not one' % (xpath, len(node))
|
|
assert_node(node[0], cls[1:], xpath=xpath + "[0]", **kwargs)
|
|
elif isinstance(cls, tuple):
|
|
assert len(node) == len(cls), \
|
|
'The node%s has %d child nodes, not %r' % (xpath, len(node), len(cls))
|
|
for i, nodecls in enumerate(cls):
|
|
path = xpath + "[%d]" % i
|
|
assert_node(node[i], nodecls, xpath=path, **kwargs)
|
|
elif isinstance(cls, string_types):
|
|
assert node == cls, 'The node %r is not %r: %r' % (xpath, cls, node)
|
|
else:
|
|
assert isinstance(node, cls), \
|
|
'The node%s is not subclass of %r: %r' % (xpath, cls, node)
|
|
|
|
for key, value in kwargs.items():
|
|
assert key in node, 'The node%s does not have %r attribute: %r' % (xpath, key, node)
|
|
assert node[key] == value, \
|
|
'The node%s[%s] is not %r: %r' % (xpath, key, value, node[key])
|
|
|
|
|
|
def skip_unless_importable(module, msg=None):
|
|
"""Decorator to skip test if module is not importable."""
|
|
try:
|
|
__import__(module)
|
|
except ImportError:
|
|
return pytest.mark.skipif(True, reason=(msg or 'conditional skip'))
|
|
else:
|
|
return pytest.mark.skipif(False, reason=(msg or 'conditional skip'))
|
|
|
|
|
|
def etree_parse(path):
|
|
with warnings.catch_warnings(record=False):
|
|
warnings.filterwarnings("ignore", category=DeprecationWarning)
|
|
return ElementTree.parse(path)
|
|
|
|
|
|
class Struct(object):
|
|
def __init__(self, **kwds):
|
|
self.__dict__.update(kwds)
|
|
|
|
|
|
class SphinxTestApp(application.Sphinx):
|
|
"""
|
|
A subclass of :class:`Sphinx` that runs on the test root, with some
|
|
better default values for the initialization parameters.
|
|
"""
|
|
|
|
def __init__(self, buildername='html', testroot=None, srcdir=None,
|
|
freshenv=False, confoverrides=None, status=None, warning=None,
|
|
tags=None, docutilsconf=None):
|
|
if testroot is None:
|
|
defaultsrcdir = 'root'
|
|
testroot = rootdir / 'root'
|
|
else:
|
|
defaultsrcdir = 'test-' + testroot
|
|
testroot = rootdir / 'roots' / ('test-' + testroot)
|
|
if srcdir is None:
|
|
srcdir = tempdir / defaultsrcdir
|
|
else:
|
|
srcdir = tempdir / srcdir
|
|
|
|
if not srcdir.exists():
|
|
testroot.copytree(srcdir)
|
|
|
|
if docutilsconf is not None:
|
|
(srcdir / 'docutils.conf').write_text(docutilsconf)
|
|
|
|
builddir = srcdir / '_build'
|
|
# if confdir is None:
|
|
confdir = srcdir
|
|
# if outdir is None:
|
|
outdir = builddir.joinpath(buildername)
|
|
if not outdir.isdir():
|
|
outdir.makedirs()
|
|
# if doctreedir is None:
|
|
doctreedir = builddir.joinpath('doctrees')
|
|
if not doctreedir.isdir():
|
|
doctreedir.makedirs()
|
|
if confoverrides is None:
|
|
confoverrides = {}
|
|
# if warningiserror is None:
|
|
warningiserror = False
|
|
|
|
self._saved_path = sys.path[:]
|
|
self._saved_directives = directives._directives.copy()
|
|
self._saved_roles = roles._roles.copy()
|
|
|
|
self._saved_nodeclasses = set(v for v in dir(nodes.GenericNodeVisitor)
|
|
if v.startswith('visit_'))
|
|
|
|
try:
|
|
application.Sphinx.__init__(self, srcdir, confdir, outdir, doctreedir,
|
|
buildername, confoverrides, status, warning,
|
|
freshenv, warningiserror, tags)
|
|
except:
|
|
self.cleanup()
|
|
raise
|
|
|
|
def cleanup(self, doctrees=False):
|
|
AutoDirective._registry.clear()
|
|
ModuleAnalyzer.cache.clear()
|
|
LaTeXBuilder.usepackages = []
|
|
sys.path[:] = self._saved_path
|
|
sys.modules.pop('autodoc_fodder', None)
|
|
directives._directives = self._saved_directives
|
|
roles._roles = self._saved_roles
|
|
for method in dir(nodes.GenericNodeVisitor):
|
|
if method.startswith('visit_') and \
|
|
method not in self._saved_nodeclasses:
|
|
delattr(nodes.GenericNodeVisitor, 'visit_' + method[6:])
|
|
delattr(nodes.GenericNodeVisitor, 'depart_' + method[6:])
|
|
|
|
def __repr__(self):
|
|
return '<%s buildername=%r>' % (self.__class__.__name__, self.builder.name)
|
|
|
|
|
|
_unicode_literals_re = re.compile(r'u(".*?")|u(\'.*?\')')
|
|
|
|
|
|
def remove_unicode_literals(s):
|
|
return _unicode_literals_re.sub(lambda x: x.group(1) or x.group(2), s)
|
|
|
|
|
|
def find_files(root, suffix=None):
|
|
for dirpath, dirs, files in os.walk(root, followlinks=True):
|
|
dirpath = path(dirpath)
|
|
for f in [f for f in files if not suffix or f.endswith(suffix)]:
|
|
fpath = dirpath / f
|
|
yield os.path.relpath(fpath, root)
|
|
|
|
|
|
def strip_escseq(text):
|
|
return re.sub('\x1b.*?m', '', text)
|
|
|
|
|
|
# #############################################
|
|
# DEPRECATED implementations
|
|
|
|
|
|
def gen_with_app(*args, **kwargs):
|
|
"""
|
|
**DEPRECATED**: use pytest.mark.parametrize instead.
|
|
|
|
Decorate a test generator to pass a SphinxTestApp as the first argument to
|
|
the test generator when it's executed.
|
|
"""
|
|
def generator(func):
|
|
@wraps(func)
|
|
def deco(*args2, **kwargs2):
|
|
status, warning = StringIO(), StringIO()
|
|
kwargs['status'] = status
|
|
kwargs['warning'] = warning
|
|
app = SphinxTestApp(*args, **kwargs)
|
|
try:
|
|
for item in func(app, status, warning, *args2, **kwargs2):
|
|
yield item
|
|
finally:
|
|
app.cleanup()
|
|
return deco
|
|
return generator
|
|
|
|
|
|
def skip_if(condition, msg=None):
|
|
"""
|
|
**DEPRECATED**: use pytest.mark.skipif instead.
|
|
|
|
Decorator to skip test if condition is true.
|
|
"""
|
|
return pytest.mark.skipif(condition, reason=(msg or 'conditional skip'))
|
|
|
|
|
|
def skip_unless(condition, msg=None):
|
|
"""
|
|
**DEPRECATED**: use pytest.mark.skipif instead.
|
|
|
|
Decorator to skip test if condition is false.
|
|
"""
|
|
return pytest.mark.skipif(not condition, reason=(msg or 'conditional skip'))
|
|
|
|
|
|
def with_tempdir(func):
|
|
"""
|
|
**DEPRECATED**: use tempdir fixture instead.
|
|
"""
|
|
return func
|
|
|
|
|
|
def raises(exc, func, *args, **kwds):
|
|
"""
|
|
**DEPRECATED**: use pytest.raises instead.
|
|
|
|
Raise AssertionError if ``func(*args, **kwds)`` does not raise *exc*.
|
|
"""
|
|
with pytest.raises(exc):
|
|
func(*args, **kwds)
|
|
|
|
|
|
def raises_msg(exc, msg, func, *args, **kwds):
|
|
"""
|
|
**DEPRECATED**: use pytest.raises instead.
|
|
|
|
Raise AssertionError if ``func(*args, **kwds)`` does not raise *exc*,
|
|
and check if the message contains *msg*.
|
|
"""
|
|
with pytest.raises(exc) as excinfo:
|
|
func(*args, **kwds)
|
|
assert msg in str(excinfo.value)
|
|
|
|
|
|
def assert_true(v1, msg=''):
|
|
"""
|
|
**DEPRECATED**: use assert instead.
|
|
"""
|
|
assert v1, msg
|
|
|
|
|
|
def assert_equal(v1, v2, msg=''):
|
|
"""
|
|
**DEPRECATED**: use assert instead.
|
|
"""
|
|
assert v1 == v2, msg
|
|
|
|
|
|
def assert_in(x, thing, msg=''):
|
|
"""
|
|
**DEPRECATED**: use assert instead.
|
|
"""
|
|
if x not in thing:
|
|
assert False, msg or '%r is not in %r' % (x, thing)
|
|
|
|
|
|
def assert_not_in(x, thing, msg=''):
|
|
"""
|
|
**DEPRECATED**: use assert instead.
|
|
"""
|
|
if x in thing:
|
|
assert False, msg or '%r is in %r' % (x, thing)
|
|
|
|
|
|
class ListOutput(object):
|
|
"""
|
|
File-like object that collects written text in a list.
|
|
"""
|
|
def __init__(self, name):
|
|
self.name = name
|
|
self.content = []
|
|
|
|
def reset(self):
|
|
del self.content[:]
|
|
|
|
def write(self, text):
|
|
self.content.append(text)
|
|
|
|
|
|
# **DEPRECATED**: use pytest.skip instead.
|
|
SkipTest = pytest.skip.Exception
|
|
|
|
|
|
class _DeprecationWrapper(object):
|
|
def __init__(self, mod, deprecated):
|
|
self._mod = mod
|
|
self._deprecated = deprecated
|
|
|
|
def __getattr__(self, attr):
|
|
if attr in self._deprecated:
|
|
obj, instead = self._deprecated[attr]
|
|
warnings.warn("tests/util.py::%s is deprecated and will be "
|
|
"removed in Sphinx 1.7, please use %s instead."
|
|
% (attr, instead),
|
|
RemovedInSphinx17Warning, stacklevel=2)
|
|
return obj
|
|
return getattr(self._mod, attr)
|
|
|
|
|
|
sys.modules[__name__] = _DeprecationWrapper(sys.modules[__name__], dict( # type: ignore
|
|
with_app=(pytest.mark.sphinx, 'pytest.mark.sphinx'),
|
|
TestApp=(SphinxTestApp, 'SphinxTestApp'),
|
|
gen_with_app=(gen_with_app, 'pytest.mark.parametrize'),
|
|
skip_if=(skip_if, 'pytest.skipif'),
|
|
skip_unless=(skip_unless, 'pytest.skipif'),
|
|
with_tempdir=(with_tempdir, 'tmpdir pytest fixture'),
|
|
raises=(raises, 'pytest.raises'),
|
|
raises_msg=(raises_msg, 'pytest.raises'),
|
|
assert_true=(assert_true, 'assert'),
|
|
assert_equal=(assert_equal, 'assert'),
|
|
assert_in=(assert_in, 'assert'),
|
|
assert_not_in=(assert_not_in, 'assert'),
|
|
ListOutput=(ListOutput, 'StringIO'),
|
|
SkipTest=(SkipTest, 'pytest.skip'),
|
|
))
|