cactus-test-definitions 1.6.0__py3-none-any.whl

cactus_test_definitions/server/procedures/S-ALL-04.yaml

@@ -0,0 +1,137 @@
+Description: Support for Multiple End Clients
+Category: Registration
+Classes:
+ - A
+
+TargetVersions:
+ - v1.2
+
+Preconditions:
+  required_clients:
+    - id: CLIENT-A
+    - id: CLIENT-B
+  
+Steps:
+  - id: CLIENT-A PRECONDITION
+    repeat_until_pass: true
+    client: CLIENT-A
+    instructions:
+      - Create at least 5 DERControls for CLIENT-A
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - DERControl
+    checks:
+      - type: end-device 
+        parameters:
+          matches_client: true 
+      - type: der-control
+        parameters:
+          minimum_count: 5
+
+  - id: CLIENT-B PRECONDITION 
+    repeat_until_pass: true
+    client: CLIENT-B
+    instructions:
+      - Create at least 5 DERControls for CLIENT-B
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - DERControl
+    checks:
+      - type: end-device 
+        parameters:
+          matches_client: true 
+      - type: der-control
+        parameters:
+          minimum_count: 5
+
+  - id: CLIENT-A DISCOVER MUPS
+    repeat_until_pass: true
+    client: CLIENT-A
+    instructions:
+      - MirrorUsagePoints for CLIENT-A must be initially empty.
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - MirrorUsagePoint
+    checks:
+      - type: mirror-usage-point
+        parameters:
+          matches: false # This will only match an empty list
+
+  - id: CLIENT-B DISCOVER MUPS
+    repeat_until_pass: true
+    client: CLIENT-B
+    instructions:
+      - MirrorUsagePoints for CLIENT-B must be initially empty.
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - MirrorUsagePoint
+    checks:
+      - type: mirror-usage-point
+        parameters:
+          matches: false # This will only match an empty list
+
+  - id: CLIENT-A CREATE MUPS
+    client: CLIENT-A
+    action: 
+      type: upsert-mup
+      parameters:
+        mup_id: mupa
+        location: Device
+        reading_types: 
+          - ActivePowerAverage
+          - VoltageSinglePhaseAverage
+    checks:
+      - type: mirror-usage-point
+        parameters:
+          matches: true
+          location: Device
+          reading_types: 
+            - ActivePowerAverage
+            - VoltageSinglePhaseAverage  
+
+  - id: CLIENT-B CREATE MUPS
+    client: CLIENT-B
+    action: 
+      type: upsert-mup
+      parameters:
+        mup_id: mupb
+        location: Device
+        reading_types: 
+          - ActivePowerAverage
+          - VoltageSinglePhaseAverage
+    checks:
+      - type: mirror-usage-point
+        parameters:
+          matches: true
+          location: Device
+          reading_types: 
+            - ActivePowerAverage
+            - VoltageSinglePhaseAverage  
+
+  - id: CLIENT-A SEND READINGS
+    client: CLIENT-A
+    action: 
+      type: insert-readings
+      parameters:
+        mup_id: mupa
+        values:
+          ActivePowerAverage: [1000, 1234, 0, -4567]
+          VoltageSinglePhaseAverage: [241.1, 232.2, 233.9, 244.1]
+    
+  - id: CLIENT-B SEND READINGS
+    client: CLIENT-B
+    action: 
+      type: insert-readings
+      parameters:
+        mup_id: mupb
+        values:
+          ActivePowerAverage: [2000, 2234, 0, -8567]
+          VoltageSinglePhaseAverage: [243.1, 233.2, 234.9, 240]

cactus_test_definitions/server/procedures/S-ALL-05.yaml

