CSV Feeders in Gatling: Data‑Driven Authentication Tests Made Simple

Why CSV Feeders Matter for Real‑World Load Tests

When you simulate thousands of users hitting an authentication endpoint, you can’t hard‑code the same username/password for every virtual user (VU). Re‑using identical credentials leads to misleading results: the server’s rate‑limit logic, caching, or session handling may behave differently than in production. CSV feeders let you inject external data – one credential per VU – without sprinkling hard‑coded strings throughout your code.

1. Feeders 101 – The Gatekeeper of Dynamic Data

A feeder is a source of key/value maps that Gatling injects into the request context. The API supports CSV, JSON, Map, and custom functions. For authentication, a simple CSV with username,password headers is common.

Key points:

• Thread‑safe: Gatling pulls rows in a safe manner, but the strategy (shared vs per‑user) matters.
• Feeders are loaded once at simulation start; changes to the file after launch have no effect.
• Missing headers or malformed rows abort the simulation – validate your CSV before running.

2. Wiring a CSV Feeder into a Login Flow

Below is a minimal simulation that reads credentials from users.csv and posts them to /login. The example uses a per‑user feeder to avoid contention under high concurrency.

import io.gatling.core.Predef._
import io.gatling.http.Predef._

class LoginSimulation extends Simulation {
  val httpProtocol = http
    .baseUrl("https://example.com")
    .acceptHeader("application/json")

  // 1. Load the CSV once – each row is a Map[String, Any]
  val userFeeder = csv("users.csv").circular

  val loginScenario = scenario("Login with CSV credentials")
    .feed(userFeeder) // inject a row into the context
    .exec(http("Login Request")
      .post("/login")
      .formParam("username", "${username}")
      .formParam("password", "${password}")
      .check(status.is(200)))

  setUp(
    loginScenario.inject(atOnceUsers(10)) // 10 VUs for demo
  ).protocols(httpProtocol)
}

Explanation of the code:

• csv("users.csv").circular loads the file and cycles through rows indefinitely. Replace .circular with .random or .shuffle for different consumption patterns.
• The feed step injects the current row’s username and password into the request context, accessible via ${username} placeholders.
• All requests are executed under the same httpProtocol to share base URL and headers.

3. Shared vs Per‑User Feeders: Concurrency Trade‑offs

When you call csv("users.csv").circular once and feed it in a shared manner (the default), every VU pulls the next row from the same feeder instance. This is memory‑efficient but can cause contention when you have >1 k VUs: the feeder becomes a bottleneck, and you may exhaust the CSV rows before all VUs finish.

To avoid this, create a feeder per VU:

val perUserFeeder = csv("users.csv").circular

val scenario = scenario("Per‑user feeder")
  .feed(perUserFeeder) // each VU gets its own feeder instance
  ...

Pros:

• No contention – each VU reads from its own feeder copy.
• Predictable row consumption: each VU sees the same sequence.

Cons:

• Higher memory usage: one feeder instance per VU.
• Need to ensure the CSV file is large enough for the total number of rows required.

4. Practical Tips & Common Pitfalls

• File Size & Heap: Large CSVs increase JVM heap usage. If you need >10 k rows, consider streaming the file or splitting it into smaller chunks.
• Validation: Run gatling:run with -Dgatling.csv.validation=true (if your version supports it) to catch header mismatches early.
• Security: Never commit a CSV with real credentials to source control. Store secrets in environment variables or use Gatling’s DataFeeders that read from encrypted stores.
• Report Verification: After running, open target/gatling-*/reports/index.html. Under “HTTP Requests” verify that the number of Login Request entries equals VUs × iterations and that each request shows a different username in the request details.
• Fail‑fast on errors: If a feeder row is missing a column, Gatling aborts the simulation. Ensure the CSV is well‑formed before launch.

Actionable Takeaway

Use a CSV feeder to inject real, per‑user credentials into your Gatling simulations. Pick the feeder strategy that matches your concurrency level: shared for low‑to‑medium load, per‑user for high concurrency. Validate the CSV, keep it out of source control, and monitor heap usage for large datasets. With these practices, your authentication tests will reflect production traffic more accurately and give you trustworthy performance insights.