Quality is not optional. It's our standard. Free QA tools for testers and developers.

Postman Test Data Generation with CSV and JSON Files

QTQA3 Team

Postman Test Data Generation with CSV and JSON Files

When an API test suite grows beyond a handful of requests, the same static payloads start to hide bugs. A single “happy‑path” JSON body cannot expose validation limits, enum drift, or schema‑evolution problems. The usual fix is to feed the collection with data‑driven inputs—CSV rows for tabular scenarios, JSON files for nested structures—so each iteration exercises a different combination without rewriting the request.

This guide walks through the practical decisions, a repeatable workflow, a worked example, common pitfalls, and a concrete next step you can take today.


1. Why Data‑Driven Testing Matters in Postman

SymptomRoot causeData‑driven remedy
Flaky tests that pass on one run and fail on anotherHard‑coded values that happen to satisfy current validationRotate values from a source file each run
New field added to the contract but tests still passTest payload never exercised the new fieldInclude the field in the data set with both valid and invalid samples
Exploratory testing limited to a few manual runsNo systematic way to combine parametersGenerate Cartesian products from CSV/JSON and let the runner iterate

Postman’s Collection Runner and Newman CLI both accept a data file (-d / --iteration-data). The runner substitutes variables ({{variable}}) in the request body, URL, headers, and scripts with the column values from each row (CSV) or each object (JSON).


2. Choosing Between CSV and JSON

DimensionCSVJSON
StructureFlat, one‑level key/value per columnArbitrary nesting, arrays, objects
Human readabilityExcellent for tabular data (e.g., user IDs, status codes)Good for hierarchical payloads (e.g., address → city → zip)
Tooling supportSpreadsheet editors, csvkit, pandasjq, VS Code, most language libraries
Size limitsHandles millions of rows comfortablyLarge files can become memory‑heavy in the runner
Version control friendlinessDiffable line‑by‑lineDiffable but noisy for deep nesting
Typical use‑caseParameter sweeps, lookup tables, configuration matricesFull request bodies, complex nested objects, polymorphic payloads

Rule of thumb – start with CSV for parameterisation (query strings, path variables, header values). Switch to JSON when the request body itself is the variable under test.


3. Decision Criteria Checklist

Before you commit to a format, run through the checklist. If you answer “yes” to a majority of the JSON column, lean that way.

QuestionCSV ✔JSON ✔
Does the test need to vary only a handful of scalar values?☐☐
Is the request body a deep object with optional arrays?☐☐
Will non‑technical stakeholders edit the data (e.g., product owners)?☐☐
Do you need to store multiple payload variants per iteration (e.g., request + expected response)?☐☐
Is the data set expected to exceed 100 k rows?☐☐
Do you already have a CI step that outputs JSON artifacts?☐☐

4. End‑to‑End Workflow

Below is a repeatable pipeline you can embed in a repository.

  1. Define the data contract – a JSON Schema or OpenAPI component that describes every variable you will inject.
  2. Generate seed files – use a script, a spreadsheet, or QA3’s free test data generator at /tools/test-data-generator to produce a starter CSV/JSON.
  3. Version‑control the data – commit the files under test-data/ with a clear naming convention (users.csv, order-payloads.json).
  4. Parameterise the collection – replace literals with {{variable}} placeholders in the request body, URL, headers, and pre‑request scripts.
  5. Add validation scripts – in the Tests tab, assert that the response matches the expected shape for the current data row (e.g., pm.expect(pm.response.json().id).to.equal(pm.iterationData.get('expectedId'))).
  6. Run locally with Collection Runner – verify a few iterations manually.
  7. Automate in CI – invoke newman run <collection>.json -d test-data/users.csv -r cli,htmlextra.
  8. Report & triage – parse Newman’s JSON output, feed failures into your ticketing system.
  9. Iterate – when the API contract changes, update the schema, regenerate data, and bump the collection version.

5. Worked Example: Order‑Service API

5.1. API Surface

MethodEndpointDescription
POST/ordersCreate an order
GET/orders/{id}Retrieve an order
PATCH/orders/{id}Update status

The create payload (simplified)

{
  "customerId": "string",
  "items": [
    {
      "sku": "string",
      "quantity": "integer",
      "unitPrice": "number"
    }
  ],
  "shippingAddress": {
    "street": "string",
    "city": "string",
    "postalCode": "string",
    "country": "string"
  },
  "metadata": {}
}

