Feeders: Injecting Test Data Into Gatling Sessions

Feeders are Gatling’s mechanism for supplying each virtual user with unique, realistic test data—usernames, search keywords, product IDs, addresses, and anything else that makes your load test representative of real traffic. A feeder is fundamentally an Iterator<Map<String, Object>>: each time a virtual user reaches a feed step in the scenario, it polls one record from the iterator and injects every key-value pair from that record into its Session as new attributes. Those attributes are then available throughout the rest of the scenario via EL expressions such as "#{username}".

The Writing realistic tests guide walks through practical examples of combining feeders with scenario logic.

Using the `feed` Method

The feed method is called in a scenario chain at the same position as exec. Every virtual user that reaches this step picks up the next available record.

Java

scenario("My scenario")
  .feed(csv("users.csv"))
  .exec(http("login")
    .post("/login")
    .formParam("username", "#{username}")
    .formParam("password", "#{password}"))

To feed multiple records at once, pass a count. The values become Java List (or Scala Seq) instances in the Session:

Java

.feed(csv("products.csv"), 3)
// Session now contains "productId" as List<String> with 3 values

In-Memory Feeders

For small datasets or dynamically generated data, use arrayFeeder (for arrays) or listFeeder (for lists):

Java

// Using an array
arrayFeeder(new Map[] {
  Map.of("username", "alice", "role", "admin"),
  Map.of("username", "bob",   "role", "user")
});

// Using a List
listFeeder(List.of(
  Map.of("username", "alice", "role", "admin"),
  Map.of("username", "bob",   "role", "user")
));

Scala

// Using an Array (implicit conversion to feeder)
Array(
  Map("username" -> "alice", "role" -> "admin"),
  Map("username" -> "bob",   "role" -> "user")
)

// Using an IndexedSeq (implicit conversion to feeder)
IndexedSeq(
  Map("username" -> "alice", "role" -> "admin"),
  Map("username" -> "bob",   "role" -> "user")
)

File-Based Feeders

File Placement

SDK	Root directory
Java / Kotlin / Scala (Maven)	`src/main/resources` or `src/test/resources`
Java / Kotlin / Scala (Gradle)	`src/gatling/resources`
JavaScript / TypeScript	`resources/`

Configure paths relative to the resource root—never use paths starting with src/:

// Correct
csv("data/users.csv")

// Wrong — don't do this
csv("src/test/resources/data/users.csv")

CSV / TSV / SSV Feeders

Gatling parses character-separated value files conforming to RFC 4180. Header field names are trimmed of surrounding whitespace.

// Comma-separated (CSV)
csv("data/users.csv")

// Tab-separated (TSV)
tsv("data/users.tsv")

// Semicolon-separated (SSV)
ssv("data/users.ssv")

// Custom separator
separatedValues("data/users.txt", '|')

JSON Feeders

Load records from a JSON file whose root element is an array of objects:

Java

jsonFile("data/products.json")
// or from an inline JSON string:
jsonUrl("https://api.example.com/test-data")

Given the file:

[
  { "id": 19434, "category": "electronics" },
  { "id": 19435, "category": "clothing" }
]

Each record becomes a Session map: { "id" -> 19434, "category" -> "electronics" }.

The root element of a JSON feeder file must be a JSON array.

JDBC Feeder

Pull records directly from a relational database using a JDBC connection. Requires a JDBC 4-compliant driver JAR on the classpath.

Java

jdbcFeeder("jdbc:postgresql://localhost/mydb", "username", "password",
  "SELECT username, password FROM test_users")

Scala

jdbcFeeder("jdbc:postgresql://localhost/mydb", "username", "password",
  "SELECT username, password FROM test_users")

Place the JDBC driver JAR in your project’s lib/ folder (for the bundle) or as a test dependency in Maven/Gradle.

Redis Feeder

Read data from a Redis instance using one of four commands:

// Remove and return the first element of a list
redisFeeder(redisPool, "gatling:users:queue")

Feeder Strategies

Every file-based feeder supports four strategies that control how virtual users pick records. The strategy is applied by chaining it after the feeder builder.

queue (default)
random
shuffle
circular

Each user consumes a unique record in file order. Records cannot be reused. The test crashes if more records are requested than available.

