🧪 Improve tests/test_basic_doc.py (#1300)

All tests are now checked for build warnings.

Additionally, the `generic_doc` test build was removed, since it was basically the same as `doc_basic`

Author: chrisjsewell

tests/__snapshots__/test_basic_doc.ambr

@@ -1,8 +1,8 @@
 # name: test_build_needs[test_app0]
   dict({
-    'current_version': '',
+    'current_version': '0.1.0',
     'versions': dict({
-      '': dict({
+      '0.1.0': dict({
         'filters': dict({
         }),
         'filters_amount': 0,
@@ -56,9 +56,9 @@
             'pre_template': None,
             'prefix': '',
             'query': '',
-            'section_name': 'Welcome to basic test’s documentation!',
+            'section_name': 'TEST DOCUMENT',
             'sections': list([
-              'Welcome to basic test’s documentation!',
+              'TEST DOCUMENT',
             ]),
             'service': '',
             'signature': '',
@@ -126,9 +126,9 @@
             'pre_template': None,
             'prefix': '',
             'query': '',
-            'section_name': 'Welcome to basic test’s documentation!',
+            'section_name': 'TEST DOCUMENT',
             'sections': list([
-              'Welcome to basic test’s documentation!',
+              'TEST DOCUMENT',
             ]),
             'service': '',
             'signature': '',

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

@@ -0,0 +1,10 @@
+<document source="<source>">
+    <section ids="test-document" names="test\ document">
+        <title>
+            TEST DOCUMENT
+        <target anonymous="" ids="ST_001" refid="ST_001">
+        <Need classes="need need-story" ids="ST_001" refid="ST_001">
+        <target anonymous="" ids="US_38823" refid="US_38823">
+        <Need classes="need need-story" ids="US_38823" refid="US_38823">
+        <target refid="needtable-index-0">
+        <Needtable caption="True" classes="" columns="('ID',\ 'ID') ('TITLE',\ 'Title') ('STATUS',\ 'Status') ('TYPE',\ 'Type') ('OUTGOING',\ 'Outgoing') ('TAGS',\ 'Tags')" colwidths="" docname="index" export_id="" filter="status == "open"" filter_code="[]" filter_func="True" filter_warning="True" ids="needtable-index-0" lineno="12" show_filters="False" show_parts="False" sort="id_complete" sort_by="True" status="" style="" style_col="" style_row="" tags="" target_id="needtable-index-0" types="">

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

@@ -1,7 +1,9 @@
-extensions = ["sphinx_needs", "sphinxcontrib.plantuml"]
+version = "0.1.0"
+copyright = "2024"
 
-# note, the plantuml executable command is set globally in the test suite
-plantuml_output_format = "svg"
+extensions = ["sphinx_needs"]
+
+suppress_warnings = ["epub.unknown_project_files"]
 
 needs_id_regex = "^[A-Za-z0-9_]"
 

tests/doc_test/doc_basic/conf.py

@@ -1,5 +1,5 @@
-Welcome to basic test's documentation!
-======================================
+TEST DOCUMENT
+=============
 
 .. story:: Test story
    :id: ST_001

tests/doc_test/doc_basic/index.rst

@@ -6,37 +6,31 @@
 from pathlib import Path
 
 import pytest
+from lxml import html as html_parser
 from sphinx import version_info
-from sphinx.application import Sphinx
 from sphinx.testing.util import SphinxTestApp
 from syrupy.filters import props
 
 from sphinx_needs.api.need import NeedsNoIdException
 
 
-@pytest.mark.parametrize(
-    "test_app", [{"buildername": "html", "srcdir": "doc_test/doc_basic"}], indirect=True
-)
-def test_build_html(test_app):
-    app = test_app
-    app.builder.build_all()
-
-    # Check if static files got copied correctly.
-    build_dir = Path(app.outdir) / "_static" / "sphinx-needs" / "libs" / "html"
-    files = [f for f in build_dir.glob("**/*") if f.is_file()]
-    assert build_dir / "sphinx_needs_collapse.js" in files
-    assert build_dir / "datatables_loader.js" in files
-    assert build_dir / "DataTables-1.10.16" / "js" / "jquery.dataTables.min.js" in files
-
-
 @pytest.mark.parametrize(
     "test_app",
-    [{"buildername": "html", "srcdir": "doc_test/generic_doc"}],
+    [{"buildername": "html", "srcdir": "doc_test/doc_basic", "no_plantuml": True}],
     indirect=True,
 )
-def test_build_html_parallel(test_app: Sphinx, snapshot_doctree):
+def test_build_html(test_app: SphinxTestApp, snapshot_doctree):
     app = test_app
-    app.builder.build_all()
+    app.build()
+    assert app._warning.getvalue() == ""
+
+    # Check if doctree is correct.
+    assert app.env.get_doctree("index") == snapshot_doctree
+
+    # Basic checks for the generated html.
+    html = Path(app.outdir, "index.html").read_text()
+    assert "<h1>TEST DOCUMENT" in html
+    assert "ST_001" in html
 
     # Check if static files got copied correctly.
     build_dir = Path(app.outdir) / "_static" / "sphinx-needs" / "libs" / "html"
@@ -45,22 +39,19 @@ def test_build_html_parallel(test_app: Sphinx, snapshot_doctree):
     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"}],
+    [{"buildername": "html", "srcdir": "doc_test/doc_basic", "no_plantuml": True}],
     indirect=True,
 )
-def test_html_head_files(test_app):
+def test_html_head_files(test_app: SphinxTestApp):
     app = test_app
-    app.builder.build_all()
-
-    from lxml import html as html_parser
+    app.build()
+    assert app._warning.getvalue() == ""
 
     # check usage in project root level
     html_path = str(Path(app.outdir, "index.html"))
@@ -81,48 +72,64 @@ def test_html_head_files(test_app):
 
 @pytest.mark.parametrize(
     "test_app",
-    [{"buildername": "singlehtml", "srcdir": "doc_test/doc_basic"}],
+    [
+        {
+            "buildername": "singlehtml",
+            "srcdir": "doc_test/doc_basic",
+            "no_plantuml": True,
+        }
+    ],
     indirect=True,
 )
-def test_build_singlehtml(test_app):
+def test_build_singlehtml(test_app: SphinxTestApp):
     app = test_app
-    app.builder.build_all()
+    app.build()
+    assert app._warning.getvalue() == ""
 
 
 @pytest.mark.parametrize(
     "test_app",
-    [{"buildername": "latex", "srcdir": "doc_test/doc_basic"}],
+    [{"buildername": "latex", "srcdir": "doc_test/doc_basic", "no_plantuml": True}],
     indirect=True,
 )
-def test_build_latex(test_app):
+def test_build_latex(test_app: SphinxTestApp):
     app = test_app
-    app.builder.build_all()
+    app.build()
+    assert app._warning.getvalue() == ""
 
 
 @pytest.mark.parametrize(
-    "test_app", [{"buildername": "epub", "srcdir": "doc_test/doc_basic"}], indirect=True
+    "test_app",
+    [{"buildername": "epub", "srcdir": "doc_test/doc_basic", "no_plantuml": True}],
+    indirect=True,
 )
-def test_build_epub(test_app):
+def test_build_epub(test_app: SphinxTestApp):
     app = test_app
-    app.builder.build_all()
+    app.build()
+    assert app._warning.getvalue() == ""
 
 
 @pytest.mark.parametrize(
-    "test_app", [{"buildername": "json", "srcdir": "doc_test/doc_basic"}], indirect=True
+    "test_app",
+    [{"buildername": "json", "srcdir": "doc_test/doc_basic", "no_plantuml": True}],
+    indirect=True,
 )
-def test_build_json(test_app):
+def test_build_json(test_app: SphinxTestApp):
     app = test_app
-    app.builder.build_all()
+    app.build()
+    assert app._warning.getvalue() == ""
 
 
 @pytest.mark.parametrize(
     "test_app",
-    [{"buildername": "needs", "srcdir": "doc_test/doc_basic"}],
+    [{"buildername": "needs", "srcdir": "doc_test/doc_basic", "no_plantuml": True}],
     indirect=True,
 )
-def test_build_needs(test_app, snapshot):
+def test_build_needs(test_app: SphinxTestApp, snapshot):
     app = test_app
-    app.builder.build_all()
+    app.build()
+    assert app._warning.getvalue() == ""
+
     json_text = Path(app.outdir, "needs.json").read_text()
     needs_data = json.loads(json_text)
 
@@ -137,14 +144,15 @@ def test_build_needs(test_app, snapshot):
             "buildername": "html",
             "srcdir": "doc_test/doc_basic",
             "confoverrides": {"needs_id_required": True},
+            "no_plantuml": True,
         }
     ],
     indirect=True,
 )
-def test_id_required_build_html(test_app):
+def test_id_required_build_html(test_app: SphinxTestApp):
     with pytest.raises(NeedsNoIdException):
         app = test_app
-        app.builder.build_all()
+        app.build()
 
 
 def test_sphinx_api_build(tmp_path: Path, make_app: type[SphinxTestApp]):