🧪 Add snapshot testing for needs data (#1019)

Previously, the validity of needs data was tested by asserting for only specific keys and values.
This commit adds snapshot testing, with https://github.com/tophat/syrupy, to more fully capture the generated data.
This should help to better identify any regressions caused by future changes.

docs/contributing.rst

@@ -56,6 +56,7 @@ installed in an isolated environment by Poetry.
 
 List make targets
 -----------------
+
 **Sphinx-Needs** uses ``make`` to invoke most development related actions.
 
 Use ``make list`` to get a list of available targets.
@@ -92,20 +93,45 @@ To check if all used links in the documentation are still valid, run:
 
 Running Tests
 -------------
-.. hint::
 
-   Please be sure to have the dependencies of the official documentation installed:
+You can either run the tests directly using ``pytest``, in an existing environment:
+
+.. code-block:: bash
+
+   pytest tests/
+
+Or you can use the provided Makefile:
 
 .. code-block:: bash
 
-   pip install -r docs/requirements.txt
    make test
 
+Note some tests use `syrupy <https://github.com/tophat/syrupy>`__ to perform snapshot testing.
+These snapshots can be updated by running:
+
+.. code-block:: bash
+
+   pytest tests/ --snapshot-update
+
+.. hint::
+
+   Please be sure to have the dependencies of the official documentation also installed:
+
+   .. code-block:: bash
+
+      pip install -r docs/requirements.txt
+
 Linting & Formatting
 --------------------
 
-**Sphinx-Needs** uses `black <https://github.com/psf/black>`_ and
-`isort <https://pycqa.github.io/isort/>`_ to format its source code.
+**Sphinx-Needs** uses `pre-commit <https://pre-commit.com/>`__ to run formatting and checking of source code.
+This can be run directly using:
+
+.. code-block:: bash
+
+    pre-commit run --all-files
+
+or via the provided Makefile:
 
 .. code-block:: bash
 

noxfile.py

@@ -14,6 +14,7 @@
 TEST_DEPENDENCIES = [
     "pytest",
     "pytest-xdist",
+    "syrupy",
     "responses",
     "lxml",
     "pyparsing!=3.0.4",

pyproject.toml

@@ -49,6 +49,7 @@ pre-commit = "^2"
 lxml = "^4.6.5"
 pytest = "^7"
 pytest-xdist="*"  # parallelisation
+syrupy = ">=3,<5"
 responses = "^0.22.0"
 requests-mock = ">=1.9.3"
 tabulate = "^0.9.0"

tests/__snapshots__/test_api_configuration.ambr

@@ -0,0 +1,40 @@
+# serializer version: 1
+# name: test_api_add_type[test_app0]
+  list([
+    dict({
+      'color': '#BFD8D2',
+      'directive': 'story',
+      'prefix': 'US_',
+      'style': 'node',
+      'title': 'User Story',
+    }),
+    dict({
+      'color': '#FEDCD2',
+      'directive': 'spec',
+      'prefix': 'SP_',
+      'style': 'node',
+      'title': 'Specification',
+    }),
+    dict({
+      'color': '#DF744A',
+      'directive': 'impl',
+      'prefix': 'IM_',
+      'style': 'node',
+      'title': 'Implementation',
+    }),
+    dict({
+      'color': '#DCB239',
+      'directive': 'test',
+      'prefix': 'TC_',
+      'style': 'node',
+      'title': 'Test Case',
+    }),
+    dict({
+      'color': '#000000',
+      'directive': 'awesome',
+      'prefix': 'AW_',
+      'style': 'cloud',
+      'title': 'Awesome',
+    }),
+  ])
+# ---

tests/__snapshots__/test_basic_doc.ambr

@@ -0,0 +1,161 @@
+# serializer version: 1
+# name: test_build_needs[test_app0]
+  dict({
+    'current_version': '',
+    'project': 'Python',
+    'versions': dict({
+      '': dict({
+        'filters': dict({
+        }),
+        'filters_amount': 0,
+        'needs': dict({
+          'ST_001': dict({
+            'arch': dict({
+            }),
+            'avatar': '',
+            'closed_at': '',
+            'completion': '',
+            'constraints': list([
+            ]),
+            'constraints_passed': True,
+            'constraints_results': dict({
+            }),
+            'content_id': 'ST_001',
+            'created_at': '',
+            'delete': None,
+            'description': '',
+            'docname': 'index',
+            'doctype': '.rst',
+            'duration': '',
+            'external_css': 'external_link',
+            'external_url': None,
+            'full_title': 'Test story',
+            'has_dead_links': '',
+            'has_forbidden_dead_links': '',
+            'hidden': '',
+            'id': 'ST_001',
+            'id_complete': 'ST_001',
+            'id_parent': 'ST_001',
+            'id_prefix': '',
+            'is_external': False,
+            'is_modified': False,
+            'is_need': True,
+            'is_part': False,
+            'jinja_content': None,
+            'layout': '',
+            'links': list([
+            ]),
+            'max_amount': '',
+            'max_content_lines': '',
+            'modifications': 0,
+            'params': '',
+            'parent_need': '',
+            'parent_needs': list([
+            ]),
+            'parent_needs_back': list([
+            ]),
+            'parts': dict({
+            }),
+            'post_template': None,
+            'pre_template': None,
+            'prefix': '',
+            'query': '',
+            'section_name': 'Welcome to basic test’s documentation!',
+            'sections': list([
+              'Welcome to basic test’s documentation!',
+            ]),
+            'service': '',
+            'signature': '',
+            'specific': '',
+            'status': 'open',
+            'style': None,
+            'tags': list([
+            ]),
+            'target_id': 'ST_001',
+            'template': None,
+            'title': 'Test story',
+            'type': 'story',
+            'type_name': 'User Story',
+            'updated_at': '',
+            'url': '',
+            'url_postfix': '',
+            'user': '',
+          }),
+          'US_38823': dict({
+            'arch': dict({
+            }),
+            'avatar': '',
+            'closed_at': '',
+            'completion': '',
+            'constraints': list([
+            ]),
+            'constraints_passed': True,
+            'constraints_results': dict({
+            }),
+            'content_id': 'US_38823',
+            'created_at': '',
+            'delete': None,
+            'description': '',
+            'docname': 'index',
+            'doctype': '.rst',
+            'duration': '',
+            'external_css': 'external_link',
+            'external_url': None,
+            'full_title': 'No ID',
+            'has_dead_links': '',
+            'has_forbidden_dead_links': '',
+            'hidden': '',
+            'id': 'US_38823',
+            'id_complete': 'US_38823',
+            'id_parent': 'US_38823',
+            'id_prefix': '',
+            'is_external': False,
+            'is_modified': False,
+            'is_need': True,
+            'is_part': False,
+            'jinja_content': None,
+            'layout': '',
+            'links': list([
+            ]),
+            'max_amount': '',
+            'max_content_lines': '',
+            'modifications': 0,
+            'params': '',
+            'parent_need': '',
+            'parent_needs': list([
+            ]),
+            'parent_needs_back': list([
+            ]),
+            'parts': dict({
+            }),
+            'post_template': None,
+            'pre_template': None,
+            'prefix': '',
+            'query': '',
+            'section_name': 'Welcome to basic test’s documentation!',
+            'sections': list([
+              'Welcome to basic test’s documentation!',
+            ]),
+            'service': '',
+            'signature': '',
+            'specific': '',
+            'status': 'open',
+            'style': None,
+            'tags': list([
+            ]),
+            'target_id': 'US_38823',
+            'template': None,
+            'title': 'No ID',
+            'type': 'story',
+            'type_name': 'User Story',
+            'updated_at': '',
+            'url': '',
+            'url_postfix': '',
+            'user': '',
+          }),
+        }),
+        'needs_amount': 2,
+      }),
+    }),
+  })
+# ---