🧪 Add snapshot testing for cached doctrees (#1020)

This adds some snapshot testing for cached doctrees of a sphinx build, with the `snapshot_doctree` fixture.

tests/__snapshots__/test_basic_doc/test_build_html_parallel[test_app0].doctree.xml

@@ -0,0 +1,12 @@
+<document source="<source>">
+    <section ids="test-document" names="test\ document">
+        <title>
+            TEST DOCUMENT
+        <target anonymous="" ids="SP_TOO_001" refid="SP_TOO_001">
+        <Need classes="need need-spec" ids="SP_TOO_001" refid="SP_TOO_001">
+            <paragraph>
+                The Tool awesome shall have a command line interface.
+        <target anonymous="" ids="US_63252" refid="US_63252">
+        <Need classes="need need-story" ids="US_63252" refid="US_63252">
+        <target refid="needfilter-index-0">
+        <Needfilter ids="needfilter-index-0">

tests/conftest.py

@@ -3,7 +3,9 @@
 from tempfile import mkdtemp
 
 import pytest
+from docutils.nodes import document
 from sphinx.testing.path import path
+from syrupy.extensions.single_file import SingleFileSnapshotExtension, WriteMode
 
 pytest_plugins = "sphinx.testing.fixtures"
 
@@ -48,3 +50,29 @@ def test_app(make_app, request):
 
     # cleanup test temporary directory
     shutil.rmtree(sphinx_test_tempdir, False)
+
+
+class DoctreeSnapshotExtension(SingleFileSnapshotExtension):
+    _write_mode = WriteMode.TEXT
+    _file_extension = "doctree.xml"
+
+    def serialize(self, data, **kwargs):
+        if not isinstance(data, document):
+            raise TypeError(f"Expected document, got {type(data)}")
+        doc = data.deepcopy()
+        doc["source"] = "<source>"  # this will be a temp path
+        doc.attributes.pop("translation_progress", None)  # added in sphinx 7.1
+        return doc.pformat()
+
+
+@pytest.fixture
+def snapshot_doctree(snapshot):
+    """Snapshot fixture for doctrees.
+
+    Here we try to sanitize the doctree, to make the snapshots reproducible.
+    """
+    try:
+        return snapshot.with_defaults(extension_class=DoctreeSnapshotExtension)
+    except AttributeError:
+        # fallback for older versions of pytest-snapshot
+        return snapshot.use_extension(DoctreeSnapshotExtension)

tests/doc_test/doc_basic/index.rst

@@ -1,16 +1,6 @@
-.. basic test documentation master file, created by
-   sphinx-quickstart on Thu May 19 21:05:52 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to basic test's documentation!
 ======================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-
 .. story:: Test story
    :id: ST_001
    :status: open
@@ -21,12 +11,3 @@ Welcome to basic test's documentation!
 
 .. needtable::
    :filter: status == "open"
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

tests/test_basic_doc.py

@@ -9,7 +9,7 @@
 
 import pytest
 import responses
-import sphinx.application
+from sphinx.application import Sphinx
 from syrupy.filters import props
 
 from sphinx_needs.api.need import NeedsNoIdException
@@ -70,7 +70,7 @@ def test_build_html(test_app):
 
 @responses.activate
 @pytest.mark.parametrize("test_app", [{"buildername": "html", "srcdir": "doc_test/generic_doc"}], indirect=True)
-def test_build_html_parallel(test_app):
+def test_build_html_parallel(test_app: Sphinx, snapshot_doctree):
     responses.add_callback(
         responses.GET,
         re.compile(r"https://api.github.com/.*"),
@@ -89,6 +89,8 @@ def test_build_html_parallel(test_app):
     assert build_dir / "datatables_loader.js" in files
     assert build_dir / "DataTables-1.10.16" / "js" / "jquery.dataTables.min.js" in files
 
+    assert app.env.get_doctree("index") == snapshot_doctree
+
 
 @pytest.mark.skipif(sys.platform == "win32", reason="assert fails on windows, need to fix later.")
 @pytest.mark.parametrize("test_app", [{"buildername": "html", "srcdir": "doc_test/generic_doc"}], indirect=True)
@@ -232,7 +234,7 @@ def test_sphinx_api_build():
     temp_dir = tempfile.mkdtemp()
     src_dir = os.path.join(os.path.dirname(__file__), "doc_test", "doc_basic")
 
-    sphinx_app = sphinx.application.Sphinx(
+    sphinx_app = Sphinx(
         srcdir=src_dir,
         confdir=src_dir,
         outdir=temp_dir,