Test editor

The test editor is where you define what a load test does: which scenarios run, which steps each scenario runs in order, which values are taken from responses and reused in later steps, which checks verify the responses and which thresholds decide whether the run passes or fails. How much load is applied (VU count, request rate, stages) is set on the same screen; the Load model page covers it separately.

This page walks through the editor from top to bottom, in order. The examples use HTTP; the other protocols (gRPC, Kafka, SQL…) share the same step structure and the same extract, check and think time fields.

#What it is for

• You define the test without writing code, through form fields; at any time you can see the same definition as JSON, edit it and run it from the CLI.
• Every change is validated on the server as you type: invalid fields are marked in red, and an invalid test cannot be saved.
• The Try it button sends the test to the real system as a single iteration, without applying load, and shows each step's request, response, check results and extracted variables.
• Save stores the test as a new version. Old versions are never deleted; the Version history on the test page shows a diff and can restore any of them.

#When to use it

• When creating a new test (Tests → New test).
• When changing an existing test (Edit on the test page).
• When reviewing a test imported from a k6 script, a JMeter plan, OpenAPI/Postman/HAR or a traffic log before saving it (imports open in the editor).
• When a run shows unexpected errors, to inspect a single iteration step by step with Try it before applying load again.

#Editor layout

From top to bottom the editor has these parts:

A tab that contains an error shows a red exclamation icon next to its name; that is how you know which tab to look at.

Test editor: tabs, scenario buttons, load model and the first step

#Step by step creating your first test

The order below is the shortest path from an empty test to a working, saved one.

1. Go to Tests in the left menu and click New test at the top right (Tests In Spitfire: /tests). The editor opens with a ready-made skeleton:

   • Test name: "New test"
   • One variable on the General & variables tab: base = https://example.com
   • A scenario named main with the Ramping VUs (ramping-vus) load model: up to 10 VUs in 30 seconds, 1 minute at 10 VUs, down to 0 in 10 seconds
   • An HTTP step named "Home page": GET {{base}}/ with one check: status = 200
   • Two thresholds: p(95)<500 on req_duration and rate<0.01 on req_failed

   New test: the skeleton the editor opens with

2. Type a meaningful name in the Test name box at the top (e.g. "Checkout flow"). The name is required; leaving it empty gives the error name: required.

