Taurus fundamentals

Taurus is the most common starting point for new MaxoPerf tests. It uses a concise, readable YAML format that engineers from any background can write and review. This page explains the full anatomy of a Taurus YAML and shows you exactly how to upload and run one in MaxoPerf.

Before you start

• You should be comfortable with basic YAML syntax.
• If you are not sure which engine to use, read By engine — choosing your test engine first.

Taurus YAML anatomy

A minimal Taurus YAML has three top-level keys:

execution:
  - executor: jmeter          # which underlying tool runs this scenario
    concurrency: 50           # virtual users
    ramp-up: 30s              # time to reach full concurrency
    hold-for: 2m              # how long to sustain full load
    scenario: checkout-flow   # pointer to the scenario block

scenarios:
  checkout-flow:
    requests:
      - url: https://api.example.com/checkout
        method: POST
        headers:
          Content-Type: application/json
        body: '{"item": "widget", "qty": 1}'
        assert:
          - contains:
              subject: body
              value: '"orderId"'

reporting:
  - module: final-stats
  - module: console

The execution: block

The execution: block is a list of execution objects. Each defines one load scenario run:

Key	Required	Description
executor	yes	The underlying engine (jmeter, k6, gatling, locust, …). Omit for native Taurus HTTP.
concurrency	yes	Number of virtual users (VUs) to sustain.
ramp-up	no	Time to linearly ramp from 0 to concurrency. E.g. 30s, 2m.
hold-for	yes	Duration to sustain full load after ramp-up.
iterations	no	Alternative to hold-for: stop after N iterations per VU.
scenario	yes	Name of the scenario block (or inline scenario).

One executor per file

MaxoPerf enforces a single-executor invariant: every Taurus YAML uploaded to MaxoPerf must declare at most one distinct executor: value across all execution: rows. A YAML mixing executor: jmeter and executor: k6 is rejected at upload time with a multi_executor validation error.

The scenarios: block

Scenarios describe what your virtual users do. For native Taurus HTTP requests:

scenarios:
  api-smoke:
    requests:
      - url: https://api.example.com/health
        method: GET
        assert:
          - contains:
              subject: body
              value: '"status":"ok"'
      - url: https://api.example.com/users
        method: GET
        assert:
          - equals:
              subject: http-code
              value: '200'

For executor-based scenarios (e.g. JMeter), the scenario points at a script file:

scenarios:
  my-jmeter-scenario:
    script: flow.jmx          # relative path to the JMX — must be uploaded as a test asset

The reporting: block

MaxoPerf injects its own reporting configuration at run time. You do not need to specify a final-stats or passfail module — MaxoPerf’s overlay adds them automatically. You can include your own reporting: entries; MaxoPerf’s overlay wins on any conflicting keys.

Included configs

Large test suites can split configuration across multiple YAML files:

included-configs:
  - shared-settings.yml       # must be uploaded as a test asset alongside the entrypoint
  - data-sources.yml

Uploading a Taurus YAML to MaxoPerf

1. Open your test in the MaxoPerf console and switch to the Files tab.
2. Drag your Taurus YAML file into the upload area (or click to browse).
3. Mark the YAML as the Entrypoint. This is the file MaxoPerf uses to detect the engine and start the run.
4. Upload any supporting files your YAML references — data CSVs, included configs, script files — and leave them as Test asset.
5. Save. MaxoPerf validates the YAML on upload: it checks the executor: field, verifies every scenarios.*.script reference resolves to an uploaded test asset, and shows a green validation badge when everything is valid.

How MaxoPerf detects the executor

When you upload a Taurus YAML and mark it as the entrypoint, MaxoPerf reads the executor: field from the execution: block:

• executor: jmeter → engine badge shows JMeter.
• executor: k6 → engine badge shows k6.
• executor: gatling, locust, selenium, etc. → engine badge shows that executor name.
• No executor: key → engine badge shows Taurus (native HTTP runner).

The engine badge appears on the test card, in the test detail header, and on the run detail summary.

Validation errors

If your YAML fails validation, MaxoPerf shows an error badge on the Files tab with a machine-readable code and a human message:

Common validation errors:

Code	Meaning	Fix
missing_reference	A scenarios.*.script or data-sources path is not uploaded	Upload the referenced file as a Test asset
multi_executor	Two different executor: values in one YAML	Keep one executor per file; split into separate tests
parse_error	YAML syntax error	Fix indentation or invalid characters
unsafe_path	A referenced path contains .. or an absolute path	Use relative basenames only

Running the test

Once validation passes (green badge), click Run on the test detail page. MaxoPerf assembles a bundle.zip that includes your YAML merged with the MaxoPerf overlay (failure criteria, reporting, runtime secrets) plus all test assets, then dispatches the bundle to the runner fleet.

Do / don’t

Do:

• Keep each Taurus YAML to a single executor.
• Use ramp-up to avoid a thundering-herd cold start.
• Upload all files referenced by scenarios.*.script, data-sources, and included-configs — MaxoPerf validates every reference.

Don’t:

• Put credentials in the YAML — use Manage test secrets.
• Set settings.env keys that override MaxoPerf’s own reporting variables — your env keys are merged but MaxoPerf’s reporting keys win.

Where to go next

• Taurus executor catalog — every executor with MaxoPerf support notes.
• JMeter JMX on Maxoperf — if your scenario is a .jmx file.
• k6 scripts on Maxoperf — if your scenario is a k6 JavaScript file.
• Upload test files — full how-to for the Files tab.
• Cookbook: REST API CRUD load test — a worked example using Taurus.