extract matter testing utilities to separate module (#37309)

* extract utilities to separate module and mark them in original module as deprecated

* update build file to include utilities

* Use UserWarning instead of DeprecationWarning; Add type hint decorators for IDE hover visibility

* lint code

* fix incorrect signatures and return values

* adding missing alias and docstrings to utility methods

* fix alias issue

* just update all the places where moved functiones are used

* remove commented out code

* using direct aliases as requested in review

* solit utilities to less general modules

* isort

* rename types.py to matchers.py

* rename type_matches to is_type

* added docstrings and copyright to packages

* style fix

* isort

* point test_testing imports to original module for now

* add doctest for new modules

* this should fix build error, doctests will run when the module is imported anyway

* import modules as modules only; add ToDo to remove aliases in future

* fix imports

Author: asirko-soft

src/python_testing/TC_DA_1_2.py

@@ -43,8 +43,8 @@
 import chip.clusters as Clusters
 from chip.interaction_model import InteractionModelError, Status
 from chip.testing.basic_composition import BasicCompositionTests
-from chip.testing.matter_testing import (MatterBaseTest, TestStep, async_test_body, default_matter_test_main, hex_from_bytes,
-                                         type_matches)
+from chip.testing.conversions import hex_from_bytes
+from chip.testing.matter_testing import MatterBaseTest, TestStep, async_test_body, default_matter_test_main, type_matches
 from chip.tlv import TLVReader
 from cryptography import x509
 from cryptography.exceptions import InvalidSignature

src/python_testing/TC_DA_1_5.py

@@ -40,7 +40,8 @@
 import chip.clusters as Clusters
 from chip import ChipDeviceCtrl
 from chip.interaction_model import InteractionModelError, Status
-from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main, hex_from_bytes, type_matches
+from chip.testing.conversions import hex_from_bytes
+from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main, type_matches
 from chip.tlv import TLVReader
 from cryptography import x509
 from cryptography.hazmat.primitives import hashes

src/python_testing/TC_DA_1_7.py

@@ -41,8 +41,8 @@
 from typing import List, Optional
 
 import chip.clusters as Clusters
-from chip.testing.matter_testing import (MatterBaseTest, TestStep, async_test_body, bytes_from_hex, default_matter_test_main,
-                                         hex_from_bytes)
+from chip.testing.conversions import bytes_from_hex, hex_from_bytes
+from chip.testing.matter_testing import MatterBaseTest, TestStep, async_test_body, default_matter_test_main
 from cryptography.exceptions import InvalidSignature
 from cryptography.hazmat.primitives import hashes
 from cryptography.hazmat.primitives.asymmetric import ec

src/python_testing/TC_DEMTestBase.py

@@ -19,7 +19,7 @@
 
 import chip.clusters as Clusters
 from chip.interaction_model import InteractionModelError, Status
-from chip.testing.matter_testing import utc_time_in_matter_epoch
+from chip.testing.timeoperations import utc_time_in_matter_epoch
 from mobly import asserts
 
 logger = logging.getLogger(__name__)

src/python_testing/TC_DGGEN_2_4.py

@@ -40,9 +40,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError
-from chip.testing.matter_testing import (MatterBaseTest, async_test_body, default_matter_test_main,
-                                         matter_epoch_us_from_utc_datetime, utc_datetime_from_matter_epoch_us,
-                                         utc_datetime_from_posix_time_ms)
+from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main
+from chip.testing.timeoperations import utc_datetime_from_matter_epoch_us, utc_datetime_from_posix_time_ms, utc_time_in_matter_epoch
 from mobly import asserts
 
 logger = logging.getLogger(__name__)
@@ -104,7 +103,7 @@ async def test_TC_DGGEN_2_4(self):
 
             self.print_step("1b", "Write current time to DUT")
             # Get current time in the correct format to set via command.
-            th_utc = matter_epoch_us_from_utc_datetime(desired_datetime=None)
+            th_utc = utc_time_in_matter_epoch(desired_datetime=None)
 
             await self.set_time_in_timesync(th_utc)
 

src/python_testing/TC_TIMESYNC_2_1.py

@@ -42,7 +42,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.testing.matter_testing import (MatterBaseTest, default_matter_test_main, has_attribute, has_cluster,
-                                         run_if_endpoint_matches, utc_time_in_matter_epoch)
+                                         run_if_endpoint_matches)
+from chip.testing.timeoperations import utc_time_in_matter_epoch
 from mobly import asserts
 
 

