Skip to content
MaxoPerf MaxoPerf docs

Gatling and Locust on MaxoPerf

Gatling and Locust are two popular load-testing frameworks. MaxoPerf runs both through the Taurus executor wrapper. You upload your existing simulation or locustfile.py and reference it from a Taurus YAML entrypoint. MaxoPerf handles the rest.

Before you start

Section titled “Before you start”

Gatling

Section titled “Gatling”

Gatling is a Scala-based load-testing framework with its own DSL and HTML reports. MaxoPerf runs Gatling simulations through the Taurus executor: gatling integration.

When to use Gatling

Section titled “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

Section titled “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 CheckoutSimulation.scala as a Test asset next to the Taurus YAML entrypoint. If your simulation is a compiled JAR, upload the JAR instead.

What to know about Gatling + MaxoPerf

Section titled “What to know about Gatling + MaxoPerf”
  • MaxoPerf passes concurrency, ramp-up, and hold-for from the YAML to Gatling’s constantUsersPerSec or rampUsers injection step. You do not need to configure injection inside the Scala file.
  • MaxoPerf runs do not generate Gatling’s HTML report. Taurus’s reporting module collects the metrics, and they appear in the standard MaxoPerf run-detail view.
  • The simulation class must be in the uploaded script or JAR. The MaxoPerf runner includes the Gatling runtime, so you do not need to install Gatling locally.
  • If your simulation depends on Gatling plugins or external JARs, ask support whether the MaxoPerf runner image includes them.

Gatling Scala snippet (reference)

Section titled “Gatling Scala snippet (reference)”

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

Section titled “Locust”

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

When to use Locust

Section titled “When to use Locust”

Use Locust when:

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

Locust YAML example

Section titled “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 locustfile.py as a Test asset. Taurus manages the Locust master/worker processes and reads metrics from Locust’s statistics endpoint.

Minimal locustfile.py

Section titled “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

Section titled “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 them in locustfile.py for MaxoPerf runs.
  • MaxoPerf runs do not expose Locust’s web UI. All metrics go 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, ask support whether the MaxoPerf runner image includes them.
  • Name your entrypoint locustfile.py. Taurus and Locust both recognize that name. If you use a different filename, reference it with script: in the YAML.

Do / don’t

Section titled “Do / don’t”

Do:

  • Wrap Gatling and Locust scenarios in a Taurus YAML. You then set concurrency and duration there instead of editing the simulation file for each load level.
  • Run your simulation or locustfile locally before you upload it. This catches import and syntax errors.
  • Use the Taurus YAML’s ramp-up key to warm up the system before you hold 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 paths that resolve against the bundle root.

Where to go next

Section titled “Where to go next”