Documentation / DSL guide

LANGUAGE REFERENCE

ReTTP DSL guide

Learn the suite structure, response contracts, variables, and deterministic execution model behind ReTTP verification runs.

01 · STRUCTURE

One suite, clear responsibilities.

A suite may contain one optional core, named pipelines, and standalone tests. Every test has exactly one request followed by one expectation block.

example.rttpUTF-8 · comments supported
core {
  test "authenticate" {
    request POST "/session"
    expect { status = 200 body { token: string -> ACCESS_TOKEN } }
  }
}

pipeline "resource lifecycle" {
  test "create" {
    request POST "/items" { body { name = "sample" } }
    expect { status = 201 body { id: integer -> ITEM_ID } }
  }
  test "read" { request GET "/items/${ITEM_ID}" expect { status = 200 } }
}
core

Runs first; its captures are available to later blocks.

pipeline

Groups dependent tests. Captures flow only forward inside it.

test

Defines one HTTP request and its response contract.

02 · BUILDING BLOCKS

Express requests and contracts.

REQUEST

Relative HTTP calls

Use GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS with headers, query values, and JSON bodies.

EXPECT

Response assertions

Assert status, case-insensitive headers, exact or partial text, empty bodies, and typed JSON.

VARIABLES

Safe interpolation

Use ${NAME} from environment values, CLI variables, or earlier captures. Invalid references never execute.

CAPTURES

Typed hand-off

Capture typed fields with token: string -> TOKEN; changes commit only after a full pass.

03 · EXECUTION ALGORITHM

Validate, then execute in order.

ReTTP blocks malformed suites and invalid references before any request reaches an environment, then follows deterministic fail rules.

  1. 01
    Parse & validate

    Lexical, syntax, and semantic diagnostics are collected where recovery is safe. Invalid suites stop without network execution.

  2. 02
    Run the core

    The optional core always runs first. A failure aborts the entire suite because later checks may depend on it.

  3. 03
    Process pipelines

    Pipelines run in source order. A failure skips later steps only in the same pipeline; subsequent blocks still run.

  4. 04
    Finish standalone tests

    Standalone failures are recorded but do not stop other tests. Reports are emitted with redacted output.