Parameterizing Gatling Simulations with CSV Feeders

Preventing Cache Hits with Dynamic Data

Static load tests often produce misleading results because servers cache identical requests, hiding the real performance of database queries and backend logic. To simulate real‑world traffic, you must parameterize your requests using Feeders.

A Feeder is a mechanism that injects dynamic data into a virtual user’s session. By loading a CSV file, Gatling can assign unique identifiers, usernames, or tokens to each request, forcing the server to process the request fully rather than serving a cached response.

Implementing a CSV Feeder

Gatling reads CSV files into memory as a Map, where the header row defines the keys used to reference data in the simulation script. This is achieved using the csv() method combined with a distribution strategy.

Configuration Example

Assume a file named users.csv located in src/test/resources/data/users.csv with the following content:

username,password
user_01,pass123
user_02,pass456
user_03,pass789

The following Scala simulation demonstrates how to load this data and inject it into a POST request:

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

class UserSimulation extends Simulation {
  // Load the CSV and set the distribution strategy to random
  val userFeeder = csv("data/users.csv").random

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

  val scn = scenario("Login Scenario")
    .feed(userFeeder) // Inject data into the session
    .exec(http("Login Request")
      .post("/login")
      .formParam("user", "${username}") // Access CSV header via EL
      .formParam("pwd", "${password}")
    )

  setUp(
    scn.inject(atOnceUsers(10))
  ).protocols(httpProtocol)
}

Choosing a Distribution Strategy

• .random(): Picks a random row for each request. This is ideal for reducing database contention on specific records.
• .circular(): Cycles through the file from top to bottom. Once the end is reached, it restarts at the first row. This ensures every data point is used at least once.
• .queue(): Hands out each row exactly once. If the queue empties before all users are finished, the simulation will fail with a NoSuchElementException.

Operational Constraints and Risks

Memory Management

By default, Gatling loads the entire CSV file into RAM. For datasets containing millions of rows, this can trigger OutOfMemoryError failures. If your dataset exceeds available heap space, consider splitting the data into multiple smaller files or utilizing a custom feeder that streams data from a database.

CSV Formatting

• Mismatched Quotes: Unclosed quotes in a cell can cause the parser to skip rows or fail at startup.
• Delimiter Conflicts: If your data contains commas, ensure the fields are properly quoted or use a different delimiter configuration.
• Header Mismatches: If the simulation references ${userId} but the CSV header is user_id, the request will be sent with the literal string ${userId} instead of the actual value.

Verification and Testing

To verify that the feeder is working as intended, follow these steps:

1. Log Inspection: Enable gatling.http.request.log.level = DEBUG in your gatling.conf file. Check the console output to ensure different values are being sent for each virtual user.
2. Loop Validation: Run a simulation with 100 users using a CSV file that only contains 10 rows and the .circular() strategy. If the simulation completes without error, the looping mechanism is functioning.
3. Empty Queue Check: Attempt to run a .queue() feeder with more users than available rows. The simulation should crash, confirming that your data volume is insufficient for the intended load.