MACHINE.md — Agent Context for ST Flow Test Harness

This file is structured for consumption by AI agents. It defines the canonical test patterns, expected behaviours, and how to operate the harness programmatically.

Repo Purpose

Canonical test harness for ST Advanced Routing flows. Provides:

Deterministic fixture files with known content and expected transforms
Automated test runner (SFTP upload → route execution → destination verify)
Declarative flow specs (YAML) for idempotent deploy
Pre-flight environment snapshot tooling

Test Case Registry

Each entry defines: fixture file, expected output filename, transform type, verification method.

[
  {
    "id": "compress-txt",
    "fixture": "fixtures/test.txt",
    "fixture_sha256": "see fixtures/CHECKSUMS",
    "expected_output_filename": "test.txt.zip",
    "transform": "Compress",
    "verify_method": "filename_suffix",
    "verify_params": {"suffix": ".zip", "size_relation": "larger"},
    "notes": "ST Compress step appends .zip. Output size > input due to ZIP header overhead on small files."
  },
  {
    "id": "pgp-encrypt-md",
    "fixture": "fixtures/test.md",
    "fixture_sha256": "see fixtures/CHECKSUMS",
    "expected_output_filename": "test.md.pgp",
    "transform": "PgpEncryption",
    "verify_method": "filename_suffix_and_magic_bytes",
    "verify_params": {
      "suffix": ".pgp",
      "magic_bytes_hex": "C1",
      "magic_bytes_offset": 0
    },
    "notes": "ST PgpEncryption appends .pgp. Binary output starts with 0xC1 (OpenPGP packet tag). Cert must have accessLevel=PUBLIC and account ownership."
  },
  {
    "id": "passthrough-csv",
    "fixture": "fixtures/test.csv",
    "fixture_sha256": "see fixtures/CHECKSUMS",
    "expected_output_filename": "test.csv",
    "transform": "None (pass-through)",
    "verify_method": "exact_match",
    "verify_params": {"filename_exact": true, "size_exact": true},
    "notes": "No step matches .csv. File passes through to SendToPartner unchanged."
  },
  {
    "id": "passthrough-pdf",
    "fixture": "fixtures/test.pdf",
    "fixture_sha256": "see fixtures/CHECKSUMS",
    "expected_output_filename": "test.pdf",
    "transform": "None (pass-through)",
    "verify_method": "exact_match",
    "verify_params": {"filename_exact": true, "size_exact": true},
    "notes": "No step matches .pdf. File passes through to SendToPartner unchanged."
  },
  {
    "id": "passthrough-jpg",
    "fixture": "fixtures/test.jpg",
    "fixture_sha256": "see fixtures/CHECKSUMS",
    "expected_output_filename": "test.jpg",
    "transform": "None (pass-through)",
    "verify_method": "exact_match",
    "verify_params": {"filename_exact": true, "size_exact": true},
    "notes": "No step matches .jpg. File passes through to SendToPartner unchanged."
  }
]

Script Interface

run_tests.py

python scripts/run_tests.py [--spec SPEC_YAML] [--env ENV_FILE] [--fixture FIXTURE] [--verbose]

--spec: Path to flow spec YAML. Used to validate environment pre-flight.
--env: Path to env file (default: .env).
--fixture: Run only a single fixture (by id). Omit to run all.
--verbose: Print step-by-step detail.

Exit codes: 0 = all pass, 1 = one or more fail, 2 = environment/config error.

Output format: JSON to stdout (machine-readable), human summary to stderr.

st_env_snapshot.py

python scripts/st_env_snapshot.py --host HOST --port PORT --user USER --pass PASS [--output json|yaml]

Returns a structured snapshot of the live ST environment:

accounts: list of accounts with type and status
partner_sites: list of partner sites with name, type, and partner account
certificates: list of certs with name, type, usage, account, accessLevel
applications: list of AR applications
subscriptions: list of active subscriptions with folder and linked application

Use this output to validate that all resources referenced in a flow spec exist before deploying.

st_deploy.py

python scripts/st_deploy.py --spec SPEC_YAML --host HOST --port PORT --user USER --pass PASS [--dry-run]

Idempotent deploy from spec YAML:

Creates objects that don't exist
Skips objects that exist with matching config
Updates objects that exist with different config (route PUT, step rebuild)
--dry-run: print planned actions without executing

Exit codes: 0 = success, 1 = deploy error, 2 = validation error.

Known Constraints

Route PUT drops step IDs: When updating a route via PUT, omit all step id fields. Including them causes "Cannot attach a route step to another route" error.
conditionType is mandatory: Every step must have explicit conditionType: ALWAYS or EL. Null causes NPE at runtime.
PGP cert must be PUBLIC: Cert accessLevel must be PUBLIC and account must be a real account name. System-level or PRIVATE certs are invisible to the routing engine.
encryptKeyExpressionType: Only ALIAS or EXPRESSION_WILDCARD are valid. NAME is rejected.
Routing latency: Allow 15-30 seconds between upload and destination check. Use ROUTING_TIMEOUT_SEC env var.
Top-level Processed is insufficient: Always verify at destination. A file with no matching step shows Processed at route level but was never transformed or delivered.

Spec Format Reference

See specs/schema.md for full YAML spec format.

5.3 KiB Raw Blame History