5.2. Data‑Set Design

We need to exercise:

  • Valid customer IDs (existing, new, malformed)
  • Item arrays of varying length (0, 1, 5, 100)
  • Edge‑case numeric values (zero, negative, max‑int)
  • Address fields with Unicode, missing optional lines

Because the payload is nested, JSON is the natural choice for the body, while CSV works well for the scalar parameters that live outside the body (e.g., customerId in the URL for GET/PATCH).

5.2.1. CSV – order-params.csv

iterationcustomerIdexpectedStatustestCaseId
1CUST-001201TC-001
2CUST-999404TC-002
3invalid-id!400TC-003
4CUST-002201TC-004

5.2.2. JSON – order-bodies.json

[
  {
    "iteration": 1,
    "body": {
      "customerId": "{{customerId}}",
      "items": [
        { "sku": "SKU-100", "quantity": 2, "unitPrice": 19.99 }
      ],
      "shippingAddress": {
        "street": "123 Main St",
        "city": "Springfield",
        "postalCode": "12345",
        "country": "US"
      },
      "metadata": { "source": "web" }
    },
    "expected": { "status": 201, "orderIdRegex": "^ORD-[A-Z0-9]{8}$" }
  },
  {
    "iteration": 2,
    "body": {
      "customerId": "{{customerId}}",
      "items": [],
      "shippingAddress": {
        "street": "456 Oak Ave",
        "city": "Shelbyville",
        "postalCode": "67890",
        "country": "US"
      },
      "metadata": {}
    },
    "expected": { "status": 400, "errorCode": "EMPTY_ITEMS" }
  },
  {
    "iteration": 3,
    "body": {
      "customerId": "{{customerId}}",
      "items": [
        { "sku": "SKU-200", "quantity": -1, "unitPrice": 0 }
      ],
      "shippingAddress": {
        "street": "789 Elm Blvd",
        "city": "Capital City",
        "postalCode": "00000",
        "country": "US"
      },
      "metadata": { "source": "mobile" }
    },
    "expected": { "status": 400, "errorCode": "INVALID_QUANTITY" }
  },
  {
    "iteration": 4,
    "body": {
      "customerId": "{{customerId}}",
      "items": [
        { "sku": "SKU-300", "quantity": 1, "unitPrice": 999999.99 }
      ],
      "shippingAddress": {
        "street": "101 Maple Dr",
        "city": "Metropolis",
        "postalCode": "11111",
        "country": "CA"
      },
      "metadata": { "promo": "SUMMER21" }
    },
    "expected": { "status": 201, "orderIdRegex": "^ORD-[A-Z0-9]{8}$" }
  }
]

Note – The {{customerId}} placeholder will be resolved from the CSV row that shares the same iteration index. Postman matches rows by line number (1‑based) when you feed both a CSV and a JSON file; the JSON file is treated as the iteration data and the CSV as global variables. To keep things simple, we’ll use only the JSON file and embed customerId inside each object (see next section).

5.3. Single‑Source JSON Approach

Postman can read one data file per run. If you want the CSV values to drive the JSON bodies, you have two options:

  1. Pre‑process – a small Node/Python script merges CSV rows into the JSON objects, producing a final iteration-data.json.
  2. Use pm.iterationData in a pre‑request script – read the CSV via pm.globals.get('csvData') (you’d have to load the CSV as a string beforehand).

For most teams, option 1 is cleaner and keeps the runner stateless. Below is a minimal Node script (merge-data.js) that produces the final file.

// merge-data.js
const fs = require('fs');
const csv = require('csv-parse/sync');


const csvText = fs.readFileSync('test-data/order-params.csv', 'utf8');
const jsonText = fs.readFileSync('test-data/order-bodies.json', 'utf8');


const csvRows = csv.parse(csvText, { columns: true, skip_empty_lines: true });
const jsonRows = JSON.parse(jsonText);


const merged = jsonRows.map((j, i) => {
  const c = csvRows[i] || {};
  return {
    ...j,
    body: {
      ...j.body,
      customerId: c.customerId ?? j.body.customerId
    },
    expected: {
      ...j.expected,
      status: Number(c.expectedStatus) ?? j.expected.status
    }
  };
});


fs.writeFileSync('test-data/iteration-data.json', JSON.stringify(merged, null, 2));
console.log('Merged', merged.length, 'iterations');

