blob: ea09c5053781891f34be93e7225ab93a118ef2e3 [file]
#
# Copyright (c) 2026 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.
#
"""Diagnostic sweep of in-range attribute writes.
TC-IDM-9.1 writes values just *outside* each spec constraint and requires the DUT to
answer CONSTRAINT_ERROR. This sweep is its inverse: it writes values sitting exactly
*on* each bound, values the spec permits, and reports the ones the DUT refuses.
It is a diagnostic, not a certification test. Acceptance of an in-range value is not
universally required: other spec rules can legitimately reject a value that sits on a
constraint bound (Valve DefaultOpenLevel has a min of 1, but with LevelStep 2 the
device must still reject 1), and roughly a quarter of the attribute constraints in the
data model XML are prose-only <desc/> forms this sweep cannot reason about. So a
rejection here is a lead to investigate by hand, not a verdict. The sweep passes
regardless of what it finds unless it is run with --bool-arg fail_on_rejected:true.
Every accepted write mutates the DUT, so each probe restores the attribute's prior
value immediately. Attributes whose value could not be restored are called out
separately in the report: the device is left dirty and should be factory reset before
running anything else against it.
Example with the chip-all-clusters-app:
./scripts/tests/run_python_test.py --factory-reset --app out/linux-x64-all-clusters/chip-all-clusters-app --app-args "--discriminator 1234 --KVS kvs1" --script src/python_testing/TC_AttributeBoundarySweep.py --script-args "--storage-path admin_storage.json --commissioning-method on-network --discriminator 1234 --passcode 20202021 --PICS src/app/tests/suites/certification/ci-pics-values"
"""
import copy
import logging
from dataclasses import dataclass, field
from enum import Enum
from mobly import asserts
from support_modules.idm_support import (COMMAND_CONSTRAINT_DENIED_CLUSTERS, ConstraintProbe, IDMBaseTest, ProbeMode,
WritableAttributeInfo)
import matter.clusters as Clusters
from matter.interaction_model import Status
from matter.testing.decorators import async_test_body
from matter.testing.global_attribute_ids import is_standard_cluster_id
from matter.testing.matter_testing import TestStep
from matter.testing.runner import default_matter_test_main
log = logging.getLogger(__name__)
# A write the DUT accepts changes device state, so the sweep inherits the command
# fuzzing deny list (fabric and credential mutation, network credentials, commissioning
# windows, OTA flows, ACLs, group keys) and adds the clusters whose writable attributes
# reconfigure the transport the sweep itself depends on.
BOUNDARY_SWEEP_DENIED_CLUSTERS = COMMAND_CONSTRAINT_DENIED_CLUSTERS | frozenset({
Clusters.IcdManagement.id,
Clusters.TimeSynchronization.id,
})
class ProbeOutcome(Enum):
"""What the DUT did with a value written at one of its spec constraint bounds."""
# Write succeeded and the attribute read back the written value.
ACCEPTED = 'accepted'
# CONSTRAINT_ERROR on a value the spec permits. This is what the sweep looks for.
REJECTED = 'rejected'
# Write succeeded but the attribute did not take the value (clamped or discarded).
IGNORED = 'ignored'
# Any other status. State-gated writes (INVALID_IN_STATE and friends) land here.
OTHER_STATUS = 'other status'
# The attribute already held the bound value, so the write would prove nothing.
ALREADY_AT_BOUND = 'already at bound'
# An exception was raised while probing, e.g. the value could not be encoded.
ERROR = 'error'
@dataclass
class ProbeResult:
"""Outcome of writing one boundary value to one attribute on one endpoint."""
endpoint_id: int
cluster_name: str
attribute_name: str
probe: ConstraintProbe
outcome: ProbeOutcome
status_name: str = ''
detail: str = ''
# True when the probe changed the attribute and the original value could not be put
# back; the DUT is left holding a value the sweep wrote.
restore_failed: bool = False
# repr() of the value the attribute last read back, from after the probe write or, when
# the restore did not take, from after the restore. None when no read completed. The DUT
# can clamp a write, so this is not necessarily the probe value; it is what the device is
# left holding when restore_failed is set.
stored_repr: str | None = None
@property
def path_str(self) -> str:
return f'EP{self.endpoint_id} {self.cluster_name}.{self.attribute_name}'
@dataclass
class SweepTally:
"""Counts of each outcome plus the results worth printing individually."""
counts: dict[ProbeOutcome, int] = field(default_factory=dict)
notable: list[ProbeResult] = field(default_factory=list)
dirty: list[ProbeResult] = field(default_factory=list)
# path_str of every attribute that produced at least one probe. A collected attribute
# yields no probe when none of its bounds can be turned into a writable value.
probed: set[str] = field(default_factory=set)
class AttributeBoundarySweep(IDMBaseTest):
@property
def default_timeout(self) -> int:
return 900
def desc_AttributeBoundarySweep(self) -> str:
return "[Diagnostic] Write values at spec constraint bounds and report the ones the DUT rejects"
def steps_AttributeBoundarySweep(self) -> list[TestStep]:
return [
TestStep(0, "Commissioning, already done", is_commissioning=True),
TestStep(1, "Walk every endpoint of the DUT and collect the writable attributes of every standard "
"server cluster that carries a machine-readable spec constraint, excluding clusters whose "
"writes could break the test session. Resolve constraint bounds that reference another "
"attribute by reading that attribute from the DUT.",
"A set of attributes and, for each, the values sitting exactly on its constraint bounds."),
TestStep(2, "Write each boundary value to its attribute, read the attribute back to confirm the write "
"took effect, and restore the attribute's prior value.",
"Each write is recorded as accepted, rejected with CONSTRAINT_ERROR, silently ignored, or "
"answered with some other status."),
TestStep(3, "Report the tally and list every attribute that rejected or ignored an in-range value, "
"along with any attribute whose original value could not be restored.",
"A report for manual triage. The sweep does not fail on rejections unless run with "
"--bool-arg fail_on_rejected:true."),
]
@async_test_body
async def test_AttributeBoundarySweep(self) -> None:
self.step(0)
await self.setup_class_helper(allow_pase=False)
self.build_spec_xmls()
self.step(1)
attributes = self._collect_constrained_writable_attributes()
log.info("Found %s writable attributes with constraints", len(attributes))
self.step(2)
results: list[ProbeResult] = []
for attr_info in attributes:
results.extend(await self._probe_attribute(attr_info))
self.step(3)
tally = self._tally(results)
self._log_report(tally, len(attributes))
asserts.assert_greater(len(results), 0,
"No boundary values could be generated for any attribute on this DUT; "
"the sweep exercised nothing")
if self.user_params.get('fail_on_rejected', False):
rejected = [r for r in tally.notable if r.outcome is ProbeOutcome.REJECTED]
if rejected:
asserts.fail("DUT rejected in-range values for: "
+ ', '.join(f'{r.path_str} ({r.probe.description})' for r in rejected))
def _collect_constrained_writable_attributes(self) -> list[WritableAttributeInfo]:
"""Collect the writable attributes carrying spec constraints, deny list applied."""
attributes: list[WritableAttributeInfo] = []
for endpoint_id, endpoint in self.endpoints_tlv.items():
for cluster_id, device_cluster_data in endpoint.items():
if not is_standard_cluster_id(cluster_id):
continue
if cluster_id not in self.xml_clusters or cluster_id not in Clusters.ClusterObjects.ALL_ATTRIBUTES:
continue
if cluster_id in BOUNDARY_SWEEP_DENIED_CLUSTERS:
log.info("Skipping cluster 0x%04X on EP%s: deny-listed for boundary writes", cluster_id, endpoint_id)
continue
xml_cluster = self.xml_clusters[cluster_id]
cluster_class = Clusters.ClusterObjects.ALL_CLUSTERS[cluster_id]
for attribute_id in self.checkable_attributes(cluster_id, device_cluster_data, xml_cluster):
xml_attr = xml_cluster.attributes[attribute_id]
if xml_attr.write_access == Clusters.AccessControl.Enums.AccessControlEntryPrivilegeEnum.kUnknownEnumValue:
continue
if not xml_attr.constraints or not xml_attr.constraints.has_constraints():
continue
attributes.append(WritableAttributeInfo(
endpoint_id=endpoint_id,
cluster_id=cluster_id,
cluster_name=xml_cluster.name,
attribute_id=attribute_id,
attribute_name=xml_attr.name,
attribute=Clusters.ClusterObjects.ALL_ATTRIBUTES[cluster_id][attribute_id],
cluster_class=cluster_class,
datatype=xml_attr.datatype,
constraints=xml_attr.constraints,
))
return attributes
async def _probe_attribute(self, attr_info: WritableAttributeInfo) -> list[ProbeResult]:
"""Write every boundary value of one attribute, restoring state after each."""
# Bounds expressed as a reference to another attribute are resolved against the
# live DUT; an unresolvable reference leaves that bound unset and it is skipped.
# The constraints object belongs to the shared spec XML, so resolve into a copy.
constraints = copy.copy(attr_info.constraints)
if constraints.min_value_ref:
constraints.min_value = await self.resolve_dynamic_constraint(
attr_info.cluster_class, attr_info.endpoint_id, constraints.min_value_ref)
if constraints.max_value_ref:
constraints.max_value = await self.resolve_dynamic_constraint(
attr_info.cluster_class, attr_info.endpoint_id, constraints.max_value_ref)
probes = self.generate_constraint_probes(attr_info, constraints, ProbeMode.AT_BOUND)
results = []
for probe in probes:
try:
probe_result = await self._write_and_restore(attr_info, probe)
# Log every probe as it happens, not just the notable ones: a sweep is only
# useful for triage if the accepted writes are visible alongside the rest.
log.info("%-16s %s: %s", probe_result.outcome.value.upper(), probe_result.path_str,
probe_result.detail)
results.append(probe_result)
except Exception as e:
log.warning("Error probing %s.%s with %s: %s", attr_info.cluster_name, attr_info.attribute_name,
probe.value, e)
results.append(ProbeResult(
endpoint_id=attr_info.endpoint_id, cluster_name=attr_info.cluster_name,
attribute_name=attr_info.attribute_name, probe=probe,
outcome=ProbeOutcome.ERROR, detail=str(e)))
return results
async def _write_and_restore(self, attr_info: WritableAttributeInfo, probe: ConstraintProbe) -> ProbeResult:
"""Write one boundary value, classify the response, and put the old value back."""
def result(outcome: ProbeOutcome, **kwargs) -> ProbeResult:
return ProbeResult(endpoint_id=attr_info.endpoint_id, cluster_name=attr_info.cluster_name,
attribute_name=attr_info.attribute_name, probe=probe, outcome=outcome, **kwargs)
original = await self.read_single_attribute_check_success(
endpoint=attr_info.endpoint_id, cluster=attr_info.cluster_class, attribute=attr_info.attribute)
if original == probe.value:
return result(ProbeOutcome.ALREADY_AT_BOUND, detail=f'attribute already reads {original}')
# A non-timed write to a timed-write attribute is answered with
# NEEDS_TIMED_INTERACTION before the boundary value is ever range-checked, which
# would record the attribute as OTHER_STATUS without testing or restoring it.
timed_request_timeout_ms = None
if attr_info.attribute.must_use_timed_write:
timed_request_timeout_ms = 65535
# The probe write and everything that follows it go inside the try so that the
# finally always gets a chance to put the original value back. A write can reach the
# DUT and still raise here (a response that never arrives, a timeout after the DUT
# applied it), and the read-back can raise on its own; either way the attribute may
# be holding a value the sweep wrote, which must not be left behind unrecorded.
detail = f'{probe.description}, value {probe.value!r}'
outcome = ProbeOutcome.ERROR
status_name = ''
stage = 'write'
# Armed until the attribute is known to be unchanged: nothing has been confirmed
# about the DUT's state yet.
needs_restore = True
restore_failed = False
stored_repr = None
try:
write_result = await self.default_controller.WriteAttribute(
nodeId=self.dut_node_id, attributes=[(attr_info.endpoint_id, attr_info.attribute(probe.value))],
timedRequestTimeoutMs=timed_request_timeout_ms)
status = write_result[0].Status
# Status is an IntEnum and formats as a bare number, so keep the name.
status_name = getattr(status, 'name', str(status))
if status != Status.Success:
# The DUT answered with a failure status, so it did not take the value.
needs_restore = False
if status == Status.ConstraintError:
outcome = ProbeOutcome.REJECTED
else:
outcome = ProbeOutcome.OTHER_STATUS
else:
stage = 'read-back after a successful write'
stored = await self.read_single_attribute_check_success(
endpoint=attr_info.endpoint_id, cluster=attr_info.cluster_class, attribute=attr_info.attribute)
stored_repr = repr(stored)
needs_restore = stored != original
if stored == probe.value:
outcome = ProbeOutcome.ACCEPTED
else:
outcome = ProbeOutcome.IGNORED
detail += f', attribute reads {stored!r}'
except Exception as e:
# The status of a write that raised says nothing about what the DUT did with it.
status_name = ''
detail += f'; {stage} failed: {e}'
finally:
if needs_restore:
try:
restore_result = await self.default_controller.WriteAttribute(
nodeId=self.dut_node_id, attributes=[(attr_info.endpoint_id, attr_info.attribute(original))],
timedRequestTimeoutMs=timed_request_timeout_ms)
restore_status = getattr(restore_result[0].Status, 'name', restore_result[0].Status)
restore_failed = restore_result[0].Status != Status.Success
if not restore_failed:
# A restore write can be answered Success and still be clamped or
# discarded, the same way a probe write can, so the status alone does
# not say the attribute is back to where it started.
restored = await self.read_single_attribute_check_success(
endpoint=attr_info.endpoint_id, cluster=attr_info.cluster_class,
attribute=attr_info.attribute)
restore_failed = restored != original
if restore_failed:
stored_repr = repr(restored)
restore_status = f'write succeeded but attribute reads {stored_repr}'
except Exception as e:
restore_status = e
restore_failed = True
# Neither the write nor the read after it completed, so what the DUT is
# holding is no longer known.
stored_repr = None
if restore_failed:
log.error("Could not restore %s.%s on EP%s to %r: %s", attr_info.cluster_name,
attr_info.attribute_name, attr_info.endpoint_id, original, restore_status)
return result(outcome, status_name=status_name, detail=detail, restore_failed=restore_failed,
stored_repr=stored_repr)
@staticmethod
def _tally(results: list[ProbeResult]) -> SweepTally:
"""Group results by outcome, separating the ones needed to look at."""
tally = SweepTally()
for outcome in ProbeOutcome:
tally.counts[outcome] = 0
for probe_result in results:
tally.counts[probe_result.outcome] += 1
tally.probed.add(probe_result.path_str)
if probe_result.outcome in (ProbeOutcome.REJECTED, ProbeOutcome.IGNORED, ProbeOutcome.OTHER_STATUS,
ProbeOutcome.ERROR):
tally.notable.append(probe_result)
if probe_result.restore_failed:
tally.dirty.append(probe_result)
return tally
@staticmethod
def _log_report(tally: SweepTally, collected_count: int) -> None:
"""Print the sweep report: tally, then every result worth attention."""
total = sum(tally.counts.values())
log.info("=== Boundary sweep: %s probes across %s of %s collected attributes ===",
total, len(tally.probed), collected_count)
for outcome, count in tally.counts.items():
log.info(" %-18s %s", outcome.value, count)
rejected = [r for r in tally.notable if r.outcome is ProbeOutcome.REJECTED]
if rejected:
log.info("--- In-range values the DUT rejected with CONSTRAINT_ERROR ---")
for probe_result in rejected:
log.info(" %s: %s", probe_result.path_str, probe_result.detail)
others = [r for r in tally.notable if r.outcome is not ProbeOutcome.REJECTED]
if others:
log.info("--- Other results worth review ---")
for probe_result in others:
log.info(" %s [%s%s]: %s", probe_result.path_str, probe_result.outcome.value,
f' {probe_result.status_name}' if probe_result.status_name else '', probe_result.detail)
if tally.dirty:
log.error("--- DUT left dirty: original value could not be restored ---")
for probe_result in tally.dirty:
if probe_result.stored_repr is not None:
current = f'now holds {probe_result.stored_repr}'
else:
current = 'holds an unknown value: the read after the write did not complete'
log.error(" %s %s; factory reset before the next run", probe_result.path_str, current)
if __name__ == "__main__":
default_matter_test_main()