[matter_yamltests] Add a dedicated class to load the yaml, enforce ty…

…pes, validate keywords, and add some implicit rules checking (#24975)

scripts/py_matter_yamltests/BUILD.gn

@@ -29,6 +29,7 @@ pw_python_package("matter_yamltests") {
     "matter_yamltests/__init__.py",
     "matter_yamltests/constraints.py",
     "matter_yamltests/definitions.py",
+    "matter_yamltests/errors.py",
     "matter_yamltests/fixes.py",
     "matter_yamltests/parser.py",
     "matter_yamltests/pics_checker.py",
@@ -38,6 +39,7 @@ pw_python_package("matter_yamltests") {
     "matter_yamltests/pseudo_clusters/clusters/system_commands.py",
     "matter_yamltests/pseudo_clusters/pseudo_cluster.py",
     "matter_yamltests/pseudo_clusters/pseudo_clusters.py",
+    "matter_yamltests/yaml_loader.py",
   ]
 
   python_deps = [ "${chip_root}/scripts/py_matter_idl:matter_idl" ]
@@ -46,6 +48,7 @@ pw_python_package("matter_yamltests") {
     "test_spec_definitions.py",
     "test_pics_checker.py",
     "test_pseudo_clusters.py",
+    "test_yaml_loader.py",
   ]
 
   # TODO: at a future time consider enabling all (* or missing) here to get

scripts/py_matter_yamltests/matter_yamltests/__init__.py

@@ -0,0 +1,19 @@
+#
+#    Copyright (c) 2023 Project CHIP Authors
+#
+#    Licensed under the Apache License, Version 2.0 (the 'License');
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an 'AS IS' BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+import sys
+
+assert sys.version_info >= (
+    3, 7), "Use Python 3.7 or newer for dictionary order guarantees"

scripts/py_matter_yamltests/matter_yamltests/errors.py

@@ -0,0 +1,157 @@
+#
+#    Copyright (c) 2023 Project CHIP Authors
+#
+#    Licensed under the Apache License, Version 2.0 (the 'License');
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an 'AS IS' BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+import yaml
+
+_ERROR_START_TAG = '__error_start__'
+_ERROR_END_TAG = '__error_end__'
+
+
+class TestStepError(Exception):
+    """Raise when a step is malformed."""
+
+    def __init__(self, message):
+        self.step_index = 0
+        self.context = None
+        self.message = message
+
+    def __str__(self):
+        return self.message
+
+    def update_context(self, context, step_index):
+        self.context = yaml.dump(
+            context,
+            default_flow_style=False,
+            sort_keys=False
+        )
+        self.step_index = step_index
+
+    def tag_key_with_error(self, content, target_key):
+        self.__tag_key(content, target_key, _ERROR_START_TAG, _ERROR_END_TAG)
+
+    def __tag_key(self, content, target_key, tag_start, tag_end):
+        # This method replace the key for the dictionary with the tag provided while preserving the order of the dictionary
+        reversed_dictionary = {}
+
+        # Build a reversed dictionary, tagging the target key.
+        for _ in range(len(content)):
+            key, value = content.popitem()
+            if key == target_key:
+                reversed_dictionary[tag_start + key + tag_end] = value
+            else:
+                reversed_dictionary[key] = value
+
+        # Revert back the the dictionary to the original order.
+        for _ in range(len(reversed_dictionary)):
+            key, value = reversed_dictionary.popitem()
+            content[key] = value
+
+
+class TestStepKeyError(TestStepError):
+    """Raise when a key is unknown."""
+
+    def __init__(self, content, key):
+        message = f'Unknown key "{key}"'
+        super().__init__(message)
+
+        self.tag_key_with_error(content, key)
+
+
+class TestStepValueNameError(TestStepError):
+    """Raise when a value name is unknown."""
+
+    def __init__(self, content, key, candidate_keys):
+        message = f'Unknown key: "{key}". Candidates are: "{candidate_keys}"'
+        for candidate_key in candidate_keys:
+            if candidate_key.lower() == key.lower():
+                message = f'Unknown key: "{key}". Did you mean "{candidate_key}" ?'
+                break
+        super().__init__(message)
+
+        self.tag_key_with_error(content, 'name')
+
+
+class TestStepInvalidTypeError(TestStepError):
+    """Raise when the value for a given key is not of the expected type."""
+
+    def __init__(self, content, key, expected_type):
+        if isinstance(expected_type, tuple):
+            expected_name = ''
+            for _type in expected_type:
+                expected_name += _type.__name__ + ','
+            expected_name = expected_name[:-1]
+        else:
+            expected_name = expected_type.__name__
+        received_name = type(content[key]).__name__
+        message = f'Unexpected type. Expecting "{expected_name}", got "{received_name}"'
+        super().__init__(message)
+
+        self.tag_key_with_error(content, key)
+
+
+class TestStepGroupResponseError(TestStepError):
+    """Raise when a test step targeting a group of nodes expects a response."""
+
+    def __init__(self, content):
+        message = 'Group command should not expect a response'
+        super().__init__(message)
+
+        self.tag_key_with_error(content, 'groupId')
+        self.tag_key_with_error(content, 'response')
+
+
+class TestStepVerificationStandaloneError(TestStepError):
+    """Raise when a test step with a verification key is enabled and not interactive."""
+
+    def __init__(self, content):
+        message = 'Step using "verification" key should either set "disabled: true" or "PICS: PICS_USER_PROMPT"'
+        super().__init__(message)
+
+        self.tag_key_with_error(content, 'verification')
+
+
+class TestStepNodeIdAndGroupIdError(TestStepError):
+    """Raise when a test step contains both "nodeId" and "groupId" keys."""
+
+    def __init__(self, content):
+        message = '"nodeId" and "groupId" are mutually exclusive'
+        super().__init__(message)
+
+        self.tag_key_with_error(content, 'nodeId')
+        self.tag_key_with_error(content, 'groupId')
+
+
+class TestStepValueAndValuesError(TestStepError):
+    """Raise when a test step response contains both "value" and "values" keys."""
+
+    def __init__(self, content):
+        message = '"value" and "values" are mutually exclusive'
+        super().__init__(message)
+
+        self.tag_key_with_error(content, 'value')
+        self.tag_key_with_error(content, 'values')
+
+
+class TestStepWaitResponseError(TestStepError):
+    """Raise when a test step is waiting for a particular event (e.g an attribute read) using the
+       wait keyword but also specify a response.
+    """
+
+    def __init__(self, content):
+        message = 'The "wait" key can not be used in conjuction with the "response" key'
+        super().__init__(message)
+
+        self.tag_key_with_error(content, 'wait')
+        self.tag_key_with_error(content, 'response')

scripts/py_matter_yamltests/matter_yamltests/fixes.py

@@ -98,7 +98,7 @@ def convert_yaml_octet_string_to_bytes(s: str) -> bytes:
     return binascii.unhexlify(accumulated_hex)
 
 
-def try_add_yaml_support_for_scientific_notation_without_dot(loader):
+def add_yaml_support_for_scientific_notation_without_dot(loader):
     regular_expression = re.compile(u'''^(?:
      [-+]?(?:[0-9][0-9_]*)\\.[0-9_]*(?:[eE][-+]?[0-9]+)?
     |[-+]?(?:[0-9][0-9_]*)(?:[eE][-+]?[0-9]+)
@@ -111,7 +111,6 @@ def try_add_yaml_support_for_scientific_notation_without_dot(loader):
         u'tag:yaml.org,2002:float',
         regular_expression,
         list(u'-+0123456789.'))
-    return loader
 
 
 # This is a gross hack. The previous runner has a some internal states where an identity match one