@@ -0,0 +1,111 @@
+Description: Authorisation
+Category: Registration
+Classes:
+ - A
+
+TargetVersions:
+ - v1.2
+
+Preconditions:
+  required_clients:
+    - id: CLIENT-A
+      client_type: device
+    - id: CLIENT-B
+      client_type: device
+  
+Steps:
+  - id: (A) PRECONDITION
+    repeat_until_pass: true
+    client: CLIENT-A
+    instructions:
+      - Create an EndDevice registration for CLIENT-A (or rerun S-ALL-02 / S-ALL-03).
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - EndDevice
+          - DERControlList
+          - DER
+    checks:
+      - type: end-device 
+        parameters:
+          matches_client: true 
+
+  - id: (B) PRECONDITION
+    repeat_until_pass: true
+    client: CLIENT-B
+    instructions:
+      - Create an EndDevice registration for CLIENT-B (or rerun S-ALL-02 / S-ALL-03).
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - EndDevice
+          - DERControlList
+          - DER
+    checks:
+      - type: end-device 
+        parameters:
+          matches_client: true 
+
+  - id: (A-B) AUTH EndDeviceList
+    client: CLIENT-A
+    use_client_context: CLIENT-B 
+    action: 
+      type: refresh-resource
+      parameters:
+        resource: EndDeviceList
+        expect_rejection: true
+
+  - id: (A-B) AUTH DerControlList
+    client: CLIENT-A
+    use_client_context: CLIENT-B 
+    action: 
+      type: refresh-resource
+      parameters:
+        resource: DERControlList
+        expect_rejection: true
+
+  - id: (A-B) AUTH DERStatus
+    client: CLIENT-A
+    use_client_context: CLIENT-B 
+    action: 
+      type: upsert-der-status
+      parameters:
+        genConnectStatus: 1
+        expect_rejection: true
+
+  - id: (A-B) AUTH MirrorUsagePoint
+    client: CLIENT-A
+    use_client_context: CLIENT-B 
+    action: 
+      type: upsert-mup
+      parameters:
+        expect_rejection: true
+        mup_id: mupa
+        location: Device
+        reading_types: 
+          - ActivePowerAverage
+          - VoltageSinglePhaseAverage
+
+  - id: (A) OK EndDeviceList
+    client: CLIENT-A
+    action: 
+      type: refresh-resource
+      parameters:
+        resource: EndDeviceList
+    checks:
+      - type: end-device 
+        parameters:
+          matches_client: true 
+
+  - id: (A) DISALLOW ACCESS
+    repeat_until_pass: true
+    instructions:
+      - Remove EndDevice entry for ClientA (or disallow access).
+    client: CLIENT-A
+    action: 
+      type: refresh-resource
+      parameters:
+        resource: EndDeviceList
+        expect_rejection_or_empty: true

cactus_test_definitions/server/procedures/S-OPT-01.yaml

@@ -0,0 +1,42 @@
+Description: Discovery Rejecting In-Band Registration
+Category: Registration
+Classes:
+ - A
+
+TargetVersions:
+ - v1.2
+
+Preconditions:
+  required_clients:
+    - id: client
+  
+Steps:
+  - id: PRECONDITION
+    repeat_until_pass: true
+    instructions:
+      - Create an EndDevice registration for client (or rerun S-ALL-02 / S-ALL-03).
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - DeviceCapability
+          - Time
+          - MirrorUsagePointList
+          - EndDevice
+          - DER
+    checks:
+      - type: end-device # This will be the check that will block UNTIL there is an existing EndDevice registration
+        parameters:
+          matches_client: true 
+
+  - id: REGISTER AGAIN
+    action: 
+      type: insert-end-device
+      parameters: 
+        expect_rejection: true
+    checks:
+      - type: end-device
+        parameters:
+          matches_client: true 
+
+  

cactus_test_definitions/server/procedures/S-OPT-02.yaml

@@ -0,0 +1,40 @@
+Description: Incorrect Connection Point Registration
+Category: Registration
+Classes:
+ - A
+
+TargetVersions:
+ - v1.2
+
+Preconditions:
+  required_clients:
+    - id: client
+  
+Steps:
+  - id: PRECONDITION
+    repeat_until_pass: true
+    instructions:
+      - Create an EndDevice registration for client (or rerun S-ALL-02 / S-ALL-03).
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - DeviceCapability
+          - Time
+          - MirrorUsagePointList
+          - EndDevice
+          - DER
+    checks:
+      - type: end-device # This will be the check that will block UNTIL there is an existing EndDevice registration
+        parameters:
+          matches_client: true 
+
+  - id: SEND BAD CONNECTION POINT ID
+    action: 
+      type: upsert-connection-point
+      parameters: 
+        connectionPointId: NOTAVALIDID
+        expect_rejection: true
+    
+
+  

