Language

DSL reference

What the parser accepts. Indentation doesn’t matter. New files should be .sapi; older .snaptest fixtures still run.

Suite

SUITE: Book Store
DESC: Validates the user API
TIMEOUT: 10
FOLLOW-REDIRECTS: true
URL: https://api.example.com
HEADER Content-Type: application/json
HELPER: Login
  POST: /login
  BODY: {"email": "${EMAIL}", "password": "${PASSWORD}"}
  EXPECT: status == 200
  SAVE: token FROM $.token
SUITE-SETUP: Login
IMPORT: shared.sapi

Test

TEST: Get User
DESC: Fetch one user
TAG: users read
SETUP: Create User
TEARDOWN: Cleanup User
EXAMPLES:
name,email
Ada,ada@example.com
Bob,bob@example.com
  GET: /users/${userId}

Request

Preferred aliases: GET:, POST:, PUT:, PATCH:, DELETE:, HEAD: plus a path. HTTP OPTIONS must be written as REQUEST: OPTIONS /path so it does not collide with suite OPTIONS: {...}.

TEST: List Users
  GET: /users
  QUERY: page=2&limit=10
  PARAM: sort name
  HEADER Accept: application/json
  AUTH: bearer ${TOKEN}
  EXPECT: status == 200

Bodies

  POST: /users
  BODY: {
    "name": "Jane",
    "email": "jane@example.com"
  }

  POST: /login
  BODY: form user=jane&pass=secret

  POST: /ingest
  BODY: raw text/plain hello

  POST: /upload
  FILE: avatar FROM ./photo.png

  POST: /graphql
  GRAPHQL: {"query": "{ user(id: 1) { email } }"}

BODY and DATA are aliases. JSON may be one line or span following lines until the value is complete. FILE and GRAPHQL are CLI-only; the playground reports them as unsupported.

Expect

Check kinds are case-insensitive. Preferred forms use lowercase kinds (json, header, body, status).

EXPECT: status == 200
EXPECT: json $.ok == true BECAUSE "login should succeed"
EXPECT: status == 400 OR status == 401
EXPECT: (status == 400 OR status == 401) AND json $.success == false
EXPECT: status == 200 RETRY 5 ON 5xx BACKOFF 1s

AND / OR combine checks on one line (AND binds tighter). Multiple EXPECT lines all run; failures are reported together. BECAUSE "reason" prefixes that check’s failure message.

Status

Body

JSON

JSONPath subset: $.a.b, $.items[0].id, $.items[*].id, $.items[?(@.status=="open")].

Headers

Other checks

The playground runs status, body, json, and header checks. Schema, XPath, duration, and OpenAPI print a playground error instead of failing silently.

SAVE, SET, and variables

SAVE: userId FROM $.id
SAVE: requestId FROM header X-Request-Id
SET: orderId ${uuid()}

${NAME} expands in URLs, paths, headers, bodies, and expect values. Lookup order: process environment, then --env / auto-discovered suite env / --profile, then SET / SAVE / CALL. Built-in functions: ${uuid()}, ${now()}, ${random.int(min,max)}. Custom functions use CALL. Undefined variables are errors.

The playground seeds ${TOKEN} as playground-token so bearer samples run without an env file. Plugins are CLI-only.

Plugins

A plugin is a Python function loaded from extensions/ (or snapapi.yaml / --plugin). The suite calls it with CALL: signature = crypto.generate_signature(${PAYLOAD}, ${SECRET}) and uses ${signature}. Arguments are explicit. The function returns a value; it does not mutate SnapAPI variables, assert, or issue the HTTP under test. CALL is computation, not a second HTTP engine. Exceptions fail that test as CALL FAILED, not a traceback. There is no IF / FOR / WHILE — see When SnapAPI is not for you and CALL.

WAIT and retries

WAIT: json $.status == "ready" TIMEOUT 10s BACKOFF 0.5s
EXPECT: json $.status == "ready" RETRY 20 BACKOFF 0.5s

WAIT reissues the current request until the check passes or the timeout expires. EXPECT … RETRY retries when the HTTP status is already retryable (for example 5xx with ON 5xx). The playground caps WAIT at 8 seconds so a tab cannot hang.

Modern vs legacy

Both parse. Prefer the left column in new files.