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

cactus_test_definitions/client/procedures/OPT-1-IN-BAND.yaml

@@ -0,0 +1,115 @@
+Description: Connection Point Registration (In Band EndDevice Registration)
+Category: Registration
+Classes:
+  - C
+
+TargetVersions:
+  - v1.2
+  - v1.3-beta/storage
+
+Criteria:
+  checks:
+    - type: all-steps-complete
+      parameters: {}
+    - type: der-capability-contents
+      parameters: {}
+    - type: der-settings-contents
+      parameters: {}
+    - type: der-status-contents
+      parameters: {}
+    - type: end-device-contents
+      parameters:
+        has_connection_point_id: true
+
+Preconditions:
+  immediate_start: true
+  init_actions:
+    - type: set-comms-rate
+      parameters:
+        dcap_poll_seconds: 60
+        edev_list_poll_seconds: 60
+        fsa_list_poll_seconds: 60
+        der_list_poll_seconds: 60 
+        derp_list_poll_seconds: 60
+        mup_post_seconds: 60
+
+Steps:
+  GET-DCAP:
+    event:
+      type: GET-request-received
+      parameters:
+        endpoint: /dcap
+    actions:
+      - type: enable-steps
+        parameters:
+          steps:
+            - GET-EDEV
+            - GET-TM
+      - type: remove-steps
+        parameters:
+          steps:
+            - GET-DCAP
+
+  GET-EDEV:
+    event:
+      type: GET-request-received
+      parameters:
+        endpoint: /edev
+    actions:
+      - type: enable-steps
+        parameters:
+          steps:
+            - POST-EDEV
+      - type: remove-steps
+        parameters:
+          steps:
+            - GET-EDEV
+
+  GET-TM:
+    event:
+      type: GET-request-received
+      parameters:
+        endpoint: /tm
+    actions:
+      - type: remove-steps
+        parameters:
+          steps:
+            - GET-TM
+
+  POST-EDEV:
+    event:
+      type: POST-request-received
+      parameters:
+        endpoint: /edev
+    actions:
+      - type: enable-steps
+        parameters:
+          steps:
+            - GET-DER
+            - PUT-CP
+      - type: remove-steps
+        parameters:
+          steps:
+            - POST-EDEV
+
+  GET-DER:
+    event:
+      type: GET-request-received
+      parameters:
+        endpoint: /edev/1/der
+    actions:
+      - type: remove-steps
+        parameters:
+          steps:
+            - GET-DER
+
+  PUT-CP:
+    event:
+      type: PUT-request-received
+      parameters:
+        endpoint: /edev/1/cp
+    actions:
+      - type: remove-steps
+        parameters:
+          steps:
+            - PUT-CP

cactus_test_definitions/client/procedures/OPT-1-OUT-OF-BAND.yaml

