Data-driven runs

A data-driven run sends the same requests many times, each time with a different set of values. You put the values in a file, one row per run, and use the column names as {{variables}} in your requests. One request can then test ten users, fifty product ids or a list of bad inputs.

Run with a data file

This example fetches three users by id.

1. Create a file named users.csv:

   userId,name
   1,Ada
   2,Linus
   3,Grace

2. In a request, use the column names as variables:

   {{baseUrl}}/users/{{userId}}

3. Open the collection's menu and select Run collection to open the runner.

4. Select Data. The data panel opens.

5. Select Load data file and choose users.csv.

   The panel shows CSV: 3 rows, 2 columns — the run will do 3 iterations. and a preview of the rows.

6. Select Run.

The runner makes three passes. Pass 1 uses userId = 1 and name = Ada, pass 2 uses the second row, and so on. The Data button now reads Data (3 rows).

To stop using the file, select the × on the file's chip in the data panel.

Paste data

For a quick run you do not need a file. Open the data panel and paste JSON or CSV into the text box:

[{"userId": "1"}, {"userId": "2"}]

userId,name
1,Ada
2,Linus

The format is detected from the first character: [ or { means JSON, anything else is read as CSV. A loaded file takes priority over pasted text. Remove the file to use the pasted text again.

How rows map to iterations and variables

• One row is one iteration. Without Recurring, the run does exactly one pass per row. The Iterations setting is ignored.
• With Recurring on, the rows are cycled: pass 1 uses row 1, and after the last row the run starts again from the first.
• Each column is a variable. A column named userId is available as {{userId}} in the URL, params, headers, body and auth fields.
• Data values win over stored variables. If the environment, collection or globals has a variable with the same name as a column, the row's value is used for that pass. A temporary value set by a script with pm.variables.set is the only thing that overrides it.
• Rows are not saved. Data values are used for the run and never written to your environment.

In scripts, read the current row with pm.iterationData:

const expected = pm.iterationData.get("name");

pm.test("Name matches the data row", () => {
  pm.expect(pm.response.json().name).to.equal(expected);
});

Every data value is text. A CSV cell 42 and a JSON number 42 both arrive as the text 42, so compare with "42" or convert with Number().

Good to know

No-code tests do not fill in variables in their expected values. To compare a response with a value from the data row, use a script as above.

CSV files

The first line is the header: it names the columns. Every line after it is one row.

email,password,expectedStatus
ada@example.com,correct-horse,200
ada@example.com,wrong,401
"Smith, Jo",secret,200

Rule	Detail
Commas inside a value	Put the value in double quotes: "Smith, Jo"
Quotes inside a value	Quote the value and double the quote: "She said ""hi"""
Line breaks inside a value	Allowed inside a quoted value
Blank lines	Ignored
A row shorter than the header	Missing values are empty
A row longer than the header	Error naming the line. Quote values that contain commas.
A column with an empty name	Dropped
The same column name twice	Error: column names must be unique
Spaces around a column name	Trimmed. Spaces in values are kept.
Tab-separated values	A file ending in .tsv is read with tabs as separators

A file with a header and no rows is refused: "The CSV file has a header row but no data rows."

JSON files

A JSON data file is an array of objects. Each object is one row, and its keys are the column names.

[
  { "userId": 1, "name": "Ada", "admin": true },
  { "userId": 2, "name": "Linus", "admin": false }
]

JSON value	Becomes
Text	The same text
Number or boolean	Its text: 1, true
null	An empty value
A nested object or array	Its JSON text

A single object, not wrapped in an array, is read as one row. Rows may have different keys; a key that a row lacks is not set for that pass.

File rules

File types offered	.csv, .tsv, .json, .txt
How the format is chosen	By the extension for .csv, .tsv and .json; otherwise by the first character
Largest file	25 MB
Text encoding	UTF-8, or UTF-16 with a byte-order mark (what Excel saves as "Unicode text")
Preview	The first 20 rows. The run uses every row.

Problems are reported in the data panel with the file name and, for CSV, the line number.

Data files on the command line

The command-line runner takes the same files with -d:

apiworkbench-cli run shop.json -d users.csv

By default it runs one iteration per row. With -n you choose the count: fewer than the rows uses the first rows only, and more cycles through them again.

Ideas for data files

• One row per user role, with the status you expect each to get.
• A list of invalid inputs, each expected to return 400. See Negative testing.
• Boundary values: empty text, very long text, zero, negative numbers.

Data-driven testing covers how to choose good rows.

Next steps

• Collection runner: the other runner settings and the results view.
• Script cookbook: scripts that use pm.iterationData.
• Variables: how scopes override each other.