tooling: Add docu and change matching function (#933)

Add documentation for the file based rule checks.
Test function checks file name and line number separately from warning message now.

Author: mmr1909

tooling/docs/_tooling/extensions/score_metamodel/tests/README.md

@@ -0,0 +1,43 @@
+# File based rule checks
+
+## Test Function
+The functionality of the Sphinx build rules can be verified with test rst files.
+
+The function *test_check_rules* in *test_rules_file_based.py* is executed for
+each rst file in the directory *rst*.
+It creates a SphinxTestApp and a document source folder with an index.rst file
+that contains a toctree with the given rst file.
+
+It uses the SphinxTestApp to build the documentation and checks for the
+**expected/not expected** warnings.
+
+## Create a test rst file
+To add a new test case create a new rst file in the rst directory.
+The test files can also be organized in a subfolder structure below directory rst.
+The test files are expected to contain the following format:
+
+    #EXPECT: <warning message>
+    #EXPECT-NOT: <warning message>
+
+    <need information>
+
+**\<warning message>**<br>
+Message text which is expected/not expected during the
+                    Sphinx build to be shown.
+                    This message is checked for the Sphinx-Needs directive
+                    specified after the EXPECT/EXPECT-NOT statement.
+
+**\<need information>**<br>
+One or more Sphinx-Needs directives needed for the
+                    Sphinx document build
+
+**Example:**
+
+    EXPECT: std_wp__test__abcd: is missing required option: `status`.
+
+    .. std_wp:: Test requirement
+        :id: std_wp__test__abcd
+
+This example verifies that the warning message
+*std_wp__test__abcd: is missing required option: `status`*
+is shown during the Sphinx build.

tooling/docs/_tooling/extensions/score_metamodel/tests/test_rules_file_based.py

@@ -82,7 +82,9 @@ def _create_app(rst_file: Path) -> SphinxTestApp:
 @dataclass
 class WarningInfo:
     #### Class to hold information about warnings
-    # The class contains the line number and the expected and not expected warnings.
+    # The class contains the filename of the rst file,
+    # line number and the expected and not expected warnings.
+    filename: str = ""
     lineno: int = 0
     expected: list[str] = field(default_factory=list)
     not_expected: list[str] = field(default_factory=list)
@@ -106,6 +108,7 @@ def extract_test_data(rst_file: Path) -> list[WarningInfo] | None:
         for no, line in enumerate(f, start=1):
             if line.startswith(".. "):  # Beginning of new need
                 if test_info:
+                    test_info.filename = rst_file.name
                     test_info.lineno = no
                     statements.append(test_info)
                 test_info = None
@@ -124,6 +127,20 @@ def extract_test_data(rst_file: Path) -> list[WarningInfo] | None:
         return statements
 
 
+def warning_matches(
+    warning_info: WarningInfo, expected_message: str, warnings: list[str]
+) -> bool:
+    ### Checks if any element of the warning list is includes the given warning info.
+    # It returns True if found otherwise False.
+    for warning in warnings:
+        if (
+            f"{warning_info.filename}:{str(warning_info.lineno)}" in warning
+            and expected_message in warning
+        ):
+            return True
+    return False
+
+
 @pytest.mark.parametrize("rst_file", RST_FILES)
 def test_check_rules(
     rst_file: str, sphinx_app_setup: Callable[[Path], SphinxTestApp]
@@ -137,14 +154,13 @@ def test_check_rules(
     app: SphinxTestApp = sphinx_app_setup(RST_DIR / rst_file)
     os.chdir(app.srcdir)  # Change working directory to the source directory
     app.build()
-    warn_text: str = app.warning.getvalue()
+    warnings = app.warning.getvalue().splitlines()
     for test in test_data:
         for expected in test.expected:
-            assert (
-                f"{Path(rst_file).name}:{test.lineno}: WARNING: {expected}" in warn_text
-            ), f"Expected warning: {[expected]} not found"
+            assert warning_matches(
+                test, expected, warnings
+            ), f"Expected warning: {expected} not found"
         for not_expected in test.not_expected:
-            assert (
-                f"{Path(rst_file).name}:{test.lineno}: WARNING: {not_expected}"
-                not in warn_text
-            ), f"Unexpected warning: {[not_expected]} found"
+            assert not warning_matches(
+                test, not_expected, warnings
+            ), f"Unexpected warning: {not_expected} found"