@@ -0,0 +1,101 @@
+Description: Connection Point Registration (Out of Band EndDevice Registration)
+Category: Registration
+Classes:
+  - C
+
+TargetVersions:
+  - v1.2
+  - v1.3-beta/storage
+
+Preconditions:
+  immediate_start: true
+  init_actions:
+    - type: set-comms-rate
+      parameters:
+        dcap_poll_seconds: 60
+        edev_list_poll_seconds: 60
+        fsa_list_poll_seconds: 60
+        der_list_poll_seconds: 60 
+        derp_list_poll_seconds: 60
+        mup_post_seconds: 60
+  actions:
+    - type: register-end-device
+      parameters:
+        registration_pin: 11111 # With checksum is 111115
+        aggregator_lfdi: 3E4F45AB31EDFE5B67E343E5E4562E3100000000 # Trailing PEN digits set to 0
+        aggregator_sfdi: 16726121139
+
+Criteria:
+  checks:
+    - type: all-steps-complete
+      parameters: {}
+    - type: end-device-contents
+      parameters:
+        has_connection_point_id: true
+      
+Steps:
+  GET-DCAP:
+    instructions:
+      - "An EndDevice has already been registered (out of band) with PIN 111115"
+      - "[Aggregator Client Only] LFDI: 3E4F45AB31EDFE5B67E343E5E4562E31XXXXXXXX (The X values will match your client PEN)"
+      - "[Aggregator Client Only] SFDI: 16726121139"
+    event:
+      type: GET-request-received
+      parameters:
+        endpoint: /dcap
+    actions:
+      - type: enable-steps
+        parameters:
+          steps:
+            - GET-EDEV-LIST
+            - GET-TM
+            - GET-DER
+            - PUT-CP
+      - type: remove-steps
+        parameters:
+          steps:
+            - GET-DCAP
+
+  GET-EDEV-LIST:
+    event:
+      type: GET-request-received
+      parameters:
+        endpoint: /edev
+    actions:
+      - type: remove-steps
+        parameters:
+          steps:
+            - GET-EDEV-LIST
+
+  GET-TM:
+    event:
+      type: GET-request-received
+      parameters:
+        endpoint: /tm
+    actions:
+      - type: remove-steps
+        parameters:
+          steps:
+            - GET-TM
+
+  GET-DER:
+    event:
+      type: GET-request-received
+      parameters:
+        endpoint: /edev/1/der
+    actions:
+      - type: remove-steps
+        parameters:
+          steps:
+            - GET-DER
+
+  PUT-CP:
+    event:
+      type: PUT-request-received
+      parameters:
+        endpoint: /edev/1/cp
+    actions:
+      - type: remove-steps
+        parameters:
+          steps:
+            - PUT-CP

cactus_test_definitions/client/procedures/test-procedures.yaml

@@ -0,0 +1,75 @@
+---
+Description: CSIP-AUS Client Test Procedures
+Version: 0.1
+TestProcedures:
+  ALL-01: !include ALL-01.yaml
+  ALL-02: !include ALL-02.yaml
+  ALL-03: !include ALL-03.yaml
+  ALL-03-REJ: !include ALL-03-REJ.yaml
+  ALL-04: !include ALL-04.yaml
+  ALL-05: !include ALL-05.yaml
+  ALL-06: !include ALL-06.yaml
+  ALL-07: !include ALL-07.yaml
+  ALL-08: !include ALL-08.yaml
+  ALL-09: !include ALL-09.yaml
+  ALL-10: !include ALL-10.yaml
+  ALL-11: !include ALL-11.yaml
+  ALL-12: !include ALL-12.yaml
+  ALL-13: !include ALL-13.yaml
+  ALL-14: !include ALL-14.yaml
+  ALL-15: !include ALL-15.yaml
+  ALL-16: !include ALL-16.yaml
+  ALL-17: !include ALL-17.yaml
+  ALL-18: !include ALL-18.yaml
+  ALL-19: !include ALL-19.yaml
+  ALL-20: !include ALL-20.yaml
+  ALL-21: !include ALL-21.yaml
+  ALL-22: !include ALL-22.yaml
+  ALL-23: !include ALL-23.yaml
+  ALL-24: !include ALL-24.yaml
+  ALL-25: !include ALL-25.yaml
+  ALL-26: !include ALL-26.yaml
+  ALL-27: !include ALL-27.yaml
+  ALL-28: !include ALL-28.yaml
+  ALL-29: !include ALL-29.yaml
+  ALL-30: !include ALL-30.yaml
+  DRA-01: !include DRA-01.yaml
+  DRA-02: !include DRA-02.yaml
+  DRD-01: !include DRD-01.yaml
+  DRL-01: !include DRL-01.yaml
+  GEN-01: !include GEN-01.yaml
+  GEN-02: !include GEN-02.yaml
+  GEN-03: !include GEN-03.yaml
+  GEN-04: !include GEN-04.yaml
+  GEN-05: !include GEN-05.yaml
+  GEN-06: !include GEN-06.yaml
+  GEN-07: !include GEN-07.yaml
+  GEN-08: !include GEN-08.yaml
+  GEN-09: !include GEN-09.yaml
+  GEN-10: !include GEN-10.yaml
+  GEN-11: !include GEN-11.yaml
+  GEN-12: !include GEN-12.yaml
+  GEN-13: !include GEN-13.yaml
+  LOA-01: !include LOA-01.yaml
+  LOA-02: !include LOA-02.yaml
+  LOA-03: !include LOA-03.yaml
+  LOA-04: !include LOA-04.yaml
+  LOA-05: !include LOA-05.yaml
+  LOA-06: !include LOA-06.yaml
+  LOA-07: !include LOA-07.yaml
+  LOA-08: !include LOA-08.yaml
+  LOA-09: !include LOA-09.yaml
+  LOA-10: !include LOA-10.yaml
+  LOA-11: !include LOA-11.yaml
+  LOA-12: !include LOA-12.yaml
+  LOA-13: !include LOA-13.yaml
+  MUL-01: !include MUL-01.yaml
+  MUL-02: !include MUL-02.yaml
+  MUL-03: !include MUL-03.yaml
+  OPT-1-IN-BAND: !include OPT-1-IN-BAND.yaml
+  OPT-1-OUT-OF-BAND: !include OPT-1-OUT-OF-BAND.yaml
+  BES-01: !include BES-01.yaml
+  BES-02: !include BES-02.yaml
+  BES-03: !include BES-03.yaml
+  BES-04: !include BES-04.yaml
+

