CACTUS Client

This is a set of tools for evaluating CSIP-Aus server test procedures defined at CACTUS Test Definitions.

Development

pip install -e .[dev,test]

Quickstart

Installing

CACTUS requires Python 3.12+

Install the latest version from pypi with: pip install cactus-client

If you're looking to update to the latest version: pip install --upgrade cactus-client

To ensure it's installed properly cactus --help

Working Directory Configuration

CACTUS requires two things:

1. A configuration file - stored either in your home directory or elsewhere (will be created below).
2. A working directory - Where all run outputs will be stored.

Portable Installation

If you're trying to keep CACTUS to a single working directory (and want all of your CACTUS operations to run out of that working directory):

1. Create a new empty directory (eg mkdir cactus-wd)
2. cd cactus-wd
3. cactus setup -l .

Please note - all CACTUS commands will now require you to operate out of the ./cactus-wd/ directory

1. cd cactus-wd
2. cactus server

Global Installation

If you'd like your CACTUS commands to work from any directory (but still have the results all stored in the working directory):

1. Create a new empty directory (eg mkdir cactus-wd)
2. cactus setup -g cactus-wd
3. cactus server

Client/Server Config

Setup the server connections details (dcap refers to your DeviceCapability URI)

1. cactus server dcap https://your.server/dcap
2. cactus server verify true
3. cactus server serca path/to/serca.pem
4. cactus server notification https://cactus.cecs.anu.edu.au/client-notifications/
   • Please note - this will utilise the shared, ANU hosted client-notifications service
   • If you wish to self host - please see client-notifications
5. (Optional) cactus server notification_admin https://localhost:6666/client-notifications/ This can be used in a self hosted context to allow the cactus-client to access the results from the notification server via a different base api uri than the one advertised in the Subscription.notificationURI to the utility server under test.
   • Useful in the context of cactus-client running on a host machine and the cactus-client-notifications server running within e.g. in a pod or docker compose context, on the same network namespace as the utility server under test.
   • If not supplied, this will revert to the value set using cactus server notification

Setup your first client - You will be prompted to populate each field (like below)

1. cactus client myclient1 You should see output like the following

Would you like to create a new client with id 'myclient1' [y/n]: y
What sort of client will this act as? [device/aggregator]: device
File path to PEM encoded client certificate: ./testdevice.crt
File path to PEM encoded client key: ./testdevice.key.decrypt
Auto calculate lfdi/sfdi from certificate? [y/n]: y
lfdi=0F3078CFDDAEE28DC20B95635DC116CC2A6D877F
sfdi=40773583337
Client Private Enterprise Number (PEN) (used for mrid generation): 12345
Client PIN (used for matching EndDevice.Registration): 111115
The DERSetting.setMaxW and DERCapability.rtgMaxW value to use (in Watts): 5000
.cactus.yaml has been updated with a new client.
                         myclient1                                                  
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ key              ┃ value                                         ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ type             │ device                                        │
│ certificate_file │ ./testdevice.crt ✓                            │
│ key_file         │ ./testdevice.key.decrypt ✓                    │
│ lfdi             │ 0F3078CFDDAEE28DC20B95635DC116CC2A6D877F      │
│ sfdi             │ 40773583337                                   │
│ max_watts        │ 5000                                          │
│ pen              │ 123455                                        │
│ pin              │ 111115                                        │
│ user_agent       │ null                                          │
└──────────────────┴───────────────────────────────────────────────┘

To update individual client settings (eg to add a User-Agent header to requests) just specify the parameter to update and new value:

cactus client myclient1 user_agent "cactus client myclient1"

Discovering available tests

The command cactus tests will print out all available test cases...

                                                     Available Test Procedures                                                     
┏━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Id       ┃ Category     ┃ Description                                                ┃ Required Clients                         ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ S-ALL-01 │ Registration │ Discovery with Out-Of-Band registration                    │ 1 client(s) with type(s): any            │
│ S-ALL-02 │ Registration │ Discovery with In-Band Registration for Direct Clients     │ 1 client(s) with type(s): device         │
...

Running your first test

The following command will run the S-ALL-01 test with the client you created earlier:

cactus run S-ALL-01 myclient1

cactus run options

Running all tests automatically

cactus autorun runs all (or a selected subset of) test procedures sequentially, assigning configured clients to each test automatically. It stops at the first failure.

cactus autorun
cactus autorun --include S-ALL-01 S-ALL-02
cactus autorun --include-file my-tests.txt --exclude S-DER-09
cactus autorun --strict --headless --timeout 120

cactus autorun options

Persistent autorun config

All autorun options (except --headless and -c) can be stored in .cactus.yaml under the runner key so you don't need to pass them on every invocation. CLI flags always take precedence over the file.

runner:
  include: []          # list of test IDs to include (empty = all)
  include_file: null   # path to an include-file
  exclude: []          # list of test IDs to skip
  timeout: null        # per-test timeout in seconds
  strict: false        # treat warnings as failures
  allow_skips: false   # permit admin plugins to waive individual steps
  quiet: false          # only show the result panel for failed tests

Viewing the compliance report

After running tests, print a summary of the latest result for each test procedure:

cactus report

This scans the configured output_dir and shows a table of every test procedure with its most recent PASS/FAIL result and timestamp. The same report is printed automatically at the end of cactus autorun.

Admin plugins

Some test procedures include admin_instruction steps — directives for an out-of-band admin agent to perform setup on the server under test (e.g. registering end devices, issuing DER controls). These are handled by plugins loaded at runtime.

Plugins are built using apluggy, a simple async wrapper around pytest's pluggy. See plugins.py for the hookspecs your plugin can implement:

Plugins are discovered automatically via setuptools entry points — no code changes to cactus-client required:

# pyproject.toml
[project.entry-points."cactus_client.admin"]
my-plugin = "my_package.plugin:MyServerPlugin"

Install your plugin alongside cactus-client (pip install -e .) and it will be loaded on next invocation.

Waiving steps your plugin can't set up: You may want to skip certain test steps based on different server use cases (difficulty with state in certain environments like CI/CD). If admin_instruction returns ActionResult.skip_step("reason"), the step's action still runs, but its pass/fail judgement is waived — provided the run was started with --allow-skips / runner.allow_skips. Without that flag, a requested skip is treated as a normal step failure. A run containing waived steps is reported as PASS*, and the reason strings are recorded in .skips in the run's output directory. See the admin_instruction hookspec docstring in plugins.py for the full contract, including why skipping only makes sense on terminal/leaf steps.

Runs with --allow-skips set will not be considered suitable for compliance testing.

Reference implementation: cactus-client-envoy is a full worked example — it implements all three hooks against a local Envoy CSIP-Aus server via direct database access, and includes setup scripts and a complete quickstart guide.