Run it once (node merge-data.js) before each CI build or commit the generated file if the data is static.

5.4. Collection Parameterisation

  1. Open the Create Order request.
  2. In the Body tab, select raw → JSON and paste:
{{body}}
  1. In the Tests tab, add validation that uses the expected block:
const data = pm.iterationData.toObject();
const expected = data.expected;


pm.test(`Status code is ${expected.status}`, () => {
  pm.response.to.have.status(expected.status);
});


if (expected.orderIdRegex) {
  pm.test('Order ID matches pattern', () => {
    const orderId = pm.response.json().orderId;
    pm.expect(orderId).to.match(new RegExp(expected.orderIdRegex));
  });
}


if (expected.errorCode) {
  pm.test('Error code matches', () => {
    const err = pm.response.json().errorCode;
    pm.expect(err).to.equal(expected.errorCode);
  });
}
  1. Save the collection.

5.5. Local Run

newman run OrderService.postman_collection.json \
  -d test-data/iteration-data.json \
  -r cli,htmlextra \
  --reporter-htmlextra-export reports/run-$(date +%s).html

Open the HTML report; each iteration shows the request body, response, and pass/fail status.


6. Validation Checks You Should Automate

CheckWhere to implementWhy it matters
Schema conformance (request)Pre‑request script (tv4/ajv)Guarantees you’re not sending malformed JSON that the runner would silently ignore
Schema conformance (response)Test script (ajv)Detects contract drift early
Unique‑key enforcement (e.g., orderId)Test script + DB cleanupPrevents flaky “duplicate key” errors on re‑run
Data‑range sanity (quantity > 0, price ≥ 0)Pre‑request scriptCatches generator bugs before they hit the API
Iteration‑count parity (CSV rows = JSON objects)CI step (node -e "…")Avoids silent truncation or extra iterations
Sensitive‑data maskingPost‑run script (replace PII in reports)Keeps logs compliant

A minimal pre‑request schema guard (using ajv bundled in Postman):

const Ajv = require('ajv');
const ajv = new Ajv({ allErrors: true });


const requestSchema = {
  type: 'object',
  required: ['customerId', 'items', 'shippingAddress'],
  properties: {
    customerId: { type: 'string', minLength: 1 },
    items: {
      type: 'array',
      minItems: 1,
      items: {
        type: 'object',
        required: ['sku', 'quantity', 'unitPrice'],
        properties: {
          sku: { type: 'string', pattern: '^SKU-\\d+$' },
          quantity: { type: 'integer', minimum: 1 },
          unitPrice: { type: 'number', minimum: 0 }
        }
      }
    },
    shippingAddress: {
      type: 'object',
      required: ['street', 'city', 'postalCode', 'country'],
      properties: {
        street: { type: 'string' },
        city: { type: 'string' },
        postalCode: { type: 'string', pattern: '^\\d{5}$' },
        country: { type: 'string', enum: ['US', 'CA', 'MX'] }
      }
    }
  }
};


const validate = ajv.compile(requestSchema);
const payload = pm.iterationData.get('body');


if (!validate(payload)) {
  console.error('Request schema validation failed:', validate.errors);
  pm.test('Request schema valid', () => { throw new Error('Invalid request payload'); });
}

7. Common Pitfalls & Mitigations

PitfallSymptomMitigation
Mismatched iteration countRunner stops early or throws “iteration data exhausted”Add a CI gate: node -e "const a=require('./csv'); const b=require('./json'); if(a.length!==b.length) process.exit(1);"
Variable name collision{{id}} resolves to the wrong columnPrefix all placeholders with a domain ({{order.id}}, {{customer.id}}`) and keep a naming

Read more

GraphQL Test Data Generation for Queries and Mutations

A practical guide to “GraphQL Test Data Generation for Queries and Mutations,” with worked scenarios, tool considerations, validation checks, and actionable advice for QA teams.

Generate API Test Data Directly from an OpenAPI Specification

A practical guide to “Generate API Test Data Directly from an OpenAPI Specification,” with worked scenarios, tool considerations, validation checks, and actionable advice for QA teams.

JSON Test Data Generator Guide for QA Engineers

A practical guide to “JSON Test Data Generator Guide for QA Engineers,” with worked scenarios, tool considerations, validation checks, and actionable advice for QA teams.