Using Gatling CSV Feeder for Parameterized Load Tests

Why Use a CSV Feeder in Gatling?

When you need realistic, per‑user data in a performance test—such as unique usernames or passwords—a CSV feeder injects values into scenario variables that can be referenced in HTTP requests or checks. This eliminates hard‑coded data and allows you to scale the test with a single file.

Basic Configuration Example

Below is a minimal Gatling script that reads a users.csv file, injects each row into the scenario, and performs a login request.

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

val httpProtocol = http
  .baseUrl("https://example.com")
  .acceptHeader("application/json")

// 1. Define the feeder – circular means it loops after the last row
val feeder = csv("users.csv").circular

// 2. Build the scenario
val scn = scenario("Login")
  .feed(feeder) // inject values into ${username} and ${password}
  .exec(http("Login request")
    .post("/login")
    .formParam("username", "${username}")
    .formParam("password", "${password}")
    .check(status.is(200)))

// 3. Run the simulation with 10 users at once
setUp(scn.inject(atOnceUsers(10)).protocols(httpProtocol))

Place users.csv in the classpath (e.g., src/test/resources) or provide an absolute path. The CSV must include a header row with column names that match the variable names used in the scenario.

Streaming Large CSV Files

By default, csv() loads the entire file into memory. For files larger than a few megabytes, this can trigger OutOfMemoryError. Gatling supports a streaming mode that reads rows on demand:

val feeder = csv("big_users.csv", delimiter = ';').streaming

Streaming is slower but memory‑efficient. If you need both speed and safety, split the file into smaller chunks or use .circular with a moderate size.

Common Pitfalls and How to Avoid Them

• Data Leakage Across Scenarios: Reusing the same feeder instance in multiple scenarios can cause rows to be shared unintentionally. Instantiate a separate feeder per scenario or reset the feeder with feeder.reset() before each use.
• Misspelled Column Names: If the CSV header does not match the variable name (e.g., user_name vs. username), Gatling injects null, which may lead to failed requests or confusing failures. Verify the header with a quick script or by inspecting the console output.
• Missing CSV File: A missing file causes the simulation to abort silently. Ensure the file is on the classpath or use an absolute path and check the console for a clear error message.
• Large In‑Memory Feeder: Forgetting to enable streaming on a large CSV leads to memory exhaustion. Use .streaming or split the file.

Verifying the Feeder Works

1. Create a two‑row CSV:

   username,password
   alice,alicePass
   bob,bobPass
   

2. Run the Gatling simulation and watch the console. You should see log lines containing the injected values, e.g., alice and bob alternating.
3. Open the generated HTML report (default: target/gatling) and navigate to the request details. Each login request should display a different username in the request body.

These steps confirm that the feeder is correctly injecting data and that your scenario uses the variables as intended.

Limitations

• Feeder data is immutable once loaded; you cannot modify values during a test.
• Streaming mode does not support .circular or .random strategies; you must use .random or .shuffle for non‑sequential access.
• Large files still consume disk I/O; keep an eye on the test machine’s I/O performance.

Practical Checklist Before Running a Production‑Grade Test

• Confirm the CSV header matches all variable names.
• Use .streaming for files >10 MB or when memory is constrained.
• Instantiate feeders per scenario or reset them between runs.
• Run a quick dry‑run with a small dataset to validate variable injection.
• Inspect the console and HTML report for correct values.