src/python_testing/TC_TIMESYNC_2_10.py

@@ -43,17 +43,12 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError
-from chip.testing.matter_testing import (MatterBaseTest, SimpleEventCallback, async_test_body, default_matter_test_main,
-                                         utc_time_in_matter_epoch)
+from chip.testing.matter_testing import MatterBaseTest, SimpleEventCallback, async_test_body, default_matter_test_main
+from chip.testing.timeoperations import get_wait_seconds_from_set_time, utc_time_in_matter_epoch
 from chip.tlv import uint
 from mobly import asserts
 
 
-def get_wait_seconds_from_set_time(set_time_matter_us: int, wait_seconds: int):
-    seconds_passed = int((utc_time_in_matter_epoch() - set_time_matter_us)/1000000)
-    return wait_seconds - seconds_passed
-
-
 class TC_TIMESYNC_2_10(MatterBaseTest):
     async def send_set_time_zone_cmd(self, tz: typing.List[Clusters.Objects.TimeSynchronization.Structs.TimeZoneStruct]) -> Clusters.Objects.TimeSynchronization.Commands.SetTimeZoneResponse:
         ret = await self.send_single_cmd(cmd=Clusters.Objects.TimeSynchronization.Commands.SetTimeZone(timeZone=tz), endpoint=self.endpoint)

src/python_testing/TC_TIMESYNC_2_11.py

@@ -43,8 +43,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError
-from chip.testing.matter_testing import (MatterBaseTest, SimpleEventCallback, async_test_body, default_matter_test_main,
-                                         get_wait_seconds_from_set_time, type_matches, utc_time_in_matter_epoch)
+from chip.testing.matter_testing import MatterBaseTest, SimpleEventCallback, async_test_body, default_matter_test_main, type_matches
+from chip.testing.timeoperations import get_wait_seconds_from_set_time, utc_time_in_matter_epoch
 from chip.tlv import uint
 from mobly import asserts
 

src/python_testing/TC_TIMESYNC_2_12.py

@@ -43,8 +43,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError
-from chip.testing.matter_testing import (MatterBaseTest, SimpleEventCallback, async_test_body, default_matter_test_main,
-                                         get_wait_seconds_from_set_time, type_matches, utc_time_in_matter_epoch)
+from chip.testing.matter_testing import MatterBaseTest, SimpleEventCallback, async_test_body, default_matter_test_main, type_matches
+from chip.testing.timeoperations import get_wait_seconds_from_set_time, utc_time_in_matter_epoch
 from chip.tlv import uint
 from mobly import asserts
 

src/python_testing/TC_TIMESYNC_2_2.py

@@ -40,8 +40,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError
-from chip.testing.matter_testing import (MatterBaseTest, async_test_body, compare_time, default_matter_test_main,
-                                         utc_time_in_matter_epoch)
+from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main
+from chip.testing.timeoperations import compare_time, utc_time_in_matter_epoch
 from mobly import asserts
 
 

src/python_testing/TC_TIMESYNC_2_4.py

@@ -40,8 +40,8 @@
 
 import chip.clusters as Clusters
 from chip.interaction_model import InteractionModelError, Status
-from chip.testing.matter_testing import (MatterBaseTest, async_test_body, default_matter_test_main, type_matches,
-                                         utc_time_in_matter_epoch)
+from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main, type_matches
+from chip.testing.timeoperations import utc_time_in_matter_epoch
 from mobly import asserts
 
 

src/python_testing/TC_TIMESYNC_2_5.py

@@ -40,7 +40,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError, Status
-from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main, utc_time_in_matter_epoch
+from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main
+from chip.testing.timeoperations import utc_time_in_matter_epoch
 from mobly import asserts
 
 

src/python_testing/TC_TIMESYNC_2_7.py