cactus_test_definitions/server/procedures/S-OPT-03.yaml

@@ -0,0 +1,44 @@
+Description: Connection Point Registration
+Category: Registration
+Classes:
+ - A
+
+TargetVersions:
+ - v1.2
+
+Preconditions:
+  required_clients:
+    - id: client
+  
+Steps:
+  - id: PRECONDITION
+    repeat_until_pass: true
+    instructions:
+      - Create an EndDevice registration for client (or rerun S-ALL-02 / S-ALL-03).
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - DeviceCapability
+          - Time
+          - MirrorUsagePointList
+          - EndDevice
+          - DER
+    checks:
+      - type: end-device # This will be the check that will block UNTIL there is an existing EndDevice registration
+        parameters:
+          matches_client: true 
+
+  - id: SEND CONNECTION POINT ID
+    action: 
+      type: upsert-connection-point
+      parameters: 
+        connectionPointId: "1234567890" # A valid NMI (in the testing range)
+    checks:
+      - type: discovered
+        parameters:
+          links:
+            - ConnectionPoint
+    
+
+  

cactus_test_definitions/server/procedures/S-OPT-04.yaml

@@ -0,0 +1,32 @@
+Description: Client Registration and PIN Validation
+Category: Registration
+Classes:
+ - A
+
+TargetVersions:
+ - v1.2
+
+Preconditions:
+  required_clients:
+    - id: client
+  
+Steps:
+  - id: MATCH PIN
+    repeat_until_pass: true
+    instructions:
+      - Create an EndDevice (with RegistrationLink) registration for client (or rerun S-ALL-02 / S-ALL-03).
+    action: 
+      type: discovery
+      parameters:
+        resources:
+          - Registration
+    checks:
+      - type: end-device # This will be the check that will block UNTIL there is an existing EndDevice registration
+        parameters:
+          matches_client: true 
+          matches_pin: true
+
+  
+    
+
+  

cactus_test_definitions/server/test_procedures.py