csv("users.csv").queue()

Use when: credentials or IDs must not be shared between users.

Each user picks a random record. Records can repeat; the feeder never runs out.

csv("keywords.csv").random()

Use when: you don’t mind duplicate data (e.g., search terms).

Like queue but the order is randomized upfront. Records are still consumed uniquely. Crashes when exhausted.

csv("users.csv").shuffle()

Use when: unique records are required but order doesn’t matter.

Records are consumed in file order, wrapping back to the start when the end is reached. Records can repeat.

csv("products.csv").circular()

Use when: you want sequential order but with an unlimited supply.

Both queue and shuffle will cause Gatling to crash if you try to consume more records than the feeder contains. Size your data files appropriately for your virtual user count.

Zipped Files

For large feeder files, you can provide them compressed and have Gatling decompress on the fly:

Java

csv("data/users.csv.gz").unzip()   // gzip
csv("data/users.csv.zip").unzip()  // zip (must contain exactly one file)

Distributed Files (Enterprise)

When running distributed tests with Gatling Enterprise, use shard to split the dataset across load generators so no two generators use the same records:

Java

csv("data/users.csv").shard()

For example, 30,000 records split across 3 load generators gives each one a unique 10,000-record slice.

shard is a no-op when running locally with the Community Edition. It only has effect on Gatling Enterprise.

Transforming Records

Apply transformations to raw feeder values before they are injected into the Session. This is useful when the source format (e.g., CSV strings) doesn’t match the type your requests expect.

Java

csv("products.csv")
  .transform((key, value) -> {
    if (key.equals("price")) return Double.parseDouble((String) value);
    return value;
  })

Scala

csv("products.csv")
  .transform { case ("price", v) => v.toDouble }

Reading Records into Memory

You can load all feeder records into a Java List or Scala Seq for custom use, such as computing the total count before the test:

Java

var records = csv("users.csv").readRecords();
int total = records.size();

Each readRecords() call re-parses the source file from scratch. Do not call it in a hot path.

Counting Records Without Loading All Data

Java

int count = csv("users.csv").recordsCount();

Custom Feeders

A feeder is any Iterator<Map<String, Object>>. Implement one directly to generate data programmatically:

Java

// Random email generator
Iterator<Map<String, Object>> randomEmailFeeder = Stream.generate(() -> {
  String uuid = UUID.randomUUID().toString().replace("-", "").substring(0, 8);
  return Map.<String, Object>of("email", uuid + "@example.com");
}).iterator();

scenario("custom feeder").feed(randomEmailFeeder)

Scala

val randomEmailFeeder: Iterator[Map[String, Any]] =
  Iterator.continually(
    Map("email" -> (UUID.randomUUID().toString.replace("-", "").take(8) + "@example.com"))
  )

scenario("custom feeder").feed(randomEmailFeeder)

HTTP Protocol

Other Protocols

Session & Data

Feeders: Injecting Test Data Into Gatling Sessions

Using the `feed` Method

In-Memory Feeders

File-Based Feeders

File Placement

CSV / TSV / SSV Feeders

JSON Feeders

JDBC Feeder

Redis Feeder

Feeder Strategies

Zipped Files

Distributed Files (Enterprise)

Transforming Records

Reading Records into Memory

Counting Records Without Loading All Data

Custom Feeders

Build docs developers (and LLMs) love

HTTP Protocol

Other Protocols

Session & Data

Documentation Index

​Using the feed Method

​In-Memory Feeders

​File-Based Feeders

​File Placement

​CSV / TSV / SSV Feeders

​JSON Feeders

​JDBC Feeder

​Redis Feeder

​Feeder Strategies

​Zipped Files

​Distributed Files (Enterprise)

​Transforming Records

​Reading Records into Memory

​Counting Records Without Loading All Data

​Custom Feeders

Build docs developers (and LLMs) love

Using the `feed` Method

In-Memory Feeders

File-Based Feeders

File Placement

CSV / TSV / SSV Feeders

JSON Feeders

JDBC Feeder

Redis Feeder

Feeder Strategies

Zipped Files

Distributed Files (Enterprise)

Transforming Records

Reading Records into Memory

Counting Records Without Loading All Data

Custom Feeders