Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

HTTP polling is an extension of the Gatling HTTP SDK that lets a virtual user send the same request repeatedly on a fixed schedule, running in a separate flow alongside the main scenario steps. This is useful for simulating real-world patterns where browsers periodically check for updates, refresh tokens, or poll a status endpoint while the user continues navigating the application. The period is measured from the moment a response is received to when the next request is sent.
Polling does not support checks. If you attach checks to a polled request, they will have no effect.

​
Starting a Poller

Start polling by calling poll().every(period).exec(request). The period can be expressed as an integer number of seconds or as a duration. 
exec(
  poll()
    .every(10)
    .exec(http("Poll status").get("/api/status"))
);

​
Stopping a Poller

When you no longer need a poller, stop it with poll().stop(). Stopping a poller merges its flow state (including any session values it captured) back into the main flow’s session. 
exec(
  poll().stop()
);
When a poller is stopped, its session state is merged back into the main flow. This means any session attributes written by the polled request become available in subsequent main-flow steps.

​
Multiple Pollers per Virtual User

If a virtual user needs to run more than one simultaneous poller, give each one a unique name using pollerName. The same name must be passed when stopping the corresponding poller. 
// start first poller
exec(
  poll()
    .pollerName("status-poller")
    .every(10)
    .exec(http("Poll status").get("/api/status"))
);

// start second poller
exec(
  poll()
    .pollerName("heartbeat-poller")
    .every(30)
    .exec(http("Heartbeat").get("/api/heartbeat"))
);

// stop the status poller
exec(
  poll().pollerName("status-poller").stop()
);

// stop the heartbeat poller
exec(
  poll().pollerName("heartbeat-poller").stop()
);
If you only have one poller per virtual user, pollerName is optional. The name is only required when multiple pollers need to be distinguished.

​
Full Example

The following scenario starts a poller, executes a sequence of main-flow steps, then stops the poller. 
scenario("Dashboard with background polling")
  .exec(
    http("Load dashboard").get("/dashboard")
      .check(status().is(200))
  )
  // start polling every 5 seconds in the background
  .exec(
    poll()
      .pollerName("metrics")
      .every(5)
      .exec(http("Poll metrics").get("/api/metrics"))
  )
  // main flow continues
  .exec(
    http("Navigate to reports").get("/reports")
      .check(status().is(200))
  )
  .pause(30)
  // stop the background poller
  .exec(
    poll().pollerName("metrics").stop()
  );

Build docs developers (and LLMs) love

Get started for freeTalk to us