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.

The HTTP protocol object is the central place to define behavior that applies across all HTTP requests in a scenario. Rather than repeating connection settings, authentication credentials, or common headers on every individual request, you configure them once on the protocol and attach it to your scenario setup. Gatling supports a comprehensive range of HTTP behaviors — including caching, cookies, redirects, resource inference, and TLS — matching what modern browsers do, while operating purely at the HTTP protocol level without executing JavaScript or CSS.

​
Bootstrapping

Every Gatling HTTP simulation starts by creating a protocol builder via the http object and passing it to setUp. This wires the protocol settings to the scenario’s virtual users. 
HttpProtocolBuilder httpProtocol = http.baseUrl("https://gatling.io");

ScenarioBuilder scn = scenario("Scenario"); // etc...

setUp(scn.injectOpen(atOnceUsers(1)).protocols(httpProtocol));

​
HTTP Engine

​
warmUp

The Java/NIO engine incurs a startup overhead on the very first request. To compensate, Gatling automatically sends a warm-up request to https://gatling.io. You can change the warm-up URL or disable it entirely. 
// change the warm up URL
http.warmUp("https://www.google.com");
// disable warm up
http.disableWarmUp();

​
maxConnectionsPerHost

To mimic real browsers, Gatling can open multiple concurrent connections per virtual user when fetching resources over HTTP/1.1. The default cap is 6 connections per remote host per virtual user.
This setting only applies when fetching concurrent resources over HTTP/1.1 with per-virtual-user connection pools. It has no effect when using HTTP/2 or .shareConnections.
http.maxConnectionsPerHost(10);

​
shareConnections

By default, every virtual user has its own connection pool and SSLContext, which accurately simulates browser-based internet traffic. If you are simulating server-to-server traffic where a single long-lived connection pool is shared across all clients, use shareConnections. 
http.shareConnections();

​
enableHttp2

Enable HTTP/2 support via ALPN negotiation. When enabled, Gatling attempts to connect using HTTP/2 and falls back to HTTP/1 automatically if the remote does not support it. HTTP/2 Push is not supported.
HTTP/2 Push is not supported by Gatling.
http.enableHttp2();
You can pre-configure HTTP/2 prior knowledge to skip ALPN negotiation for known hosts: 
Map<String, Boolean> priorKnowledge = new HashMap<>();
priorKnowledge.put("www.google.com", true);
priorKnowledge.put("gatling.io", false);

http
  .enableHttp2()
  .http2PriorKnowledge(priorKnowledge);
If a remote is configured with true in prior knowledge but actually only supports HTTP/1, the request will fail. Only use this option when you are certain about the remote’s configuration.

​
Request Generation

​
baseUrl

Setting a base URL prepends it to every relative URL in the scenario. Absolute URLs (those starting with http) are left unchanged. 
HttpProtocolBuilder httpProtocol = http.baseUrl("https://gatling.io");

ScenarioBuilder scn = scenario("Scenario")
  // resolves to "https://gatling.io/doc/"
  .exec(http("Relative").get("/doc/"))
  // absolute URL unchanged
  .exec(http("Absolute").get("https://github.com/gatling/gatling"));

​
baseUrls

To distribute load across multiple servers (e.g., bypassing a load balancer), provide a list of base URLs. Each virtual user is assigned one URL from the list in a round-robin fashion at startup. 
http.baseUrls(
  "https://gatling.io",
  "https://github.com"
);

​
disableAutoReferer

By default, Gatling automatically computes the Referer header from the request history. You can disable this behavior. 
http.disableAutoReferer();

​
disableCaching

Gatling caches responses based on Expires, Cache-Control, Last-Modified, and ETag headers. You can disable this feature entirely.
When a response is served from cache, checks are skipped for that request.
http.disableCaching();

​
disableUrlEncoding

By default, Gatling URL-encodes query parameters. If your URLs are already properly encoded and you want to avoid the overhead, you can disable this. 
http.disableUrlEncoding();

​
silentUri

Silent requests are excluded from reports and don’t influence error triggers such as tryMax or exitHereIfFailed. Their response times are still counted in group times. Use regex patterns to silence CDN or static asset requests at the protocol level. 
// silence all requests matching the pattern
http.silentUri("https://myCDN/.*");
// silence all inferred resource requests
http.silentResources();

​
Headers

​
Default Headers

Apply one or more HTTP headers to every request in the scenario. Values can be static strings, Gatling EL expressions, or functions. 
http
  .header("foo", "bar")
  .header("foo", "#{headerValue}")
  .header("foo", session -> session.getString("headerValue"))
  .headers(Map.of("foo", "bar"));

​
Built-in Header Shortcuts

