python - 如何对具有覆盖率的 sphinxdoc 扩展进行单元测试(在 PyCharm 中)？

Question

所以我写了许多 sphinxdoc 扩展，例如这个(用作示例，因为它是最简单的):

from docutils import nodes
from docutils.statemachine import StringList
from sphinx.util.compat import Directive

class SvnRevisionDirective(Directive):
    """Directive to display subversion revision of the path.
    """
    has_content = True
    required_arguments = 1
    optional_arguments = 1
    final_argument_whitespace = False
    option_spec = {}

    def run(self):
        path = self.arguments[0]
        # rev = svntools.Revision(path)
        rev = 42
        paragraph = nodes.paragraph()
        self.state.nested_parse(
            StringList([
                '**Revision:** r%d' % rev
            ]), 0, paragraph)
        return [paragraph]

def setup(app):
    """Directive framework code.
    """
    app.add_directive('svnrevision', SvnRevisionDirective)

将扩展路径添加到 extensions 后在文档的 conf.py 中它可以像这样使用:

.. svnrevision:: mypackage/__init__.py

并将产生:

修订: r42

为了测试它是否正常工作，我可以创建一个 tests/testproj目录并用 docs 填充它目录，一个 conf.py文件和 index.rst包含指令的文件，并使用:

import os
import pytest
DIRNAME = os.path.dirname(__file__)

@pytest.mark.django_db
def test_svnrevision(monkeypatch):
    testprojdir = os.path.join(DIRNAME, 'testproj')
    monkeypatch.setenv('PYTHONPATH', testprojdir, os.pathsep)
    monkeypatch.setenv('DJANGO_SETTINGS_MODULE', 'testingapp.settings')
    monkeypatch.chdir(DIRNAME)
    cmd = 'sphinx-build -bhtml -a -E testproj/docs testproj/build'
    os.system(cmd)

但这在测试和代码之间留下了很大的距离，并且不会给我代码覆盖率，至少在 PyCharm 下运行时不会。

我想要更直接的东西，类似于例如:

def test_svnrevision():
    rst = """
        .. svnrevision:: mypackage/__init__.py
    """
    svndirective = SvnRevisionDirective(...., rst, ...)
    result = svndirective.run()
    assert result.___ == '**Revision:** 42'

这可能吗？

Answer 1

如果你使用 unittest 或nose，你可以尝试使用 sphinx-testing模块，可在 PyPI 上使用。

对于基于 pytest 的单元测试，the approach differs based on Sphinx version you are using .

从 Sphinx 1.6.1 开始，你可以使用 pytest 插件 sphinx.testing.fixtures如 Sphinx Developer’s Guide 中所述.虽然此功能仍处于试验阶段，但与下面描述的其他功能相比，它似乎是更好的选择。

对于 Sphinx <= 1.6.0 的 pytest 测试，无法直接重用 Sphinx 测试 fixture 。可以尝试复制contest.py , path.py和 util.py来自 sphinx/tests directory 的文件进入你自己的项目并破解 util.py文件有点让它在没有自定义 sphinx runner 的情况下工作(run.py 文件):

+# code from run.py
+testroot = os.path.dirname(__file__) or '.'
+# find a temp dir for testing and clean it up now
+os.environ['SPHINX_TEST_TEMPDIR'] = \
+    os.path.abspath(os.path.join(testroot, 'build')) \
+    if 'SPHINX_TEST_TEMPDIR' not in os.environ \
+    else os.path.abspath(os.environ['SPHINX_TEST_TEMPDIR'])
+
 rootdir = path(os.path.dirname(__file__) or '.').abspath()
 tempdir = path(os.environ['SPHINX_TEST_TEMPDIR']).abspath()

+# code from run.py
+print('Temporary files will be placed in %s.' % tempdir)
+if tempdir.exists():
+    tempdir.rmtree()
+tempdir.makedirs()
+

然后您以与在 Sphinx 单元测试中看到的相同的方式编写单元测试。