Skip to main content
RELAMPO
Documentation
ENES

Reference

This page documents the current practical YAML structure used by Relampo, based on the active RELAMPO-YAML-SPEC.md maintained in the editor repo.

Test block​

The test section defines script metadata.

test:
  name: "User API Load Test"
  description: "Load validation for the user endpoints"
  version: "1.0"
  author: "QA Team"
  tags:
    - api
    - users

Fields​

  • name (required): descriptive test name
  • description (optional): longer context for maintainers
  • version (optional): script version
  • author (optional): author or owning team
  • tags (optional): list of labels for organization

Variables​

The variables section defines reusable values available across the file.

variables:
  base_url: "https://api.example.com"
  api_key: "secret-key"
  timeout: "30s"
  max_retries: 3

Reference variables using {{variable_name}} anywhere the engine supports interpolation.

Data source​

Relampo supports a shared data_source block for structured test data. A data_source can also be used as a step when values must be bound at a specific point in the flow.

data_source:
  type: csv
  file: "data/users.csv"
  mode: per_vu
  strategy: sequential
  bind:
    email: email_column
    password: password_column
  on_exhausted: recycle

Fields​

  • type: source type, csv or txt
  • file: source file path
  • mode:
    • per_vu: each virtual user advances its own cursor
    • shared: all users consume the same source
    • per_worker: row assignment is stable by VU index
  • strategy:
    • sequential: consume rows in order
    • random: pick rows randomly
    • unique: use rows without repeating until exhausted
  • variable_names: comma-separated string or YAML list for positional column binding
  • bind: variable-to-field assignment
  • on_exhausted: recycle or stop

HTTP defaults​

The http_defaults block defines baseline HTTP behavior inherited by requests unless overridden.

http_defaults:
  base_url: "https://api.example.com"
  timeout: "30s"
  follow_redirects: true
  max_redirects: 5
  headers:
    Accept: "application/json"
    User-Agent: "Relampo/2.0"
    Authorization: "Bearer {{token}}"

Scenarios​

The scenarios array defines one or more executable flows.

scenarios:
  - name: "User Flow"
    load:
      type: constant
      users: 10
      duration: "5m"
    steps:
      - request: ...

Each scenario usually contains:

  • name
  • load
  • steps
  • optional runtime controls such as cookies, cache, and error policy

Load models​

Constant​

load:
  type: constant
  users: 50
  duration: "10m"
  ramp_up: "30s"

Ramp​

load:
  type: ramp
  start_users: 1
  end_users: 100
  duration: "10m"
  step_users: 10
  step_duration: "1m"

Stages​

load.type: stages defines a dynamic VU plan over time.

load:
  type: stages
  duration: "10m"
  stages:
    - type: constant
      users: 10
      duration: "2m"
    - type: ramp_up
      start_users: 10
      end_users: 50
      duration: "3m"
    - type: ramp_down
      start_users: 50
      end_users: 0
      duration: "5m"

stages requires a top-level load.duration, a non-empty stages list, and stage types of constant, ramp_up, or ramp_down. Stage durations must cover the full load duration without gaps or overlap.

Scenario runtime options​

scenarios:
  - name: "Complete Scenario"
    load:
      type: constant
      users: 10
      duration: "5m"

    cookies:
      mode: auto
      persist_across_iterations: true

    cache_manager:
      enabled: true
      max_size_mb: 50

    error_policy:
      on_4xx: continue
      on_5xx: retry
      on_timeout: stop

    steps:
      - request: ...

These settings control browser-like behavior and failure handling at the scenario level.

Steps and requests​

A scenario is executed through ordered steps.

Supported step types include:

  • HTTP requests: request, get, post, put, delete, patch, head, options
  • Data and database: data_source, sql
  • Containers and controllers: group, controller, transaction, parallel, one_time, balanced
  • Flow control: if, loop, retry
  • Validation: assertions
  • Pauses: think_time

Short request form​

steps:
  - get: /api/users
  - post: /api/users
  - put: /api/users/123
  - delete: /api/users/123
  - patch: /api/users/123

Full request form​

steps:
  - request:
      name: "Get Users"
      method: GET
      url: /api/users
      headers:
        Authorization: "Bearer {{token}}"
        Content-Type: "application/json"

In full form, a request can include:

  • name
  • method
  • url
  • headers
  • query params
  • body or payload
  • assertions
  • extractors

Controllers​

Controllers organize or control nested steps.

steps:
  - transaction:
      name: "Login"
      steps:
        - get: /login
        - post: /session

  - parallel:
      name: "Load widgets"
      steps:
        - get: /api/widget-a
        - get: /api/widget-b

Common controller types:

  • group: named container for related steps
  • controller: generic container
  • transaction: measured block that produces transaction-level metrics
  • parallel: executes child steps concurrently
  • one_time: runs initialization steps once and reuses generated variables
  • balanced: routes each VU or iteration into one child branch by percentage

Balanced traffic mix​

balanced distributes load across child branches.

steps:
  - balanced:
      name: "Traffic Mix"
      type: total
      mode: iterations
      steps:
        - percentage: 70
          transaction:
            name: "Browse"
            steps:
              - get: /products
        - percentage: 30
          transaction:
            name: "Checkout"
            steps:
              - post: /checkout

Rules:

  • type must be total.
  • mode must be iterations or virtual_users.
  • Participating child percentages must sum to 100.
  • Child branches must contain at least one enabled HTTP request or SQL step.

SQL steps​

sql executes database work inside a scenario.

steps:
  - sql:
      name: "Check user count"
      dialect: postgres
      kind: query
      connection:
        host: localhost
        port: 5432
        database: app
        user: "{{db_user}}"
        password: "{{db_password}}"
      query: "select count(*) from users"

Supported dialects are postgres and mysql. Supported kinds are query for reads and exec for writes. Write operations require allow_writes: true.

Headers​

Headers may be defined in:

  • http_defaults.headers for shared defaults
  • request.headers for request-level overrides

Request-level values should be treated as stronger than inherited defaults.

Think time​

Relampo supports pacing between requests through think_time steps.

steps:
  - get: /login
  - think_time: "2s"
  - post: /session

Assertions​

Assertions validate responses and protect the flow from silent failures.

Typical assertion targets include:

  • status code
  • body content
  • response time
  • headers

Extractors​

Extractors capture dynamic values from responses so later requests can reuse them.

These values are critical for:

  • authentication tokens
  • IDs
  • session state
  • correlation of dynamic values across requests

Inheritance model​

The active editor specification describes a JMeter-style inheritance model.

In practice, values can be layered from broader scope to narrower scope:

  1. global sections such as variables and http_defaults
  2. scenario-level settings
  3. request-level overrides

Always evaluate the effective value after inheritance, not just the local block.