@@ -42,8 +42,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError
-from chip.testing.matter_testing import (MatterBaseTest, async_test_body, compare_time, default_matter_test_main, type_matches,
-                                         utc_time_in_matter_epoch)
+from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main, type_matches
+from chip.testing.timeoperations import compare_time, utc_time_in_matter_epoch
 from chip.tlv import uint
 from mobly import asserts
 

src/python_testing/TC_TIMESYNC_2_8.py

@@ -42,8 +42,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError
-from chip.testing.matter_testing import (MatterBaseTest, async_test_body, compare_time, default_matter_test_main, type_matches,
-                                         utc_time_in_matter_epoch)
+from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main, type_matches
+from chip.testing.timeoperations import compare_time, utc_time_in_matter_epoch
 from chip.tlv import uint
 from mobly import asserts
 

src/python_testing/TC_TIMESYNC_2_9.py

@@ -41,8 +41,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError
-from chip.testing.matter_testing import (MatterBaseTest, async_test_body, compare_time, default_matter_test_main, type_matches,
-                                         utc_time_in_matter_epoch)
+from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main, type_matches
+from chip.testing.timeoperations import compare_time, utc_time_in_matter_epoch
 from chip.tlv import uint
 from mobly import asserts
 

src/python_testing/TC_VALCC_4_4.py

@@ -37,8 +37,8 @@
 import chip.clusters as Clusters
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError, Status
-from chip.testing.matter_testing import (MatterBaseTest, TestStep, async_test_body, default_matter_test_main,
-                                         utc_time_in_matter_epoch)
+from chip.testing.matter_testing import MatterBaseTest, TestStep, async_test_body, default_matter_test_main
+from chip.testing.timeoperations import utc_time_in_matter_epoch
 from mobly import asserts
 
 

src/python_testing/TestCommissioningTimeSync.py

@@ -20,7 +20,8 @@
 from chip import ChipDeviceCtrl
 from chip.clusters.Types import NullValue
 from chip.interaction_model import InteractionModelError, Status
-from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main, utc_time_in_matter_epoch
+from chip.testing.matter_testing import MatterBaseTest, async_test_body, default_matter_test_main
+from chip.testing.timeoperations import utc_time_in_matter_epoch
 from mobly import asserts
 
 # We don't have a good pipe between the c++ enums in CommissioningDelegate and python

src/python_testing/TestMatterTestingSupport.py

@@ -22,13 +22,13 @@
 
 import chip.clusters as Clusters
 from chip.clusters.Types import Nullable, NullValue
-from chip.testing.matter_testing import (MatterBaseTest, async_test_body, compare_time, default_matter_test_main,
-                                         get_wait_seconds_from_set_time, parse_matter_test_args, type_matches,
-                                         utc_time_in_matter_epoch)
+from chip.testing.matter_testing import (MatterBaseTest, async_test_body, default_matter_test_main, parse_matter_test_args,
+                                         type_matches)
 from chip.testing.pics import parse_pics, parse_pics_xml
 from chip.testing.taglist_and_topology_test import (TagProblem, create_device_type_list_for_root, create_device_type_lists,
                                                     find_tag_list_problems, find_tree_roots, flat_list_ok, get_all_children,
                                                     get_direct_children_of_root, parts_list_cycles, separate_endpoint_types)
+from chip.testing.timeoperations import compare_time, get_wait_seconds_from_set_time, utc_time_in_matter_epoch
 from chip.tlv import uint
 from mobly import asserts, signals
 

src/python_testing/matter_testing_infrastructure/BUILD.gn

