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.

Many APIs and web applications protect their endpoints with HTTP Basic authentication — a scheme in which the client encodes a username:password pair in base64 and sends it in the Authorization request header. Load testing these endpoints correctly means supplying valid credentials for each virtual user, cycling through a pool of test accounts so that your users do not all share the same session, and verifying that authenticated requests return the expected responses. This guide shows how to achieve all of that with a CSV feeder and Gatling’s HTTP DSL.

​
Understanding HTTP Basic Authentication

When a server requires Basic authentication, it expects an Authorization header in the form: 
Authorization: Basic base64(username:password)
For example, user1:pass123 encodes to dXNlcjE6cGFzczEyMw==, producing: 
Authorization: Basic dXNlcjE6cGFzczEyMw==
Gatling’s .basicAuth(username, password) helper builds and attaches this header automatically, so you do not need to perform the base64 encoding yourself.

​
Step 1: Create the Credentials Feeder

Create a credentials.csv file in the resources folder of your Gatling project: 
username,password
user1,pass123
user2,pass456
user3,pass789
Never commit real production credentials to version control. Use test accounts with limited permissions, or retrieve credentials from a secrets manager at simulation startup.

​
Step 2: Write the Simulation

The simulation below feeds one credential pair per virtual user, uses that pair to authenticate, then exercises a protected API endpoint. 
import io.gatling.javaapi.core.*;
import io.gatling.javaapi.http.*;
import static io.gatling.javaapi.core.CoreDsl.*;
import static io.gatling.javaapi.http.HttpDsl.*;

import java.time.Duration;

public class BasicAuthSimulation extends Simulation {

  // Load credentials from CSV with circular strategy
  private final FeederBuilder<String> credentialsFeeder =
      csv("credentials.csv").circular();

  private final HttpProtocolBuilder httpProtocol =
      http.baseUrl("https://your-application.example.com")
          .acceptHeader("application/json");

  private final ScenarioBuilder scn = scenario("Basic Auth Scenario")
      .feed(credentialsFeeder)
      // GET the login page (unauthenticated)
      .exec(http("Get Login Page")
          .get("/login")
          .check(status().is(200)))
      .pause(Duration.ofSeconds(2))
      // POST with Basic Auth credentials
      .exec(http("Authenticated Request")
          .post("/api/protected")
          .basicAuth("#{username}", "#{password}")
          .check(status().is(200)));

  {
    setUp(
      scn.injectOpen(rampUsers(50).during(Duration.ofSeconds(30)))
    ).protocols(httpProtocol);
  }
}

​
Key Code Concepts

ComponentPurpose
csv("credentials.csv").circular()Loads the CSV and loops through records so the feeder never exhausts
feed(credentialsFeeder)Injects the next username and password into the current virtual user’s session
"#{username}"Gatling Expression Language — reads the value from the session
.basicAuth("#{username}", "#{password}")Encodes the credentials and sets the Authorization header
rampUsers(50).during(30)Gradually injects 50 users over 30 seconds to simulate a realistic load ramp

​
Update the URLs

The code examples use placeholder URLs. Before running the simulation, update:
  • baseUrl — point to your application’s base URL
  • /login — replace with your application’s actual login or landing path
  • /api/protected — replace with the authenticated endpoint you want to test

​
Best Practices

Use separate test accounts

Provision dedicated test user accounts with limited permissions. This prevents rate limiting and avoids accidentally impacting shared state in your test environment.

Add assertions

Use .check(status().is(200)) on every request to catch authentication failures during the test and include global().failedRequests().percent().lt(5.0) in your setUp assertions.

Include think times

Add .pause() calls between requests to simulate the time a real user spends reading a page before clicking the next link. This prevents artificially high request rates.

Handle re-authentication

If your application uses session tokens that expire, model the token refresh call in your scenario so virtual users re-authenticate when needed rather than accumulating errors.

Build docs developers (and LLMs) love

Get started for freeTalk to us