Gatling and Locust on MaxoPerf

Gatling and Locust are two popular load-testing frameworks with dedicated user communities. MaxoPerf runs both via the Taurus executor wrapper — you upload your existing simulation or locustfile.py, reference it from a Taurus YAML entrypoint, and MaxoPerf handles the rest.

Before you start

• Read Taurus fundamentals — both Gatling and Locust are run via Taurus, so you need to understand the Taurus YAML structure.
• For context on how MaxoPerf infers engines, see By engine — choosing your test engine.

Gatling

Gatling is a Scala-based load-testing framework known for its expressive DSL and HTML report generation. MaxoPerf runs Gatling simulations through the Taurus executor: gatling integration.

When to use Gatling

Use Gatling when:

• Your team already maintains Gatling Scala simulation files.
• You need Gatling’s specific DSL constructs (feeders, checks, conditional execution).
• You want to reuse Gatling scenarios without rewriting them in YAML or JavaScript.

Gatling YAML example

execution:
  - executor: gatling
    concurrency: 100
    ramp-up: 2m
    hold-for: 10m
    scenario: checkout-simulation

scenarios:
  checkout-simulation:
    script: CheckoutSimulation.scala   # uploaded as a Test asset
    # For a compiled JAR, use:
    # script: gatling-test-1.0.jar
    simulation: com.example.CheckoutSimulation

Upload your CheckoutSimulation.scala file as a Test asset alongside the Taurus YAML entrypoint. If your simulation uses a compiled JAR, upload the JAR instead.

What to know about Gatling + MaxoPerf

• MaxoPerf passes the concurrency, ramp-up, and hold-for from the YAML to Gatling’s constantUsersPerSec or rampUsers injection step — you do not need to configure Gatling’s own injection inside the Scala file.
• Gatling’s HTML report is not generated in MaxoPerf runs; metrics are collected from Taurus’s reporting module instead and shown in the standard MaxoPerf run-detail view.
• Gatling requires the simulation class to be present in the uploaded script or JAR — MaxoPerf’s runner includes the Gatling runtime; you do not need to install Gatling locally.
• If your simulation depends on Gatling plugins or external JARs, contact support to confirm they are available in the MaxoPerf runner image.

Gatling Scala snippet (reference)

Here is a minimal Gatling simulation that MaxoPerf can run:

import io.gatling.core.Predef._
import io.gatling.http.Predef._
import scala.concurrent.duration._

class CheckoutSimulation extends Simulation {

  val httpProtocol = http
    .baseUrl("https://api.example.com")
    .acceptHeader("application/json")

  val checkoutScenario = scenario("Checkout")
    .exec(
      http("POST checkout")
        .post("/checkout")
        .body(StringBody("""{"item":"widget","qty":1}""")).asJson
        .check(status.is(200))
    )

  // Injection: MaxoPerf overrides via the YAML concurrency / ramp-up / hold-for.
  // Keep a placeholder here for local Gatling Desktop runs.
  setUp(
    checkoutScenario.inject(rampUsers(100).during(2.minutes))
  ).protocols(httpProtocol)
}

Locust

Locust is a Python-based load-testing tool that defines user behavior as Python classes. MaxoPerf runs Locust tests through the Taurus executor: locust integration.

When to use Locust

Use Locust when:

• Your team prefers Python for scripting.
• You need Locust’s flexible task weighting and user class composition.
• You already have a locustfile.py in your project.

Locust YAML example

execution:
  - executor: locust
    concurrency: 50
    ramp-up: 1m
    hold-for: 5m
    scenario: api-users

scenarios:
  api-users:
    script: locustfile.py    # uploaded as a Test asset

Upload your locustfile.py as a Test asset. Taurus manages the Locust master/worker process topology and collects metrics from Locust’s statistics endpoint.

Minimal locustfile.py

from locust import HttpUser, task, between

class ApiUser(HttpUser):
    wait_time = between(1, 3)   # think time between tasks (seconds)

    @task(3)                    # weight: 3x more likely than the second task
    def get_products(self):
        self.client.get("/products")

    @task(1)
    def post_checkout(self):
        self.client.post(
            "/checkout",
            json={"item": "widget", "qty": 1},
        )

What to know about Locust + MaxoPerf

• MaxoPerf passes concurrency, ramp-up, and hold-for from the Taurus YAML to Locust’s spawn rate and user count — you do not need to set these in the locustfile.py for MaxoPerf runs.
• Locust’s web UI is not exposed in MaxoPerf runs; all metrics come through Taurus’s reporting pipeline and appear in the standard MaxoPerf run-detail view.
• If your locustfile.py imports third-party Python packages beyond the standard library and Locust itself, contact support to confirm they are available in the MaxoPerf runner image.
• Name your entrypoint locustfile.py — Taurus and Locust both recognize this convention automatically. If you use a different filename, explicitly reference it via script: in the YAML.

Do / don’t

Do:

• Wrap Gatling and Locust scenarios in a Taurus YAML — this gives you explicit control over concurrency and duration without editing the simulation file for each load level.
• Test your simulation or locustfile locally before uploading to catch import errors and syntax issues.
• Use the Taurus YAML’s ramp-up key to warm up the system before sustaining peak load.

Don’t:

• Mix executor: gatling and executor: locust in the same YAML — MaxoPerf rejects multi-executor files.
• Hard-code absolute paths in your Scala file or locustfile.py — use relative references that resolve against the bundle root.

Where to go next

• Taurus executor catalog — the gatling and locust executor entries.
• Taurus fundamentals — YAML anatomy and upload workflow.
• Upload test files — how to upload the script as a test asset.
• Test engines concept page — high-level engine comparison.