@@ -39,7 +39,9 @@ pw_python_package("chip-testing-module") {
     "chip/testing/basic_composition.py",
     "chip/testing/choice_conformance.py",
     "chip/testing/conformance.py",
+    "chip/testing/conversions.py",
     "chip/testing/global_attribute_ids.py",
+    "chip/testing/matchers.py",
     "chip/testing/matter_asserts.py",
     "chip/testing/matter_testing.py",
     "chip/testing/metadata.py",
@@ -48,6 +50,7 @@ pw_python_package("chip-testing-module") {
     "chip/testing/spec_parsing.py",
     "chip/testing/taglist_and_topology_test.py",
     "chip/testing/tasks.py",
+    "chip/testing/timeoperations.py",
   ]
   tests = [
     "chip/testing/test_metadata.py",

src/python_testing/matter_testing_infrastructure/chip/testing/conversions.py

@@ -0,0 +1,122 @@
+#
+#    Copyright (c) 2025 Project CHIP Authors
+#    All rights reserved.
+#
+#    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.
+#
+
+"""Conversion utilities for Matter testing infrastructure.
+
+This module provides utility functions for converting between different data
+representations commonly used in Matter testing.
+"""
+
+from binascii import hexlify, unhexlify
+
+import chip.clusters as Clusters
+
+
+def bytes_from_hex(hex: str) -> bytes:
+    """ Converts hex string to bytes, handling various formats (colons, spaces, newlines).
+
+    Examples:
+        >>> bytes_from_hex("01:ab:cd")
+        b'\\x01\\xab\\xcd'
+        >>> bytes_from_hex("01 ab cd")
+        b'\\x01\\xab\\xcd'
+        >>> bytes_from_hex("01abcd")
+        b'\\x01\\xab\\xcd'
+        >>> bytes_from_hex("01\\nab\\ncd")
+        b'\\x01\\xab\\xcd'
+    """
+    return unhexlify("".join(hex.replace(":", "").replace(" ", "").split()))
+
+
+def hex_from_bytes(b: bytes) -> str:
+    """ Converts a bytes object to a hexadecimal string.
+
+    This function performs the inverse operation of bytes_from_hex(). It converts
+    a bytes object into a continuous hexadecimal string without any separators.
+
+    Args:
+        b: bytes, the bytes object to convert to hexadecimal
+
+    Returns:
+        str: A string containing the hexadecimal representation of the bytes,
+            using lowercase letters a-f for hex digits
+
+    Examples:
+        >>> hex_from_bytes(b'\\x01\\xab\\xcd')
+        '01abcd'
+        >>> hex_from_bytes(bytes([1, 171, 205]))  # Same bytes, different notation
+        '01abcd'
+    """
+    return hexlify(b).decode("utf-8")
+
+
+def format_decimal_and_hex(number):
+    """ Formats a number showing both decimal and hexadecimal representations.
+
+    Creates a string representation of a number showing both its decimal value
+    and its hex representation in parentheses.
+
+    Args:
+        number: int, the number to format
+
+    Returns:
+        str: A formatted string like "123 (0x7b)"
+
+    Examples:
+        >>> format_decimal_and_hex(123)
+        '123 (0x7b)'
+        >>> format_decimal_and_hex(0)
+        '0 (0x00)'
+        >>> format_decimal_and_hex(255)
+        '255 (0xff)'
+    """
+    return f'{number} (0x{number:02x})'
+
+
+def cluster_id_with_name(id):
+    """ Formats a Matter cluster ID with its name and numeric representation.
+
+    Uses format_decimal_and_hex() for numeric formatting and looks up cluster name from registry.
+    Falls back to "Unknown cluster" if ID not recognized.
+
+    Args:
+        id: int, the Matter cluster identifier
+
+    Returns:
+        str: A formatted string containing the ID and cluster name
+
+    Examples:
+        >>> cluster_id_with_name(6)  # OnOff cluster
+        '6 (0x06) OnOff'
+        >>> cluster_id_with_name(999999)  # Unknown cluster
+        '999999 (0xf423f) Unknown cluster'
+        >>> cluster_id_with_name("invalid")  # Invalid input
+        'HERE IS THE PROBLEM'
+    """
+    if id in Clusters.ClusterObjects.ALL_CLUSTERS.keys():
+        s = Clusters.ClusterObjects.ALL_CLUSTERS[id].__name__
+    else:
+        s = "Unknown cluster"
+    try:
+        return f'{format_decimal_and_hex(id)} {s}'
+    except (TypeError, ValueError):
+        return 'HERE IS THE PROBLEM'
+
+
+if __name__ == "__main__":
+    import doctest
+    doctest.testmod()