From dc3242a52f94a44bb3d41e1582acd42b008c3f89 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Fri, 13 Sep 2024 15:04:12 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=AA=20Improve=20`tests/test=5Fbasic=5F?= =?UTF-8?q?doc.py`=20(#1300)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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` --- tests/__snapshots__/test_basic_doc.ambr | 12 +-- .../test_build_html[test_app0].doctree.xml | 10 ++ ...build_html_parallel[test_app0].doctree.xml | 12 --- tests/doc_test/doc_basic/conf.py | 8 +- tests/doc_test/doc_basic/index.rst | 4 +- tests/doc_test/generic_doc/conf.py | 32 ------- tests/doc_test/generic_doc/index.rst | 15 --- tests/test_basic_doc.py | 94 ++++++++++--------- tests/test_test_doc.py | 16 ---- 9 files changed, 74 insertions(+), 129 deletions(-) create mode 100644 tests/__snapshots__/test_basic_doc/test_build_html[test_app0].doctree.xml delete mode 100644 tests/__snapshots__/test_basic_doc/test_build_html_parallel[test_app0].doctree.xml delete mode 100644 tests/doc_test/generic_doc/conf.py delete mode 100644 tests/doc_test/generic_doc/index.rst delete mode 100644 tests/test_test_doc.py diff --git a/tests/__snapshots__/test_basic_doc.ambr b/tests/__snapshots__/test_basic_doc.ambr index 2250a9f60..543c737ea 100644 --- a/tests/__snapshots__/test_basic_doc.ambr +++ b/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': '', diff --git a/tests/__snapshots__/test_basic_doc/test_build_html[test_app0].doctree.xml b/tests/__snapshots__/test_basic_doc/test_build_html[test_app0].doctree.xml new file mode 100644 index 000000000..b4019c907 --- /dev/null +++ b/tests/__snapshots__/test_basic_doc/test_build_html[test_app0].doctree.xml @@ -0,0 +1,10 @@ + +
+ + 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=""> diff --git a/tests/__snapshots__/test_basic_doc/test_build_html_parallel[test_app0].doctree.xml b/tests/__snapshots__/test_basic_doc/test_build_html_parallel[test_app0].doctree.xml deleted file mode 100644 index 369ab7c58..000000000 --- a/tests/__snapshots__/test_basic_doc/test_build_html_parallel[test_app0].doctree.xml +++ /dev/null @@ -1,12 +0,0 @@ -<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 docname="index" export_id="" filter="True" filter_code="[]" filter_func="True" filter_warning="True" ids="needfilter-index-0" layout="list" lineno="14" show_filters="False" show_legend="False" show_status="False" show_tags="False" sort_by="True" status="" tags="test my_test" target_id="needfilter-index-0" types=""> diff --git a/tests/doc_test/doc_basic/conf.py b/tests/doc_test/doc_basic/conf.py index eab8dc5d6..ec173fd2e 100644 --- a/tests/doc_test/doc_basic/conf.py +++ b/tests/doc_test/doc_basic/conf.py @@ -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_]" diff --git a/tests/doc_test/doc_basic/index.rst b/tests/doc_test/doc_basic/index.rst index 539ca0693..de34aac29 100644 --- a/tests/doc_test/doc_basic/index.rst +++ b/tests/doc_test/doc_basic/index.rst @@ -1,5 +1,5 @@ -Welcome to basic test's documentation! -====================================== +TEST DOCUMENT +============= .. story:: Test story :id: ST_001 diff --git a/tests/doc_test/generic_doc/conf.py b/tests/doc_test/generic_doc/conf.py deleted file mode 100644 index 1b74e151a..000000000 --- a/tests/doc_test/generic_doc/conf.py +++ /dev/null @@ -1,32 +0,0 @@ -extensions = ["sphinx_needs"] - -needs_types = [ - { - "directive": "story", - "title": "User Story", - "prefix": "US_", - "color": "#BFD8D2", - "style": "node", - }, - { - "directive": "spec", - "title": "Specification", - "prefix": "SP_", - "color": "#FEDCD2", - "style": "node", - }, - { - "directive": "impl", - "title": "Implementation", - "prefix": "IM_", - "color": "#DF744A", - "style": "node", - }, - { - "directive": "test", - "title": "Test Case", - "prefix": "TC_", - "color": "#DCB239", - "style": "node", - }, -] diff --git a/tests/doc_test/generic_doc/index.rst b/tests/doc_test/generic_doc/index.rst deleted file mode 100644 index cd3a0e0bf..000000000 --- a/tests/doc_test/generic_doc/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -TEST DOCUMENT -============= - -.. spec:: Command line interface - :id: SP_TOO_001 - :status: implemented - :tags: test;test2 - - The Tool awesome shall have a command line interface. - -.. story:: A story - :tags: 1 - -.. needfilter:: - :tags: test;my_test diff --git a/tests/test_basic_doc.py b/tests/test_basic_doc.py index 767e0d96d..f27f93e14 100644 --- a/tests/test_basic_doc.py +++ b/tests/test_basic_doc.py @@ -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]): diff --git a/tests/test_test_doc.py b/tests/test_test_doc.py deleted file mode 100644 index 8dbb8792d..000000000 --- a/tests/test_test_doc.py +++ /dev/null @@ -1,16 +0,0 @@ -from pathlib import Path - -import pytest - - -@pytest.mark.parametrize( - "test_app", - [{"buildername": "html", "srcdir": "doc_test/generic_doc"}], - indirect=True, -) -def test_doc_build_html(test_app): - app = test_app - app.build() - html = Path(app.outdir, "index.html").read_text() - assert "<h1>TEST DOCUMENT" in html - assert "SP_TOO_001" in html