skip to content

In a Newman command line, what does the `-d` data file do to a collection run, and how does a script read the current row?

level: juniorimportance: must knowfreq 70%

answer

  1. One flag turns one run into many
  2. The row arrives as a scope
  3. Rows in, iterations out
  4. pm.iterationData holds this pass's columns

basics

~10 s

Newman's -d flag takes a data file and runs the whole collection once per row. Each row becomes that iteration's pm.iterationData scope, so a script reads its columns with pm.iterationData.get('column').

solid answer

~40 s

`-d` (long form `--iteration-data`) is a CLI flag that hands the runner a file of rows. Instead of one pass over the collection, the runner performs one **iteration per row** — the same saved requests, executed again, with a different record in play each time. The collection file is not modified and knows nothing about the file; the runner injects the row. Inside a script the row for the iteration currently executing is the sandbox scope `pm.iterationData`, whose keys are that row's columns: `pm.iterationData.get('email')` returns one value and `pm.iterationData.toObject()` returns the whole row. The scope is swapped for the next row when the next iteration starts, so nothing leaks forward on its own. With `-d` and no explicit count, the number of rows decides how many iterations run.

code

bash · 1 line
bash
newman run orders.postman_collection.json -d customers.json

go deeper

for a junior

Be ready to say what the data file flag does in one sentence: the whole collection runs once per row. Then name pm.iterationData as the thing a script reads the current row from.

for a middle

Explain the mechanics: the runner injects a fresh scope per iteration, the collection document is untouched, and the row count decides the iteration count unless a count is passed explicitly.

for a senior

Show the operational habits — asserting the columns you depend on, logging the row so a failure names its record, and keeping the data file reviewed as its own input rather than smuggled into the collection.

for a principal

Own the boundary question: which variation belongs in a data file versus in the collection or the environment, and how many records a run should carry before it stops being a check and becomes a batch job.

## One saved file, many runs A **collection run** normally executes the saved requests once, in order, and stops. Newman's `-d` flag (long form `--iteration-data`) changes the shape of that run: you hand the CLI a data file whose rows are records, and the runner executes **the whole collection once per row**. Five rows means five passes over exactly the same requests, each pass seeing a different record. The unit of repetition is an **iteration**. One row in, one iteration out. Nothing in the collection file changes — the requests are not rewritten, no field is added to the saved document, and the same collection still runs standalone when no data file is supplied. The data file lives entirely outside the artefact, which is why the same collection can be driven by a smoke-sized file locally and a much larger one elsewhere. ## Where the row lands: `pm.iterationData` The row belonging to the iteration currently executing is exposed to scripts by the sandbox as **`pm.iterationData`**, a variable scope whose keys are that row's columns: - `pm.iterationData.get('email')` returns the value of the `email` column for **this** iteration. - `pm.iterationData.has('email')` reports whether that column exists at all, which is how you tell a missing column from an empty one. - `pm.iterationData.toObject()` returns the whole row as a plain object, handy for logging what the iteration is actually working on. - The scope is **replaced** when the next iteration begins; the previous row's values do not linger into the next pass. Attribution matters here. `-d` is a **CLI flag**. `pm.iterationData` is a **sandbox** member. There is no field in the collection format that declares a data file, and no class you configure — the runner puts the row in front of each iteration and the script reads it. ## How many iterations you get The count is decided by the flags you pass, not by anything in the collection: | what you pass | iterations executed | what each iteration reads | |---|---|---| | `-d rows.csv` alone | one per row in the file | that row | | `-n` alone, no data file | the count you asked for | nothing; `pm.iterationData` is empty | | `-d rows.csv` with a smaller `-n` | the smaller count | the leading rows only | | `-d rows.csv` with a larger `-n` | the larger count | the rows, then the **last row repeated** | That final row of the table is the one people get wrong under interview pressure: **a count past the data's last row repeats that last row.** It does not wrap around to the first row, and it does not raise an error. ## Reading the row in practice 1. Put one column in the file for each value the request needs to vary by, and give the columns names a script can read literally. 2. In a pre-request script, pull what you need with `pm.iterationData.get(...)` and use it to build whatever the request needs. 3. In a test script, compare the response against the **same row**, so each iteration checks its own expectation instead of one hardcoded value that only suits the first record. 4. Log `pm.iterationData.toObject()` while developing, so a failing iteration tells you which record produced it rather than only that something failed. ## What travels between iterations, and what does not - The row is **per iteration** by construction: a value read in the first pass is simply gone in the second unless the file carries it again. - The collection's own requests are unchanged between iterations; only the data in front of them differs. - Whether a value written by a script survives into the next iteration is a **different** mechanism with different lifetime rules, and it is not what `pm.iterationData` does. - How the file itself is written — its separator, its quoting, how a blank cell is represented, whether a header line is skipped — is a property of the data format, not of this mechanism. ## Why interviewers ask it Because it is the cheapest way to find out whether a candidate has actually run a suite against more than one record. The follow-up is almost always about the disagreement case: what happens when the count and the file do not match. Someone who has only read about the flag says it wraps or errors; someone who has watched a run says the last row comes round again, quietly, with everything still green.

  • If a script reads a column that the data file does not contain, what does it get back?
    `pm.iterationData.get('missing')` returns `undefined` rather than throwing, so a typo in a column name silently produces an empty value instead of an error. `pm.iterationData.has('missing')` is the explicit check, and asserting the columns you depend on at the start of the run turns a silent blank into a named failure on the first iteration.
  • Does the data file change the collection, or does it have to be checked in alongside it?
    It changes nothing in the collection: the saved document has no field naming a data file, and the same collection runs unchanged without one. The file is a separate input supplied on the command line, so it is versioned and reviewed on its own terms, and different files can drive the same collection.

The collection is a single stencil and the data file is the stack of sheets: the same shape is traced once per sheet, and the stencil itself is never cut.

saying these in an interview costs you the question

  • Says the data file is imported into the collection document
  • Thinks one row maps to one request, not one whole run
  • Reaches for a global to hold the current row instead of pm.iterationData
  • Assumes values from the previous row remain readable in the next iteration
  • Cannot name the scope that exposes the row to a script