03 — HTTP Protocol Configuration

The HttpProtocolBuilder defines defaults shared by every HTTP request in the simulation. Configure it once and pass it to setUp.

---

Base URL

// Java
HttpProtocolBuilder httpProtocol = http.baseUrl("https://api.example.com");

// Kotlin
val httpProtocol = http.baseUrl("https://api.example.com")

All relative request paths are resolved against this URL. You can also provide multiple base URLs for round-robin load balancing:

http.baseUrls("https://api1.example.com", "https://api2.example.com")

---

Headers

HttpProtocolBuilder httpProtocol = http
    .baseUrl("https://api.example.com")
    .acceptHeader("application/json")
    .acceptEncodingHeader("gzip, deflate")
    .acceptLanguageHeader("en-US,en;q=0.5")
    .contentTypeHeader("application/json")
    .userAgentHeader("Gatling LoadTest/1.0")
    .header("X-Api-Version", "2");

Per-request headers override protocol-level headers.

---

Authentication

Basic auth

// Java
http.basicAuth("user", "password")

// Kotlin
http.basicAuth("user", "password")

Bearer token (static)

http.authorizationHeader("Bearer my-static-token")

Bearer token (dynamic — from session)

// Per-request (see 08-session.md for how to save the token)
http("Secure endpoint").get("/profile")
    .header("Authorization", session -> "Bearer " + session.getString("authToken"))

Digest auth

http.digestAuth("user", "password")

---

Connection management

http
    .maxConnectionsPerHost(6)          // default browser-like limit
    .shareConnections()                // all virtual users share connection pool
    .disableFollowRedirect()           // don't follow 3xx
    .maxRedirects(5)                   // default is 20

---

TLS / HTTPS

TLS trust store configuration is done via gatling.conf, not the DSL.

For self-signed certificates in dev environments, set in gatling.conf:

gatling {
  http {
    ssl {
      trustStore {
        type = "JKS"
        file = "certs/truststore.jks"
        password = "changeit"
      }
    }
  }
}

---

Proxy

http.proxy(
    Proxy("proxy.example.com", 8080)
        .credentials("proxyUser", "proxyPass")  // optional
)

---

Timeouts

Global defaults are configured in gatling.conf:

gatling {
  http {
    requestTimeout = 10000        # ms
    pooledConnectionIdleTimeout = 60000
    connectionTimeout = 10000
  }
}

You can override the request timeout per-request via the DSL:

http("Slow endpoint").get("/export")
    .requestTimeout(Duration.ofSeconds(30))

---

Automatic checks applied globally

You can add checks that apply to every request without repeating them:

http
    .check(status().not(500))       // fail all requests that return 500
    .check(status().not(503))

---

Full example

Java

HttpProtocolBuilder httpProtocol = http
    .baseUrl("https://api.example.com")
    .acceptHeader("application/json")
    .contentTypeHeader("application/json")
    .userAgentHeader("Gatling/3.15")
    .authorizationHeader("Bearer static-token")
    .maxConnectionsPerHost(10)
    .check(status().not(500));

Kotlin

val httpProtocol = http
    .baseUrl("https://api.example.com")
    .acceptHeader("application/json")
    .contentTypeHeader("application/json")
    .userAgentHeader("Gatling/3.15")
    .authorizationHeader("Bearer static-token")
    .maxConnectionsPerHost(10)
    .check(status().not(500))