Tests & Gates

Tests are a first-class kind of action used only as pre/post gates on an action, sequence, or solution. A gate runs the test during a deployment; a failing gate fails the deployment (and can trigger a rollback or handler). Because a test is an action, it runs through the normal execution path (any executor, any target) — no separate test engine.

Authoring a test

A test lives in tests/<slug>.ncl and looks like an action, with one difference: description is required (so a browse UI shows what it verifies).

{
  slug = "http-health-check",
  name = "HTTP Health Check",
  description = "verifies the endpoint returns 200",
  versions = {
    "1.0.0" = {
      version = "1.0.0",
      executor = "bash",
      payload_type = "command",
      payload = { type = "command", command = "bash", args = ["-c", "curl -fsS #{Url}"] },
    },
  },
}

A test cannot be used as an ordinary sequence step — it is only ever attached as a gate.

Exit-code contract

A test signals its result by exit code: 0 = pass, non-zero = fail. When wrapping a tool (goss, curl, Pester…), translate the tool’s exit codes into this contract in your test script.

Attaching gates

Gates are dual-path: declare them in config-as-code (managed, versioned, portable) or attach them via the API/CLI (tenant-local).

In config-as-code

Add pre_tests / post_tests to a gated entity’s version:

versions = {
  "1.0.0" = {
    version = "1.0.0",
    sequences = [ { sequence = "standard-deploy", version = "=1.0.0" } ],
    post_tests = [ { test = "http-health-check", version = "=1.0.0" } ],
  },
}

With mantisctl

mantisctl test attach --test <test-id> --target-kind solution --target <solution-id> \
  --phase post
mantisctl test detach <attachment-id>

Phases and outcomes

• pre gates run before the entity; a failing pre-gate blocks entry (nothing has run). The exception is a deployment whose failure strategy is ignore_failures, which ignores a failed gate as it ignores any other failure and deploys the gated step anyway. Use stop_on_first_failure or continue_on_failure where a gate has to hold.
• post gates run after; a failing post-gate marks the deployment failed. To roll back or run a compensating handler, set the deployment’s on_failure_action_id, on_failure_sequence_id or on_failure_solution_id — auto-rollback acts on any failure, a failed gate included.

Gates run against the same target(s) as the gated deployment. Off-target execution is a whole-deployment choice, not a per-gate one: set execution_pool_id or execution_thorax_instance_id on the create-deployment request.

Scope

• Solution gates wrap the whole deployment (a final acceptance gate, or a pre precondition).
• Sequence gates wrap a sequence; action gates wrap a single step (a mid-flow checkpoint).