cactus_test_definitions/client/test_procedures.py

@@ -0,0 +1,296 @@
+from dataclasses import dataclass
+from enum import StrEnum
+from importlib import resources
+from pathlib import Path
+from typing import Iterable
+
+import yaml
+import yaml_include
+from cactus_test_definitions.client.actions import Action, validate_action_parameters
+from cactus_test_definitions.client.checks import Check, validate_check_parameters
+from cactus_test_definitions.client.events import Event, validate_event_parameters
+from cactus_test_definitions.csipaus import CSIPAusVersion
+from cactus_test_definitions.errors import TestProcedureDefinitionError
+from cactus_test_definitions.schema import UniqueKeyLoader
+from dataclass_wizard import YAMLWizard
+
+
+class TestProcedureId(StrEnum):
+    """The set of all available test ID's
+
+    This should be kept in sync with the current set of client test procedures loaded from the procedures directory"""
+
+    __test__ = False  # Prevent pytest from picking up this class
+    ALL_01 = "ALL-01"
+    ALL_02 = "ALL-02"
+    ALL_03 = "ALL-03"
+    ALL_03_REJ = "ALL-03-REJ"
+    ALL_04 = "ALL-04"
+    ALL_05 = "ALL-05"
+    ALL_06 = "ALL-06"
+    ALL_07 = "ALL-07"
+    ALL_08 = "ALL-08"
+    ALL_09 = "ALL-09"
+    ALL_10 = "ALL-10"
+    ALL_11 = "ALL-11"
+    ALL_12 = "ALL-12"
+    ALL_13 = "ALL-13"
+    ALL_14 = "ALL-14"
+    ALL_15 = "ALL-15"
+    ALL_16 = "ALL-16"
+    ALL_17 = "ALL-17"
+    ALL_18 = "ALL-18"
+    ALL_19 = "ALL-19"
+    ALL_20 = "ALL-20"
+    ALL_21 = "ALL-21"
+    ALL_22 = "ALL-22"
+    ALL_23 = "ALL-23"
+    ALL_24 = "ALL-24"
+    ALL_25 = "ALL-25"
+    ALL_26 = "ALL-26"
+    ALL_27 = "ALL-27"
+    ALL_28 = "ALL-28"
+    ALL_29 = "ALL-29"
+    ALL_30 = "ALL-30"
+    DRA_01 = "DRA-01"
+    DRA_02 = "DRA-02"
+    DRD_01 = "DRD-01"
+    DRL_01 = "DRL-01"
+    GEN_01 = "GEN-01"
+    GEN_02 = "GEN-02"
+    GEN_03 = "GEN-03"
+    GEN_04 = "GEN-04"
+    GEN_05 = "GEN-05"
+    GEN_06 = "GEN-06"
+    GEN_07 = "GEN-07"
+    GEN_08 = "GEN-08"
+    GEN_09 = "GEN-09"
+    GEN_10 = "GEN-10"
+    GEN_11 = "GEN-11"
+    GEN_12 = "GEN-12"
+    GEN_13 = "GEN-13"
+    LOA_01 = "LOA-01"
+    LOA_02 = "LOA-02"
+    LOA_03 = "LOA-03"
+    LOA_04 = "LOA-04"
+    LOA_05 = "LOA-05"
+    LOA_06 = "LOA-06"
+    LOA_07 = "LOA-07"
+    LOA_08 = "LOA-08"
+    LOA_09 = "LOA-09"
+    LOA_10 = "LOA-10"
+    LOA_11 = "LOA-11"
+    LOA_12 = "LOA-12"
+    LOA_13 = "LOA-13"
+    MUL_01 = "MUL-01"
+    MUL_02 = "MUL-02"
+    MUL_03 = "MUL-03"
+    OPT_1_IN_BAND = "OPT-1-IN-BAND"
+    OPT_1_OUT_OF_BAND = "OPT-1-OUT-OF-BAND"
+
+    # Storage extension
+    BES_01 = "BES-01"
+    BES_02 = "BES-02"
+    BES_03 = "BES-03"
+    BES_04 = "BES-04"
+
+
+@dataclass
+class Step:
+    """A step is a part of the test procedure that waits for some form of event before running a set of actions.
+
+    It's common for a step to activate other "steps" so that the state of the active test procedure can "evolve" in
+    response to client behaviour
+
+    Instructions are out-of-band operations that need performing during the step
+    e.g. disconnect DER from grid, disable power consumption etc.
+    """
+
+    event: Event  # The event to act as a trigger
+    actions: list[Action]  # The actions to execute when the trigger is met
+    instructions: list[str] | None = None
+
+
+@dataclass
+class Preconditions:
+    """Preconditions are run during the "initialization" state that precedes the start of a test. They typically
+    allow for the setup of the test.
+
+    Checks are also included to prevent a client from starting a test before they have correctly met preconditions
+
+    Instructions are out-of-band operations that need performing at the start of the test procedure
+    e.g. attach a load etc.
+
+    If immediate_start is set to True - the "initialization" step will be progressed through immediately so that the
+    client has no opportunity to interact with the server in this state. Any actions will still be executed. Do NOT
+    utilise immediate_start with precondition checks.
+    """
+
+    init_actions: list[Action] | None = None  # To be executed as the runner starts (before anything can occur)
+    immediate_start: bool = False  # If True - a test execution will have NO "pre-start" phase.
+    actions: list[Action] | None = None  # To be executed as the test case "starts" (usually on request of client)
+    checks: list[Check] | None = None  # Will prevent move from "init" state to "started" state of a test if any fail
+    instructions: list[str] | None = None
+
+
+@dataclass
+class Criteria:
+    """Criteria represent the final pass/fail analysis run after a TestProcedure completion. They can consider both
+    the final state of the test system as well as the interactions that happened while it was running"""
+
+    checks: list[Check] | None = None  # These should be run at test procedure finalization to determine pass/fail
+
+
+@dataclass
+class TestProcedure:
+    """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?
+    steps: dict[str, Step]
+    preconditions: Preconditions | None = None  # These execute during "init" and setup the test for a valid start state
+    criteria: Criteria | None = None  # How will success/failure of this procedure be determined?
+
+
+@dataclass
+class TestProcedures(YAMLWizard):
+    """Represents a collection of CSIP-AUS client test procedure descriptions/specifications
+
+    By sub-classing the YAMLWizard mixin, we get access to the class method `from_yaml`
+    which we can use to create an instances of `TestProcedures`.
+    """
+
+    __test__ = False  # Prevent pytest from picking up this class
+
+    description: str
+    version: str
+    test_procedures: dict[str, TestProcedure]
+
+    def _do_action_validate(self, procedure: TestProcedure, procedure_name: str, location: str, action: Action):
+        """Handles the full validation of an action's definition for a parent procedure.
+
+        procedure: The parent TestProcedure for action
+        procedure_name: The name of procedure (used for labelling errors)
+        location: Where in procedure can you find action? (used for labelling errors)
+        action: The action to validate
+
+        raises TestProcedureDefinitionError on failure
+        """
+        validate_action_parameters(procedure_name, location, action)
+
+        # Provide additional "action specific" validation
+        match action.type:
+            case "enable-steps" | "remove-steps":
+                for step_name in action.parameters["steps"]:
+                    if step_name not in procedure.steps.keys():
+                        raise TestProcedureDefinitionError(
+                            f"{procedure_name}.{location}. Refers to unknown step '{step_name}'."
+                        )
+
+    def _validate_actions(self):
+        """Validate actions of test procedure steps / preconditions
+
+        Ensure,
+        - action has the correct parameters
+        - if parameters refer to steps then those steps are defined for the test procedure
+        """
+
+        for test_procedure_name, test_procedure in self.test_procedures.items():
+            # Validate actions in the preconditions
+            if test_procedure.preconditions:
+                if test_procedure.preconditions.actions:
+                    for action in test_procedure.preconditions.actions:
+                        self._do_action_validate(test_procedure, test_procedure_name, "Precondition", action)
+
+                if test_procedure.preconditions.init_actions:
+                    for action in test_procedure.preconditions.init_actions:
+                        self._do_action_validate(test_procedure, test_procedure_name, "Precondition", action)
+
+            # Validate actions that exist on steps
+            for step_name, step in test_procedure.steps.items():
+                for action in step.actions:
+                    self._do_action_validate(test_procedure, test_procedure_name, step_name, action)
+
+    def _validate_checks(self):
+        """Validate checks of test procedures
+
+        Ensure,
+        - check has the correct parameters
+        """
+
+        for test_procedure_name, test_procedure in self.test_procedures.items():
+            if test_procedure.criteria and test_procedure.criteria.checks:
+                for check in test_procedure.criteria.checks:
+                    validate_check_parameters(test_procedure_name, check)
+
+    def _validate_events(self):
+        """Validate events of test procedure steps
+
+        Ensure,
+        - event has the correct parameters
+        """
+
+        for test_procedure_name, test_procedure in self.test_procedures.items():
+            for step_name, step in test_procedure.steps.items():
+                validate_event_parameters(test_procedure_name, step_name, step.event)
+
+    def validate(self):
+        self._validate_actions()
+        self._validate_checks()
+        self._validate_events()
+
+
+class TestProcedureConfig:
+    __test__ = False  # Prevent pytest from picking up this class
+
+    @staticmethod
+    def from_yamlfile(path: Path, skip_validation: bool = False) -> TestProcedures:
+        """Converts a yaml file given by 'path' into a 'TestProcedures' instance.
+
+        Supports parts of the TestProcedures instance being described by external
+        YAML files. These are referenced in the parent yaml file using the `!include` directive.
+
+        skip_validation: If True, the test_procedures.validate() call will not be made
+
+        Example:
+
+            Description: CSIP-AUS Client Test Procedures
+            Version: 0.1
+            TestProcedures:
+              ALL-01: !include ALL-01.yaml
+        """
+        with open(path, "r") as f:
+            yaml_contents = f.read()
+
+        # Modifies the pyyaml's load method to support references to external yaml files
+        # through the `!include` directive.
+        yaml.add_constructor(
+            "!include", constructor=yaml_include.Constructor(base_dir=path.parent), Loader=UniqueKeyLoader
+        )
+
+        # ...because we are using YAMLWizard we need to supply a decoder and a Loader to
+        # use this modified version.
+        test_procedures: TestProcedures = TestProcedures.from_yaml(
+            yaml_contents,
+            decoder=yaml.load,  # type: ignore
+            Loader=UniqueKeyLoader,
+        )
+
+        if not skip_validation:
+            test_procedures.validate()
+
+        return test_procedures
+
+    @staticmethod
+    def from_resource() -> TestProcedures:
+        yaml_resource = resources.files("cactus_test_definitions.client.procedures") / "test-procedures.yaml"
+        with resources.as_file(yaml_resource) as yaml_file:
+            return TestProcedureConfig.from_yamlfile(path=yaml_file)
+
+    @staticmethod
+    def available_tests() -> Iterable[str]:
+        test_procedures: TestProcedures = TestProcedureConfig.from_resource()
+        return test_procedures.test_procedures.keys()

cactus_test_definitions/csipaus.py

@@ -0,0 +1,81 @@
+from enum import StrEnum
+
+
+class CSIPAusVersion(StrEnum):
+    """The various version identifiers for CSIP-Aus. Used for distinguishing what tests are compatible with what
+    released versions CSIP-Aus."""
+
+    RELEASE_1_2 = "v1.2"
+    BETA_1_3_STORAGE = "v1.3-beta/storage"
+
+
+class CSIPAusResource(StrEnum):
+    """Labels for each resource type that the server/client tests might reference. This is not designed to be
+    an exhaustive list of all SEP2 / CSIP-Aus models - only the entities that might have tests applied to them."""
+
+    DeviceCapability = "DeviceCapability"
+
+    Time = "Time"
+
+    MirrorUsagePointList = "MirrorUsagePointList"
+    MirrorUsagePoint = "MirrorUsagePoint"
+
+    EndDeviceList = "EndDeviceList"
+    EndDevice = "EndDevice"
+    ConnectionPoint = "ConnectionPoint"
+    Registration = "Registration"
+
+    FunctionSetAssignmentsList = "FunctionSetAssignmentsList"
+    FunctionSetAssignments = "FunctionSetAssignments"
+
+    DERProgramList = "DERProgramList"
+    DERProgram = "DERProgram"
+
+    DERControlList = "DERControlList"
+    DERControl = "DERControl"
+
+    DefaultDERControl = "DefaultDERControl"
+
+    DERList = "DERList"
+    DER = "DER"
+    DERCapability = "DERCapability"
+    DERSettings = "DERSettings"
+    DERStatus = "DERStatus"
+
+    SubscriptionList = "SubscriptionList"
+    Subscription = "Subscription"
+
+
+class CSIPAusReadingLocation(StrEnum):
+    Site = "Site"  # The reading is measured at the site's connection point
+    Device = "Device"  # The reading is measured at the actual device (behind the meter)
+
+
+class CSIPAusReadingType(StrEnum):
+    """A non exhaustive set of CSIPAus reading types / role flags that can be specified in tests"""
+
+    ActivePowerAverage = "ActivePowerAverage"
+    ActivePowerInstantaneous = "ActivePowerInstantaneous"
+    ActivePowerMaximum = "ActivePowerMaximum"
+    ActivePowerMinimum = "ActivePowerMinimum"
+
+    ReactivePowerAverage = "ReactivePowerAverage"
+    ReactivePowerInstantaneous = "ReactivePowerInstantaneous"
+    ReactivePowerMaximum = "ReactivePowerMaximum"
+    ReactivePowerMinimum = "ReactivePowerMinimum"
+
+    FrequencyAverage = "FrequencyAverage"
+    FrequencyInstantaneous = "FrequencyInstantaneous"
+    FrequencyMaximum = "FrequencyMaximum"
+    FrequencyMinimum = "FrequencyMinimum"
+
+    VoltageSinglePhaseAverage = "VoltageSinglePhaseAverage"
+    VoltageSinglePhaseInstantaneous = "VoltageSinglePhaseInstantaneous"
+    VoltageSinglePhaseMaximum = "VoltageSinglePhaseMaximum"
+    VoltageSinglePhaseMinimum = "VoltageSinglePhaseMinimum"
+
+
+def is_list_resource(resource: CSIPAusResource) -> bool:
+    """Returns true if the specified resource is classified as a list resource (i.e. it supports list query params) and
+    will return an entity with list attributes (eg 'all')"""
+    return resource.name.endswith("List")  # This is a really simple method but it should work

cactus_test_definitions/errors.py

@@ -0,0 +1,15 @@
+class TestProcedureDefinitionError(Exception):
+    __test__ = False  # Prevent pytest from picking up this class
+
+
+class UnresolvableVariableError(Exception):
+    """Raised whenever a NamedVariable cannot be resolved at test execution time (eg: database doesn't have the
+    requisite information)"""
+
+    pass
+
+
+class UnparseableVariableExpressionError(Exception):
+    """Raised whenever a raw string cannot parse to a NamedVariable/Expression"""
+
+    pass