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", on_fail = "rollback" } ],
  },
}

With mantisctl

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

Phases and outcomes

• pre gates run before the entity; a failing pre-gate blocks entry (nothing has run).
• post gates run after; a failing post-gate routes per on_fail:
  • fail — mark the deployment failed,
  • rollback — roll back to the previous deployment,
  • handler — run the attached handler action/sequence/solution.

Gates run against the same target(s) as the gated deployment by default. To check a different host, give the test an execution_pool variable so it runs off-target on a Thorax pool.

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).