3. Switch to the General & variables tab. In the Variables section, replace the value of the base variable with the address of the system you are testing (e.g. https://shop.staging.example.com). Write it without a trailing /; steps use it as {{base}}/api/....

4. Go back to the Scenarios & steps tab. Under the Load heading, pick the load model and enter its values. If you don't know which model to pick, read Which load model should I pick first. Keep it small for a first try (e.g. 5 VUs, 1 minute).

5. In the first step card under the Steps heading:

   1. Type the Step name in the text box at the start of the card (e.g. "Login").
   2. Leave HTTP selected in the Protocol list.
   3. Pick the method in the Method list (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS).
   4. Type the address in the URL field: {{base}}/api/login.
   5. Fill in the Headers, Query and Body sub-tabs if needed (details below, HTTP request).

6. On the Checks tab at the bottom of the same card, define how you tell that the response is correct ("status = 200" is already there).

7. If a value from this step's response (e.g. a token) is needed in later steps, switch to the Extract tab and define an extractor with Add variable.

8. Click Add step for a new step and repeat steps 5–7.

9. Review the pass/fail criteria on the Thresholds (N) tab (see Defining thresholds).

10. When there is no yellow error box, click Try it at the top right. In the Try (1 VU, 1 iteration) window, check each step's request, response, checks and extracted values.

11. If everything is right, click Save. The test is saved and its page opens. You start the run from there with Run.

#Scenario structure

A test is made of one or more scenarios. At the top of the Scenarios & steps tab there is a button for each scenario (e.g. main); the selected one is solid blue. The Scenario button with the plus icon next to them adds a new scenario (named scenario_2, scenario_3…, with Constant VUs 5 VUs / 1 minute and a single HTTP step).

Each scenario has its own fields:

The hint on screen says it too: "Scenarios run at the same time; each has its own load model." For example, one scenario can represent many users browsing the catalog and a second one a few users checking out.

The iteration: when a VU has run all of a scenario's steps once from top to bottom, one iteration is complete. Then (depending on the load model) it starts another.

#Step structure

Each step is a card. Its header row holds, from left to right: the expand/collapse arrow, the sequence number, the Step name, the protocol badge, a short summary (METHOD URL for HTTP), the "once" badge if set, and on the right the Move up, Move down and Delete step buttons. A step with an error gets a red border and an exclamation icon in its header.

Inside the card:

1. The Protocol list: HTTP, WebSocket, Server-Sent Events, gRPC, MQTT, RabbitMQ (AMQP), Kafka, Redis, SQL, MongoDB.
2. For protocols other than HTTP, WebSocket and SSE, the Connection list (address and passwords are not in the step but in a saved connection on the Connections page). If there is no suitable connection it says "No connection for this protocol." with a Create a connection In Spitfire: /connections link. For HTTP/WS/SSE, when a saved mTLS connection exists, a Client certificate (mTLS) list shows instead.
3. The protocol's own form (HTTP below).
4. The list of variables you can use: "Use variables as {{name}}: … Built-in: {{__VU}} {{__ITER}} {{$uuid}} {{$randInt 1 100}} {{$timestamp}}" and the expandable Synthetic test data (fake.…) section.
5. Three sub-tabs: Checks, Extract, More.

Every step also has a step id (id). The editor generates it from the step name and shows it at the bottom of the More tab as "Step id (used by threshold filters)". The id identifies the step in threshold filters and result tables, and must be unique within the test. To change it by hand, use the JSON tab.

#HTTP request

The HTTP form has these fields:

Body types:

• JSON / XML / Raw: you type the body in the text area; templates are allowed. When a JSON body has no {{…}}, the server also checks that the JSON is valid.
• Form (urlencoded): key/value rows with Add field.
• Form (multipart / files): fields with Add part. A part with a File name (for files) is sent as a file; for a binary file tick Value is base64 (binary file) and paste the value as base64.

When an HTTP step counts as "failed" (req_failed): the connection cannot be made, it times out, or the status code is 400 or above. Exception: if the step has a "Status = X" or "Status one of X, Y" check, Spitfire treats those codes as expected. For example, with a check expecting 404, a 404 response does not count in the error rate, while a 200 does.

HTTP step: method, URL, Headers / Query / Body and checks

#Variables and templates

Most step fields (URL, header and query values, body, gRPC message, Kafka value, SQL parameters…) are templates: you insert values with {{…}}, and they are computed again for every request.

#Defining test variables

They are defined in the Variables section of the General & variables tab (Add variable). The hint on screen: "Use them in steps as {{name}}. The one place to switch environments (e.g. the base URL)."

• A name may only contain letters, digits and _ and must not start with a digit (base, api_key).
• The value is plain text; it is visible in the test definition (and in the JSON and the version history).
• To change a variable's value per environment use Environments; for a single run use Change variables for this run in the Run dialog.

The names a template may use are: test variables, data file columns ({{users.email}}, see Test data) and variables extracted in earlier steps. Any other name gives the error unknown variable {name}.

#Built-in values

Expanding Synthetic test data (fake.…) in a step card shows one button per fake data kind; clicking it copies the {{fake.…}} syntax to the clipboard.

Built-in values and fake data buttons in a step card

#Template rules

• Opening {{ and forgetting to close it with }}: template error: unterminated {{ at offset N.
• An unknown $ function ({{$random}}) is a template error.
• {{$randInt 10 1}} (max < min) is a template error.
• A variable without a value (e.g. one whose extractor found nothing) renders as an empty string.
• In SQL, values may not be written into the query text; use the $1, ?, @p1, :1 parameters and put the template in the parameter value.

#Extracting values

An extractor takes a value from a step's response so later steps can use it as {{name}}. Typical example: taking the token from the login step.

Step by step:

1. In the card of the step that produces the value, click the Extract tab.
2. Click Add variable. A row appears.
3. Type the variable name in the Variable name box (e.g. token).
4. Pick where the value comes from in the Source list.
5. Type an expression that fits the source in the Expression box (table below).
6. Optionally type a value in the default box to use when nothing is found.
7. Use {{token}} in a later step (e.g. the header value Bearer {{token}}).
8. Check it with Try it: under the step the try window should show "Extracted: token=…"; when nothing was found it says "Not found: token" in red.

Extract tab: variable name, source, expression and default

Good to know:

• An extracted variable can be used in later steps of the same iteration and in the VU's later iterations. The help line in a step card lists the variables that step can use (only those extracted in earlier steps appear).
• If a value is not found this time, the value from the previous iteration is not reused: the variable falls back to its default, or without one to the test's variable of the same name (or to an empty string). This way an expired token cannot make later requests look successful by mistake.
• Asking for a regex group that does not exist gives the regex has only N group(s).
• Not keeping response bodies (Options → Don't keep response bodies) does not break extractors; steps that read the body are not affected.

#Defining checks

A check verifies whether a response is right. The help text on screen states an important rule: "A failed check doesn't stop the iteration; it counts in the "checks" rate. Add a threshold to fail the test." So after a failed check the iteration's remaining steps still run; to turn the test red you put a threshold on the checks metric (e.g. rate>0.99).

Step by step:

1. Click the Checks tab in the step card (it is the tab open by default).
2. Click Add check.
3. Pick the type in the Check type list.
4. For JSON field, XML field or Header, type the path in the Path box.
5. Pick the comparison in the Operator list.
6. Type the expected value in the Value box. For "one of", separate the values with commas: 200, 201.

The Header type is listed for HTTP, gRPC, AMQP and Kafka steps; Row count only for SQL and MongoDB steps.

A check has a name; left empty, one is generated (status == 200, latency < 800ms, $.status == PAID). The name shows on the run page's Checks card and is used in threshold filters.

Checks tab: check type, path, operator and value

#Think time and once per VU

The More tab of a step card has two settings:

• Run once per VU: the step runs only in each VU's first iteration. "For steps like login. Retried in the next iteration if it fails." To count as successful, the request must not fail and all its extractors must find a value. The header shows a "once" badge. Because cookies are kept per VU (the default), the session cookie received at login is sent in later iterations too.
• Think time (pause after the step): how long the VU waits after the step, i.e. the think time. There are two boxes: min (1s) and max (3s). With both filled, the pause is picked at random in that range; with only "min" it is fixed. It imitates real users pausing between pages.

More tab: once per VU, think time and step id

#Environments

The Environments tab lets you run the same test against different environments (staging, production…): "each one replaces some variables' values and the connections the steps use. The environment is chosen when a run or schedule starts."

Step by step:

1. First define the variables that change per environment on the General & variables tab (e.g. base). An environment can only replace variables the test has.
2. On the Environments tab click Add environment.
3. Type the Environment name: lowercase letters, digits, - and _, at most 32 characters (staging, prod-eu).
4. In the Variables section enter the values that differ in this environment. "An empty variable keeps its value from the test."
5. In the Connections section, map the saved connections the steps use to their counterpart in this environment (e.g. orders-db → orders-db-staging). Only a connection of the same type can be picked. If no step uses a saved connection it says "No step uses a saved connection."
6. The Equivalence (comparative runs) and Version endpoint (optional) sections are only for comparative (A/B) runs; you can leave them empty for normal runs.
7. Save. In the Run dialog the environment appears in Environment and scale → Environment.

Environments tab: environment name, variable values and connection mapping

In JSON:

"variables": { "base": "https://shop.example.com" },
"environments": {
  "staging": {
    "variables": { "base": "https://shop.staging.example.com" },
    "connections": { "orders-db": "orders-db-staging" }
  }
}

#Options

The Options tab holds settings that apply to the whole test. The defaults are fine for most tests.

Options tab

#Validation and saving

#Live validation

Shortly after every change (about 0.6 seconds) the editor has the server validate the definition and redraws the load plan. The result shows in three places:

1. The yellow box below the title: "N errors:" with the path and message of the first four.
2. Red exclamation icons on the tab names.
3. A red message right below the invalid field.

When the test contains operations that change data (This request changes data on the target on an HTTP step, SQL/Mongo writes, dangerous Redis commands) a red box also appears: "This test modifies data. Starting a run or a try asks for confirmation." It is a warning, not an error; the test can be saved.

#Saving

1. Click Save at the top right (Save as new version for an existing test).
2. The test is saved as a new version (v1, v2, …) and its page opens.
3. To start a run, click Run on the test page.

If you try to leave the page without saving, the Unsaved changes dialog opens: "This test has changes you have not saved. They are lost if you leave the page." Leave without saving discards them; Cancel returns to the editor.

#When two people edit the same test

If someone else saved the same test after you opened the editor, your save is refused: "Someone else saved this test since you opened it. Copy your changes (JSON tab), reload the page and apply them again." In that case:

1. Switch to the JSON tab and click Copy (or paste the text somewhere).
2. Reload the page; the editor opens with the latest version.
3. Make your changes again (or paste the JSON and click Apply; then make sure you are not overwriting the other person's changes).

#Version history

Clicking the Version history (current: vN) heading at the bottom of the test page lists every version:

• Diff with current: shows the difference between that version and the current one, line by line.
• Restore this version: saves that version's definition as a new version; history and runs stay as they are. It is refused if the definition no longer passes today's rules (e.g. it uses a deleted connection).

Version history on the test page

#JSON view

The JSON tab shows the whole test: "The whole definition. Edit it and press "Apply"; the form follows. Same format as the CLI: spitfire run test.json".

Step by step:

1. Click the JSON tab.
2. Edit the text (or paste it from elsewhere).
3. Click Apply. Invalid JSON gives "Invalid JSON: …"; JSON without a scenarios array gives "a "scenarios" array is required".
4. The form updates from the JSON; live validation errors show as usual.
5. Click Save to save. Apply alone does not save.

The Copy button puts the text on the clipboard. Fields not in the form (e.g. the step id, the scenario or check filter of a threshold) can only be edited here.

JSON tab: the whole definition, Apply and Copy

Durations are written as text: "500ms", "30s", "1m30s", "2h". In hand-written JSON a bare number is read as milliseconds (500 = half a second).

#Full example

The test below is a three-step shopping flow: each VU logs in once and takes the token, lists the products, takes the first product's id and creates an order. You can paste it into the JSON tab and click Apply (replace the base address with your system's).

{
  "version": 1,
  "name": "Checkout flow",
  "variables": {
    "base": "https://shop.example.com",
    "password": "Test1234!"
  },
  "options": { "timeout": "30s" },
  "scenarios": [
    {
      "name": "checkout",
      "executor": {
        "type": "ramping-vus",
        "startVUs": 0,
        "stages": [
          { "duration": "1m", "target": 20 },
          { "duration": "3m", "target": 20 },
          { "duration": "30s", "target": 0 }
        ]
      },
      "steps": [
        {
          "id": "login",
          "name": "Login",
          "once": true,
          "protocol": "http",
          "request": {
            "method": "POST",
            "url": "{{base}}/api/login",
            "body": {
              "type": "json",
              "content": "{\"email\": \"vu{{__VU}}@example.com\", \"password\": \"{{password}}\"}"
            }
          },
          "extract": [
            { "var": "token", "from": "jsonpath", "expr": "$.token" }
          ],
          "checks": [
            { "type": "status", "op": "eq", "value": 200 },
            { "type": "jsonPath", "path": "$.token", "op": "exists" }
          ]
        },
        {
          "id": "list_products",
          "name": "List products",
          "protocol": "http",
          "request": {
            "method": "GET",
            "url": "{{base}}/api/products",
            "headers": [ { "key": "Authorization", "value": "Bearer {{token}}" } ],
            "query": [ { "key": "page", "value": "{{$randInt 1 5}}" } ]
          },
          "extract": [
            { "var": "productId", "from": "jsonpath", "expr": "$.items[0].id", "default": "1" }
          ],
          "checks": [
            { "type": "status", "op": "eq", "value": 200 },
            { "type": "latency", "op": "lt", "value": 800 }
          ],
          "thinkTime": { "min": "1s", "max": "3s" }
        },
        {
          "id": "create_order",
          "name": "Create order",
          "protocol": "http",
          "request": {
            "method": "POST",
            "url": "{{base}}/api/orders",
            "headers": [
              { "key": "Authorization", "value": "Bearer {{token}}" },
              { "key": "Idempotency-Key", "value": "{{$uuid}}" }
            ],
            "body": {
              "type": "json",
              "content": "{\"productId\": \"{{productId}}\", \"quantity\": 1}"
            },
            "modifiesData": true
          },
          "checks": [
            { "type": "status", "op": "in", "value": [200, 201] },
            { "type": "jsonPath", "path": "$.status", "op": "eq", "value": "CREATED" }
          ]
        }
      ]
    }
  ],
  "thresholds": [
    { "metric": "req_duration", "expr": "p(95)<500" },
    { "metric": "req_failed", "expr": "rate<0.01" },
    { "metric": "req_duration", "filter": { "step": "create_order" }, "expr": "p(95)<800" },
    { "metric": "checks", "expr": "rate>0.99" }
  ]
}

Things to notice in this example:

• The login step has "once": true, so each VU logs in only once; the token is used in all of the VU's iterations.
• The create_order step has "modifiesData": true, so starting a run asks for write confirmation.
• The third threshold applies only to the create_order step (filter.step is the step id, not the step name).
• If the JSON field names in your system differ ($.token, $.items[0].id, $.status), look at the real response with Try it and fix the expressions accordingly.

#Trying a single iteration with Try it

Try it sends the selected scenario to the real system as 1 VU and 1 iteration, without applying load. The scenario tried is the one selected with the scenario buttons on the Scenarios & steps tab.

1. Make sure there is no error box (Try it is disabled while there are errors).
2. Select the right scenario.
3. Click Try it. If the test changes data, the Try a test that modifies data dialog opens first and lists which operations change data; click I understand, try it to go on.
4. In the Try (1 VU, 1 iteration) window, read for each step: status and duration, check results (with the "actual" value when they fail), the Extracted variables, the Not found list, the Request and the Response (headers and body). At the bottom, the Final VU variables are listed.

Try window: each step's request, response, checks and extracted values

#Common problems

#Related pages

• Load model: executors, stages, thresholds and capacity tests.
• Test data: CSV data files, fake data and passing values between steps.
• Runs and results: starting a run, watching it live, reading results and reports.
• Tests In Spitfire: /tests · Connections In Spitfire: /connections · Data files In Spitfire: /data-files