Gatling provides named methods for the most common request headers, all accepting static, EL string, or function values. 
http
  .acceptHeader("text/html,application/xhtml+xml")
  .acceptCharsetHeader("utf-8")
  .acceptEncodingHeader("gzip, deflate")
  .acceptLanguageHeader("en-US,en;q=0.5")
  .authorizationHeader("Bearer #{token}")
  .connectionHeader("keep-alive")
  .contentTypeHeader("application/json")
  .doNotTrackHeader("1")
  .originHeader("https://gatling.io")
  .userAgentHeader("Mozilla/5.0")
  .upgradeInsecureRequestsHeader("1");

​
Authentication

​
Request Signing

You can supply a signing function that runs after Gatling builds the request and before it is sent. A common use case is computing a checksum header. A built-in for OAuth1 is also provided. 
// custom signing function
http.sign((request, session) -> request);

// built-in OAuth1
http.signWithOAuth1(
  "consumerKey",
  "clientSharedSecret",
  "token",
  "tokenSecret"
);
// dynamic credentials from session
http.signWithOAuth1(
  session -> session.getString("consumerKey"),
  session -> session.getString("clientSharedSecret"),
  session -> session.getString("token"),
  session -> session.getString("tokenSecret")
);

​
Basic Auth and Digest Auth

Set HTTP authentication globally so all requests use the same credentials. Both static values and dynamic Gatling EL expressions are supported. 
// Basic Auth
http.basicAuth("username", "password");
http.basicAuth("#{username}", "#{password}");

// Digest Auth
http.digestAuth("username", "password");
http.digestAuth("#{username}", "#{password}");

​
Response Handling

​
Redirect Configuration

Gatling follows 301, 302, 303, 307, and 308 redirects automatically and caps redirect chains at 20 by default. You can disable redirect following, adjust the limit, or customize how redirect request names are generated. 
// disable redirect following
http.disableFollowRedirect();

// custom limit
http.maxRedirects(5);

// keep original method on 302 (instead of switching to GET)
http.strict302Handling();

// custom naming strategy
http.redirectNamingStrategy(
  (uri, originalRequestName, redirectCount) -> "redirectedRequestName"
);

​
Resource Inference

Gatling can parse HTML responses and automatically fetch embedded resources in parallel, mimicking browser behavior. Supported tags include <script>, <base>, <link>, <bgsound>, <frame>, <iframe>, <img>, <input>, <body>, <applet>, <embed>, and <object>, as well as CSS @import directives. 
// fetch only resources in the allow list
http.inferHtmlResources(AllowList("pattern1", "pattern2"));
// fetch all except those in the deny list
http.inferHtmlResources(DenyList("pattern1", "pattern2"));
// allow list + deny list combined
http.inferHtmlResources(
  AllowList("pattern1", "pattern2"),
  DenyList("pattern3", "pattern4")
);

​
Proxy Configuration

Route all HTTP requests through a proxy. You can supply credentials for authenticated proxies and bypass the proxy for specific hosts with noProxyFor. 
http.proxy(
  Proxy("myHttpProxyHost", 8080)
    .credentials("myUsername", "myPassword")
);
Exclude specific hosts from the proxy: 
http
  .proxy(Proxy("myProxyHost", 8080))
  .noProxyFor("www.github.com", "gatling.io");

​
DNS Resolution

​
JDK Blocking Resolver (default)

Gatling uses Java’s DNS name resolution by default, with a 30-second TTL on OpenJDK. For multiple DNS records (A records), Gatling shuffles them to emulate DNS round-robin behavior. The TTL can be tuned via the networkaddress.cache.ttl security property.

​
asyncNameResolution

Switch to Gatling’s own non-blocking async DNS resolver. You can also force specific DNS server addresses and opt into per-virtual-user DNS caches. 
// use system DNS servers
http.asyncNameResolution();

// force specific DNS servers
http.asyncNameResolution("8.8.8.8");

// per-virtual-user DNS cache (own UDP requests per user)
http
  .asyncNameResolution()
  .perUserNameResolution();

​
hostNameAliases

Define hostname aliases programmatically without modifying /etc/hosts. 
http.hostNameAliases(
  Map.of("gatling.io", List.of("192.168.0.1", "192.168.0.2"))
);

​
Local Addresses

When your load generator has multiple IP addresses (via IP aliasing or iproute2), you can bind sockets to specific local addresses. Each virtual user is assigned one address in a round-robin fashion. 
http.localAddress("192.168.0.1");
http.localAddresses("192.168.0.1", "192.168.0.2");

// use all available bindable addresses
http.useAllLocalAddresses();

// use addresses matching a regex pattern
http.useAllLocalAddressesMatching("pattern1", "pattern2");

​
Per-User Key Manager

By default, Gatling uses the KeyManagerFactory from gatling.conf or the JVM default. For mutual TLS scenarios where each virtual user needs different certificates, you can supply a factory function keyed on the virtual user ID. 
http.perUserKeyManagerFactory(
  userId -> (javax.net.ssl.KeyManagerFactory) myFactoryForUser(userId)
);
perUserKeyManagerFactory is not supported in the JavaScript/TypeScript SDK.

Build docs developers (and LLMs) love

Get started for freeTalk to us