@@ -0,0 +1,122 @@
+from dataclasses import dataclass
+from enum import StrEnum
+from importlib import resources
+
+import yaml
+from cactus_test_definitions.csipaus import CSIPAusVersion
+from cactus_test_definitions.schema import UniqueKeyLoader
+from cactus_test_definitions.server.actions import Action
+from cactus_test_definitions.server.checks import Check
+from dataclass_wizard import LoadMeta, YAMLWizard
+
+
+class TestProcedureId(StrEnum):
+    """The set of all available test ID's
+
+    This should be kept in sync with the current set of test procedures loaded from the procedures directory"""
+
+    __test__ = False  # Prevent pytest from picking up this class
+    S_ALL_01 = "S-ALL-01"
+    S_ALL_02 = "S-ALL-02"
+    S_ALL_03 = "S-ALL-03"
+    S_ALL_04 = "S-ALL-04"
+    S_ALL_05 = "S-ALL-05"
+    S_OPT_01 = "S-OPT-01"
+    S_OPT_02 = "S-OPT-02"
+    S_OPT_03 = "S-OPT-03"
+    S_OPT_04 = "S-OPT-04"
+
+
+class ClientType(StrEnum):
+    DEVICE = "device"  # This is a direct device client - i.e. the cert will match a SPECIFIC EndDevice
+    AGGREGATOR = "aggregator"  # This is an aggregator client - i.e. the cert can manage MANY EndDevices
+
+
+@dataclass
+class RequiredClient:
+    """A RequiredClient is a way for a test to assert that it needs a specific client type or set of clients. The id
+    will be used internally within a test to reference a specific client"""
+
+    id: str  # How this client will be referred to within the step's of the test
+    client_type: ClientType | None = None  # If set - the client type that is required
+
+
+@dataclass
+class Step:
+    """A step is an action for a client to execute and then a series of checks to validate the results. If the action
+    raises an exception OR any of the checks fail, this step will marked as failed and the test will be aborted.
+
+    Actions might represent a single operation or they may represent a series of polls/checks over a period of time.
+    """
+
+    id: str  # Descriptive identifier for this step (must be unique)
+    action: Action  # The action to execute when the step starts
+    client: str | None = None  # The RequiredClient.id that will execute this step. If None - use the 0th client.
+    use_client_context: str | None = (
+        None  # Specify to allow a request to execute with clientX using the context of clientY
+    )
+    checks: list[Check] | None = None  # The checks (if any) to execute AFTER action completes to determine success
+    instructions: list[str] | None = None  # Text to display while this step executes
+
+    repeat_until_pass: bool = False  # If True - failing checks will cause this step to re-execute until successful
+
+
+@dataclass
+class Preconditions:
+    """Preconditions are a way of setting up the test / server before the test begins.
+
+    Instructions are out-of-band information to show until the preconditions are all met.
+
+    If any checks are required - they will be polled regularly until ALL pass. For each check poll, a discovery
+    will be run to ensure data is available.
+    """
+
+    required_clients: list[RequiredClient]  # What client(s) need to be supplied to run this test procedure
+
+
+@dataclass
+class TestProcedure(YAMLWizard):
+    """Top level object for collecting everything relevant to a single TestProcedure"""
+
+    __test__ = False  # Prevent pytest from picking up this class
+    description: str  # Metadata from test definitions
+    category: str  # Metadata from test definitions
+    classes: list[str]  # Metadata from test definitions
+    target_versions: list[CSIPAusVersion]  # What version(s) of csip-aus is this test targeting?
+    preconditions: Preconditions
+    steps: list[Step]  # What behavior will the test procedure be evaluating?
+
+
+LoadMeta(raise_on_unknown_json_key=True).bind_to(TestProcedure)
+
+
+def parse_test_procedure(yaml_contents: str) -> TestProcedure:
+    """Given a YAML string - parse a TestProcedure.
+
+    This will ensure the YAML parser will use all the "strict" extensions to reduce the incidence of errors"""
+
+    return TestProcedure.from_yaml(
+        yaml_contents,
+        decoder=yaml.load,  # type: ignore
+        Loader=UniqueKeyLoader,
+    )
+
+
+def get_yaml_contents(test_procedure_id: TestProcedureId) -> str:
+    """Finds the YAML contents for the TestProcedure with the specified TestProcedureId"""
+    yaml_resource = resources.files("cactus_test_definitions.server.procedures") / f"{test_procedure_id}.yaml"
+    with resources.as_file(yaml_resource) as yaml_file:
+        with open(yaml_file, "r") as f:
+            yaml_contents = f.read()
+            return yaml_contents
+
+
+def get_test_procedure(test_procedure_id: TestProcedureId) -> TestProcedure:
+    """Gets the TestProcedure with the nominated ID by loading its definition from disk"""
+    yaml_contents = get_yaml_contents(test_procedure_id)
+    return parse_test_procedure(yaml_contents)
+
+
+def get_all_test_procedures() -> dict[TestProcedureId, TestProcedure]:
+    """Gets every TestProcedure, keyed by their TestProcedureId"""
+    return {tp_id: get_test_procedure(tp_id) for tp_id in TestProcedureId}

cactus_test_definitions/server/validate.py

@@ -0,0 +1,30 @@
+from cactus_test_definitions.errors import TestProcedureDefinitionError
+from cactus_test_definitions.server.actions import validate_action_parameters
+from cactus_test_definitions.server.checks import validate_check_parameters
+from cactus_test_definitions.server.test_procedures import (
+    TestProcedure,
+    TestProcedureId,
+)
+
+
+def validate_test_procedure(test_procedure: TestProcedure, test_procedure_id: TestProcedureId):
+    # Check preconditions
+    if not test_procedure.preconditions.required_clients:
+        raise TestProcedureDefinitionError(
+            f"{test_procedure_id} has no RequiredClients element. At least 1 entry required"
+        )
+    required_clients_by_id = dict(((rc.id, rc) for rc in test_procedure.preconditions.required_clients))
+
+    for step in test_procedure.steps:
+        validate_action_parameters(test_procedure_id, step.id, step.action)
+
+        # Validate step checks
+        if step.checks:
+            for check in step.checks:
+                validate_check_parameters(test_procedure_id, check)
+
+        # Ensure client exists
+        if step.client is not None and step.client not in required_clients_by_id:
+            raise TestProcedureDefinitionError(
+                f"{test_procedure_id} reference client {step.client} that isn't listed in RequiredClients."
+            )