[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