# How to Write Postman Performance Test Scripts That Scale

A Postman performance test is only as good as the script behind it. A collection that works for one request can quietly misbehave when 50 virtual users run it at once: a variable that was never set, an assertion that only holds for one record, a sign-in that every user fires in the same second. This post walks through building that script: getting a collection, chaining requests, writing assertions that mean something under load, signing in and cleaning up with setup and teardown, feeding it data, and, just as important, debugging it before you add load. Once it runs cleanly, you can try it in the app and then take it to CI with the Postman CLI or Postman Cloud.

## The workflow at a glance

1. **Get a collection**: import your OpenAPI spec, or record it with the Postman proxy, fork one, or write it.
2. **Script it**: chain values between requests and control the pace.
3. **Assert** on correctness and on a response-time budget.
4. **Sign in and clean up** with setup and teardown collections.
5. **Feed it data** with a data file or a dataset.
6. **Debug it** at one user, before you add load.
 
 *You will loop between Debug and Script until a one-VU run is clean, and only then run it at scale.*## What a performance test script is

 There is no separate scripting language for performance tests. A performance test runs the requests in your collection (or one folder), in order, in a repeating loop, for every virtual user (VU) at once, for a set duration. The pre-request scripts, post-response scripts and `pm.test()` assertions you already write run on every pass of that loop, under load, the same way they run in a functional run. That has two consequences for how you write them: - **Your script runs thousands of times.** A slow or noisy script is multiplied by every request, every VU, every iteration. On a local run, scripts reduce the number of VUs the machine can simulate.
- **Many copies run at once.** Anything that assumes it is the only user (a shared record, a one-time sign-in, a counter) behaves differently when it is not.
 
## Prerequisites

- The Postman desktop app (it is also where you run a local performance test) and a workspace.
- Docker, to run the demo app below.
- For Step 5: a paid plan if you want datasets or data files in a performance test.
 
## Set up the demo app

 The examples use [Swagger Petstore](https://github.com/swagger-api/swagger-petstore), an open source (Apache-2.0) sample REST API with an OpenAPI spec. It runs on your own machine, which matters: never point a load test at a shared public service, and never at production. The app listens on 8080 inside the container; this maps it to **18080** on your machine, because 8080 is one of the most commonly used ports and a clash fails quietly (see Step 6, pointer 4). To check that 18080 is free first, run `lsof -nP -iTCP:18080 -sTCP:LISTEN` (macOS and Linux); no output means it is free. Give it a few seconds. The OpenAPI spec is at `http://localhost:18080/api/v3/openapi.json`. Four things worth knowing before you start: - **Pin the tag.** The README suggests `:unstable`, which is a March 2023 build. `1.0.28` is the current release.
- **Timings are not benchmarks.** The image is built for amd64 only, so on Apple Silicon it runs under emulation.
- **State lives in memory.** Restart the container for a clean slate.
- **Auth is declared but not enforced.** The spec lists OAuth2 and an `api_key` header, but the server accepts requests without either, so there is no real token to chain. Step 2 notes where that matters.
 
## Step 1: Get a collection

 A performance test needs one thing: a collection (or one folder of one). The rest of this post uses a single collection, **Petstore Load**, built from the app's OpenAPI spec, so that is the route described in detail. The other ways to get a collection get a line each at the end of this step. ### Import the OpenAPI spec

 If your API has an OpenAPI spec, this is usually the fastest route, and it doubles as a check that the spec matches reality. Importing a spec in the Postman app gives you the spec *and* a collection generated from it, in one step. In the app: 1. Click **Import**.
2. Add Petstore's spec: paste its link, `http://localhost:18080/api/v3/openapi.json`, or save it with `curl -o openapi.json http://localhost:18080/api/v3/openapi.json` and drag the file in.
3. Leave the import option as it is. **OpenAPI 3.0** is already selected, and it brings in the specification together with a collection generated from it.
4. Press **Enter** to import and wait for it to finish. Then rename the new collection to **Petstore Load**.
 
 Importing Petstore's OpenAPI spec: paste the link, press Enter, and Postman creates the spec and a collection. Petstore's spec has 19 operations, so you get **19 requests**, one per operation, grouped into folders by path, each with saved examples for the documented responses. A collection generated from an OpenAPI 2.0, 3.0 or 3.1 spec can be kept in sync with the spec afterward, so when the spec changes you update the collection instead of rebuilding it. Prefer the command line? `postman spec generate collection ./openapi.json -n "Petstore Load"` builds the same kind of collection as local files (add `--folder-strategy Tags` to group by tag instead of path). ### Fix what the import gets wrong

 Four things need a hand before you can use the generated collection: - **Set the base URL.** Petstore's spec declares its server as the relative path `/api/v3`, so the collection's `baseUrl` variable has no host. Change it to `http://localhost:18080/api/v3`.
- **Check the request bodies.** The generated "Add a new pet" request uses the form-encoded variant of the body, with duplicated placeholder fields, not the JSON one. Step 2 replaces it with a clean JSON body.
- **Watch the order.** Requests run in folder order, which is alphabetical here, so `pet` comes before `user` and the sign-in request runs *last*. Step 4 moves sign-in into a setup collection, which runs before everything else. If you keep a sign-in request in the loop instead (the per-VU option in Step 2), reorder it to the top.
- **Add assertions.** A generated collection has requests and examples but no tests. Step 3 adds them.
 
### Trim it to the requests you will test

 A spec rarely knows which of your endpoints are worth hammering, and load-testing all 19 is not the goal. Keep the four that make up one realistic flow, and give them readable names. Sign-in is not among them: it moves to its own setup collection in Step 4. | Keep this generated request | Rename it to | Role in the flow |
|---|---|---|
| `POST /pet` (Add a new pet to the store) | Add Pet | Creates the data |
| `GET /pet/{petId}` (Find pet by ID) | Get Pet | Reads it back |
| `GET /pet/findByStatus` (Finds Pets by status) | Find Pets By Status | A list query |
| `DELETE /pet/{petId}` (Deletes a pet) | Delete Pet | Cleans up after itself |

 Delete the other 15 requests in the app. That leaves a few empty folders (`store`, `order`, `{username}`), which you can delete too. Then put the four requests in a folder called **Pet Lifecycle**, which is how the rest of the post refers to it. (Only if you want the per-VU sign-in from Step 2, add a Sign In request in its own folder at the top.) (If you made a local copy with the CLI, `postman collection request remove "Update an existing pet." --collection "Petstore Load" --folder pet` deletes one request, and you repeat it for each.) ### Run it once before you load it

 Send the requests once before you add load, and keep in mind that a performance test repeats the collection in a loop for every virtual user, so anything that should happen only once (creating an account, placing an order) will happen thousands of times. Move one-time work into a setup collection (Step 4). In the app, click **Run** on the collection; from the CLI, `postman collection run <collection-id>`. Read the result with suspicion. Run untouched (with `baseUrl` fixed), the four-request collection reports **4 requests, 0 failed**: Yet one of those four, `GET /pet/4808`, came back `404 Not Found`: the generated request asks for a made-up pet ID that does not exist. Nothing failed because nothing was asserting anything. Postman does not treat an HTTP status as a failure on its own, so a collection without assertions can only fail on a transport problem. Add assertions (Step 3) before you trust a green run, and Step 6 shows how to dig in when something is wrong. ### Other ways to get a collection

 Any of these ends in the same place: a collection you can script in Step 2. In brief: - **A cURL command or HAR file:** paste it into **Import** in the app, or run `postman collection import <curl or file.har> --name "..."`. See [Import data into Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-data/).
- **Real traffic from a client:** the Postman proxy (**Tools → Proxy**) records what a client actually sends and saves it as a collection. Browsers usually skip the proxy for `localhost`, so address your app by your computer's IP. See [Capture requests with the Postman proxy](https://learning.postman.com/docs/use/capturing-request-data/capture-with-proxy).
- **A collection someone else built:** **Fork** it (it stays linked to the original) or import the file. See [Fork elements](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/forking-elements).
- **From scratch:** **+ → Collection** in the sidebar, or `postman collection new "Orders API"` for a local one. See [Create a collection](https://learning.postman.com/docs/use/use-collections/create-collections).
 
## Step 2: Script it

 Pre-request and post-response scripts run under load exactly as they do locally, so the scripts you write for functional testing carry over. The cost is that every script runs once per request per VU, so keep them lean. ### Know your variables first

 The scripts below lean on variables, so it helps to know which kind to reach for, and who else can see the value. Postman has five [variable scopes](https://learning.postman.com/docs/use/send-requests/variables/variables/), listed here from broadest to narrowest: | Scope | Visible to | Use it for |
|---|---|---|
| Global | Everything in the workspace | Quick tests and prototyping. Every collection in the workspace can see it, so keep anything a load test depends on somewhere narrower. |
| Collection | Every request in one collection, whichever environment is selected | Settings that belong to the test itself, such as think time, pacing and feature flags, and values your scripts pass from one request to the next. |
| Environment | Whichever environment is active | Anything that changes between targets: the base URL, a tenant, the credentials for staging vs. production. |
| Data | One row of a CSV or JSON file per iteration | Per-iteration input, such as a different `petName` on each pass. It does not persist beyond the run. |
| Local | One request or one run | A temporary value set with `pm.variables.set` that overrides every other scope and disappears when the run ends. |

 When the same name exists in two scopes, the narrowest one wins. Step 5 shows what that does to a script. ### Who else sees a variable's value?

 Collection, environment and global variables are **local to your copy of Postman by default**. The value you type is used when you send requests, and it is not synced to the Postman Cloud. So a collection variable belongs to you alone until someone with Editor access chooses to [share its value](https://learning.postman.com/docs/use/send-requests/variables/share-variables/). Sharing syncs the value to the workspace as a default your teammates can start from. They can still change their own local value, and they can reset it to the shared one at any time. With Viewer access, you can only change the local value of an existing variable. ![The Variables tab of the Petstore Load collection: a variable named foo with the value bar, and a Share button with the tooltip 'Create a shared value and make it accessible to teammates.'](https://blog.postman.com/wp-content/uploads/2026/11/variables-share-button-1.png)A new collection variable is local to you. The **Share** button creates a shared value your teammates can use. ![The same variable with the value changed to bar1 and the Share button replaced by a cloud icon with a dropdown menu.](https://blog.postman.com/wp-content/uploads/2026/11/variables-shared-menu-1.png)After a value is shared, the button becomes a cloud menu. You can keep editing your local value without changing what your teammates see. Changing a variable from a script changes your local value. It does not reach your teammates unless you share the new value on purpose. (In the Postman VS Code extension, the shared value is still called the initial value and the local one the current value.) **Do not confuse this with virtual users.** Everything above is about people on your team. During a performance test, each virtual user runs with its own copy of the collection variables, so a value one VU sets, such as a token, a counter or an iteration start time, is never visible to another VU. That is why "sign in once per VU" works, and why the pacing timestamp in this step is safe. It also means collection variables cannot coordinate VUs: you cannot count total requests across all VUs, or hand one VU's token to another. The shared value matters for load tests in two ways: - **Postman features that run in the cloud use the shared value, not your local one.** That includes cloud performance runs, as well as scheduled collection runs, monitors and the Postman CLI. A variable that is only local works on your laptop and comes up empty when the same collection runs in the cloud or in CI. Share the values your test reads before you run it anywhere but your own machine.
- **Shared values are not private.** Teammates can read them, and they are published with your documentation. Never share a password or token as a plain value. Mark it as a secure variable instead, which moves the value into Postman Vault and leaves the variable holding only a reference.
 
 A rule of thumb for a performance test: put the test's own settings (think time, pacing, flags) in shared collection variables, so every teammate and every cloud run starts from the same defaults. Put the base URL in an environment. Put per-iteration input in a data file. Put credentials in secure variables. ### Make the settings variables, not code

 Built-in think time and pacing settings are not part of the performance test configuration yet, and the Postman team is working on them. Until they arrive, scripts can do the job today, because they can read variables. The trick is to put every tunable in a collection variable with a sensible default, and have the scripts read them. Then you tune a test by changing a variable, not by editing code, and when native settings ship you will already know which knobs you want. | Variable | Default | What it controls |
|---|---|---|
| `PACING_DURATION_MILLIS` | `0` | The minimum length of one iteration, in ms. `0` turns pacing off. |
| `THINK_TIME_MIN_MILLIS` / `THINK_TIME_MAX_MILLIS` | `250` / `750` | A random pause after each request. A max of `0` turns think time off. |
| `REQUIRE_DATASET` | `false` | When `true`, an iteration whose data row has no `petName` skips the requests that use the pet instead of using a random name. |

 It also helps to document them where the next person will look: the collection description. This one holds a small JSON block listing every knob and its default. ### Chain values between requests

 Extract what the next request needs in a script and keep it in a variable. The Petstore flow is add a pet, get it, find pets by status and delete it, and each request needs the ID the first one chose. Give every iteration its own pet ID so concurrent users would not step on one another's data: The guard uses `pm.execution.skipRequest()` because, in a pre-request script, `pm.execution.setNextRequest(null)` does not stop the request it runs in. Add Pet would still be sent, with `{{petId}}` unset on the first iteration and left over from the previous iteration after that; only the requests after it would be dropped. `skipRequest()` keeps the current request from being sent, but the run moves on to the next request, so the guard clears `petId` and each later request that uses it checks first: In a post-response script, such as the sign-in one below, `setNextRequest(null)` is the right call: the request has already been sent. The request body then uses `{{petId}}`, `{{petName}}` and `{{petStatus}}`, and later requests read the same variables: `GET {{baseUrl}}/pet/{{petId}}` and `DELETE {{baseUrl}}/pet/{{petId}}`. Deleting at the end of the loop also keeps the app's state from growing with every iteration. ```
pm.test("add pet returns 200", () => { pm.response.to.have.status(200); });
pm.test("add pet echoes the id we sent", () => {
  pm.expect(String(pm.response.json().id)).to.eql(pm.collectionVariables.get('petId'));
});

```

### Sign in once, and ramp the users up

 If every VU signs in at the same instant, you are testing your login endpoint's tolerance for a stampede, not the flow you care about. The Postman CLI has two built-in answers, so you do not need a delay script: sign in once in a setup collection, and let the load profile bring the VUs in gradually. (Both are in the Postman CLI 1.75.0 we used. If `postman performance run --help` does not list `--setup-collection` and `--load-profile`, upgrade the CLI.) **Sign in once, for the whole test.** Put the sign-in request in a setup collection. It runs once before any VU starts, and Postman passes the environment it updated on to every VU, so there is no sign-in request left in the loop and no stampede. Step 4 shows the setup and teardown scripts and the full command. **Ramp the VUs up.** With the Postman CLI the default load profile is already `ramp-up` (the app starts on **Fixed**, so change **Load profile** there): the test holds at a base number of VUs, then climbs to the peak, then holds there. Users arrive over minutes, not all at the first second. Set the shape with `--base-vu`, `--peak-vu` and `--load-segments`, which gives the length of the warm-up and the ramp: ```
--load-profile ramp-up --base-vu 2 --peak-vu 50 --duration 10 --load-segments 1m,3m

```

 That is 2 VUs for the first minute, a climb to 50 over the next three, and 50 until minute 10. The base VUs still start together, so keep the base small. **When one token is not enough.** A setup collection signs in once, so every VU shares one identity and one token. If each VU needs its own session (per-user data, per-user rate limits), or the token can expire before the run ends, sign in inside the loop instead, once per VU. The token lives in a collection variable, so every later iteration skips the request. With a ramp-up profile the VUs join gradually, so their first sign-ins are already spread out: ```
pm.test("sign in returns 200", () => { pm.response.to.have.status(200); });
// Petstore answers with plain text: "Logged in user session: "
const match = pm.response.text().match(/session:\s*(\S+)/);
if (match) {
  pm.collectionVariables.set('accessToken', match[1]);
} else {
  console.log('Sign in did not return a session, ending this iteration.');
  pm.execution.setNextRequest(null);
}

```

 Petstore does not enforce authentication, so this pattern does nothing useful there; it is here because a real API usually does. Note that its login response is plain text despite a JSON content type, so the script reads `pm.response.text()`, not `pm.response.json()`. ### Add think time

 Real users pause between actions. Without think time, every VU fires its next request the instant the last one returns, which is closer to a stress test than to your traffic. Add a random pause after each request, in its post-response script: ```
const min = Number(pm.collectionVariables.get('THINK_TIME_MIN_MILLIS')) || 0;
const max = Number(pm.collectionVariables.get('THINK_TIME_MAX_MILLIS')) || 0;
if (max > 0) {
  const delay = Math.floor(Math.random() * (max - min + 1)) + min;
  await new Promise(resolve => setTimeout(resolve, delay));
}

```

 Putting the pause *after* a request, and gating it on `max > 0`, means one variable turns the whole thing off for a quick smoke test. ### Hold a steady pace

 Think time spaces out requests within an iteration. Pacing fixes how long the whole iteration takes. Without it, a fast API makes each VU loop faster, so the load you send quietly grows with how well your API performs. A pacing floor makes every iteration take at least a fixed time, so the request rate stays predictable. Stamp the start time in the first request of the loop, and wait out the remainder in the last request: ```
// First request of the loop
const pacing = Number(pm.collectionVariables.get('PACING_DURATION_MILLIS')) || 0;
if (pacing > 0) {
  pm.collectionVariables.set('iterationStartMillis', String(Date.now()));
}

```

 ```
// Last request of the loop
const pacingTarget = Number(pm.collectionVariables.get('PACING_DURATION_MILLIS')) || 0;
const pacingStart = Number(pm.collectionVariables.get('iterationStartMillis'));
if (pacingTarget > 0 && Number.isFinite(pacingStart)) {
  const remaining = pacingTarget - (Date.now() - pacingStart);
  if (remaining > 0) {
    await new Promise(resolve => setTimeout(resolve, remaining));
  }
}

```

### Check that the knobs do what you think

 Scripts that sleep are easy to get wrong silently, so measure. We ran the same four-request loop for one minute at one VU with three settings, and counted requests: | Settings (1 VU, 1 minute) | Requests | Iterations | Requests per second |
|---|---|---|---|
| Think time off, pacing off | 3,868 | about 967 | 64.5 |
| Think time 250–750 ms, pacing off | 117 | about 29 | 1.95 |
| Think time 250–750 ms, pacing 5,000 ms | 48 | 12 | 0.80 |

 The numbers match the arithmetic. Four requests with a pause averaging 500 ms each take about two seconds, so a minute fits about 29 iterations. A 5-second floor on the same loop gives exactly 60 ÷ 5 = 12 iterations. In general, once pacing is on, the request rate is roughly *VUs × requests per iteration ÷ pacing time*, which is how you scale VUs without scaling the rate by accident. The sleeping is also not counted as response time: average response time stayed in the tens of milliseconds in the runs with think time, not hundreds, so your latency numbers are not inflated by the pauses. ### Keep scripts cheap

- **Skip** `console.log` **on the hot path.** Logging in a loop at 100 VUs is its own load test, of your terminal.
- **Assert on what you need.** Parse the body once and reuse it.
- **Fail loudly on missing inputs.** A thrown error in a script counts as an error in the run (see Step 3), which makes broken chaining easy to spot. Step 6 shows what these look like in the results.
 
## Step 3: Add test assertions that mean something under load

 `pm.test()` assertions run during the test, so you can keep your functional checks and add a few that only matter at scale. Think in two layers: *correctness* (status code, shape) and *budget* (response time). ```
pm.test("Status is 200", () => pm.response.to.have.status(200));
pm.test("Responds within budget", () => {
  pm.expect(pm.response.responseTime).to.be.below(800);
});
pm.test("Returns the pet we added", () => {
  pm.expect(pm.response.json().name).to.eql(pm.collectionVariables.get('petName'));
});

```

 Assertions are also the only thing that can make an individual request fail. A `404` or a `500` response is not an error on its own; the trimmed collection from Step 1 returned a 404 and still reported nothing failed. If you want a status code to count, assert on it. Separate from assertions, the run has pass/fail thresholds at the test level: average, p90, p95, p99, error rate and requests per second. Per-request assertions tell you *which* endpoint broke; run-level thresholds tell you whether the test as a whole passed. You need both. In the CLI you set the run-level threshold with `--pass-if` (for example `--pass-if "less_than(p95, 500)"`; repeat the flag and every condition must hold). The command exits 0 when the condition is met and 1 when it is not. ## Step 4: Sign in and clean up with setup and teardown collections

 Some work must happen once before any VU starts and be undone afterward, and signing in is the usual example. Postman handles that with a **setup collection** and a **teardown collection**, which run once before and once after the whole test. The requests in your main collection run in between, in the VU loop. The data each VU uses comes from a dataset (Step 5), so setup does not need to create any. - Setup runs once, before the load starts. If setup fails, the test is skipped, teardown is still attempted, and the run is marked failed.
- Teardown runs on every outcome, including cancel, fail and timeout.
- State passes through a per-run copy of the environment you select. Setup writes `accessToken`; the load requests read it. Variables written *during* the test are not visible to teardown, so teardown must work from what setup created.
 
 This post uses two small collections in the same workspace as **Petstore Load**. **Petstore Setup** holds one request, **Sign In**: `GET {{baseUrl}}/user/login?username=perf-user&password=perf-pass`. **Petstore Teardown** holds one request, **Sign Out**: `GET {{baseUrl}}/user/logout`. Neither defines `baseUrl`. Both read it from the environment you pass to the run, which here is an environment called **demoEnv** with two variables: | Variable | Value | Who sets it |
|---|---|---|
| `baseUrl` | `http://localhost:18080/api/v3` | You, once. Set it as the shared value so cloud and CLI runs see it too. |
| `accessToken` | Leave empty | The setup collection fills it in at run time, in that run's copy of the environment. |

 ```
// Petstore Setup — Sign In post-response script
pm.test("sign in returns 200", () => { pm.response.to.have.status(200); });
// Petstore answers with plain text: "Logged in user session: "
const match = pm.response.text().match(/session:\s*(\S+)/);
if (match) {
  pm.environment.set('accessToken', match[1]);
}

```

 ```
// Petstore Teardown — Sign Out post-response script
pm.test("sign out returns 200", () => pm.response.to.have.status(200));

```

 Setup writes the token to the **environment**, not to a collection variable, and that is what lets the main collection see it. Postman gives the run its own copy of the environment, applies what setup writes to that copy, and passes the updated copy to the virtual users and to teardown. A collection variable set in Petstore Setup would stay in Petstore Setup. The copy exists only for that run, so your saved environment is never changed. The requests in your main collection send the token in an `Authorization` header, `Bearer {{accessToken}}`. Petstore ignores it, but a real API would not, and sending it lets you check that it arrives. Add one assertion to each request: ```
pm.test("Authorization header carries a token", () => {
  const authorization = pm.variables.replaceIn(pm.request.headers.get('Authorization') || '');
  pm.expect(authorization).to.match(/^Bearer \S+$/);
  pm.expect(authorization).to.not.include('{{');
});

```

 The second check matters: when the variable is missing, Postman leaves `{{accessToken}}` in the header as literal text, and the first check alone would accept it. The requests in your main collection then use `{{accessToken}}`, and there is no sign-in request left in the loop. Setup and teardown collections are chosen when you start a run. They are not saved on the main collection, so nothing links them to it until you point the run at them. In the app, click **Run**, set **Run type** to **Performance**, and choose **App** or **Cloud** as the run method. On the **Run order** tab, click **+ Setup** and choose Petstore Setup, then click **+ Teardown** and choose Petstore Teardown, with your environment selected in the top right so they can share state with the test. These buttons exist only for the App and Cloud run methods; with the Postman CLI run method, use the command after the recording. ﻿Attaching Petstore Setup and Petstore Teardown to a performance run in the app. From the CLI, pass collection IDs with `--setup-collection` and `--teardown-collection`, and pass the environment with `--environment`, because setup, the test and teardown share state through it: ```
postman performance run <collection-id> \
  --environment <environment-id> \
  --setup-collection <setup-collection-id> \
  --teardown-collection <teardown-collection-id> \
  --peak-vu 5 --duration 5

```

 Replace the placeholders with your own IDs. Because the flags take IDs, the setup and teardown collections have to exist in your Postman workspace, not only on disk. Find the IDs in the info pane of each collection and environment in the app, or from the CLI with `postman collection list --workspace <workspace-id>` and `postman environment list`. Petstore does not enforce authentication, so the token does nothing there; the pattern is here because a real API usually needs it. ## Step 5: Drive the test with data

 One user hammering one record tests your cache, not your API. Feed each VU different data with a data file or a Postman Dataset. |  | Data file | Dataset |
|---|---|---|
| Format | CSV or JSON | A Postman Dataset, optionally a saved view |
| Runs where | Local only | Local and cloud |
| Read in scripts with | `pm.variables.get("column")` | `pm.iterationData.get("column")` |
| Row-to-VU mapping | Ordered or randomized in the app; the CLI supports random only | Round-robin (default), fixed (VU N uses row N, wrapping) or random |
| Plan | Paid | Paid |

 CSV rules: the first row holds variable names, use Unix line endings, and keep every row the same width. With a `petName` column in the data, `{{petName}}` in the "Add pet" body gives every iteration a different pet. Watch the names. When a name exists in more than one scope, `{{name}}` resolves in this order: local, data (the dataset row or data file), environment, collection, global, so a data column beats a collection variable with the same name. This matters when a script stores a value it generated or got back from the server. If the data also has a `petId` column, `{{petId}}` in the request uses the row's value while `pm.collectionVariables.get('petId')` still returns the script's, with no error. Give script-created values names no column uses, such as `createdPetId`. A dataset column that holds an object or an array, such as a pet's `tags`, comes back from `pm.iterationData.get()` as a JSON string, not as the object. Parse it before you read its fields: From the CLI: ```
# Data file (local only)
postman collection run <collection-id> --data-file ./pets.csv

# Dataset (local or cloud)
postman performance run <collection-id> \
  --dataset-id <dataset-id> \
  --dataset-view-id <view-id> \
  --dataset-distribution round-robin

```

## Step 6: Debug the script before you add load

 Debug at one user, with nothing else going on. A script bug under 50 VUs shows up as a wall of identical errors; at one VU it shows up as one error you can read. Almost everything below is easier in the app than anywhere else, and the reason is in pointer 8. To show what each kind of failure looks like, we made a deliberately broken copy of Petstore Load with four one-line sabotages, and ran it at one VU for a minute against a local Petstore: | Request | Sabotage | What it should trigger |
|---|---|---|
| Get Pet | The URL starts with `{{nope}}`, a variable that does not exist | A request that cannot complete |
| Find Pets By Status | An extra assertion that the list is empty | A failed assertion |
| Find Pets By Status | A script line reads a dataset column that does not exist | Nothing, which is the point |
| Delete Pet | The script calls `pm.response.json()`, but Petstore answers "Pet deleted" as plain text | A script error |

### 1. Open the Postman Console and run it once

 Click **Console** in the Postman footer, or press **⌘+Option+C** / **Ctrl+Alt+C** in the desktop app to open it in its own window. Then send the request or run the collection once. The Console shows the request that was sent (with its headers and variable values), the raw response, network details, and anything your scripts log. It keeps the last 5,000 messages or 24 hours and stays local; it is not synced to the cloud. ### 2. Print what you would otherwise guess

 `console.log`, `info`, `warn` and `error` all work in scripts. Log the value and its type, because "it looks right" is how a string gets compared with a number. When you are not sure the body is JSON, log the raw text first. ### 3. Read the error before you fix it

 The messages are specific, and each points at a cause: | Message | Usually means |
|---|---|
| `ReferenceError: x is not defined` | A variable is used outside the scope where it was declared |
| `AssertionError: expected undefined to deeply equal …` | The property you assert on does not exist in the response, or is nested differently |
| `AssertionError: expected 1 to deeply equal '1'` | A number was compared with a string |
| `JSONError` (in the run results) | `pm.response.json()` was called on a body that is not JSON, such as Petstore's plain-text "Pet deleted" |
| `getaddrinfo ENOTFOUND {{redirecturi}}` | A variable that forms the URL's host was never set, so its literal name was looked up as a hostname. The name appears lowercased, so search your collection for it case-insensitively. |
| A `pm.test` that never fails | The name string must be the first argument; a function with no name is not a test |

### 4. Check the final URL, and check who answered

 An undefined `{{variable}}` in a URL produces an invalid address, and nothing in your script has to be wrong for that to happen. The Console shows the URL the request actually went to. Under load, the same mistake does not appear as an assertion failure at all; it is a request that never completed. The other way a URL goes wrong is a perfectly good URL that points at the wrong thing. If the very first request returns a 404 and everything after it fails too, suspect that another service is listening on the port you chose. This happened to us: a pgAdmin container was already using port 8080, so the sign-in request to `localhost:8080` came back `404 NOT FOUND`, politely, from a server that had never heard of Petstore. The response headers give it away: Compare the `Server` header (or the body) with what the app should send. To find out who owns a port, run `docker ps` for containers, or `lsof -nP -iTCP:<port> -sTCP:LISTEN` for anything else. ### 5. A bad status code is not an error

 Postman does not treat an HTTP status as a failure on its own. The trimmed collection from Step 1 got a 404 back from `GET /pet/4808` and still reported 4 requests, 0 failed, because nothing asserted on the status. If a status should fail the test, assert on it. ### 6. Make missing input loud

 The most expensive bugs are the ones that do not fail. In the broken copy, Find Pets By Status reads `pm.iterationData.get("nope")`, a dataset column that does not exist. It gets `undefined` and carries on: no error, no failure, nothing in the results. The request ran with bad input and counted as healthy. Guard every input a script depends on, and stop the iteration, or throw, when it is missing. A thrown error is counted and classified (next pointer). A quiet skip, even a logged one, is easy to miss at scale. ### 7. Know which bucket a failure lands in

 Under load the results separate failures into different buckets, and they point at different fixes. This is what we saw in the four-sabotage run: | What went wrong | Counted as | First move |
|---|---|---|
| A `pm.test()` assertion fails (Find Pets By Status) | **Test failure** (Failure %, "requests with failed assertions") | Check the assertion and the data. At one VU, read the message in the Console. |
| A request cannot complete: unresolved variable, DNS or TLS failure, timeout (Get Pet) | **Error**, category `transport`, *and also* counted as a request with failed assertions, because its assertions never ran | Check the final URL in the Console. |
| A script throws, such as `pm.response.json()` on a text body (Delete Pet) | **Error**, category `script`, type `JSONError`. *Not* counted as a failed assertion. | Log `pm.response.text()` and guard the parse. |
| A 404 or 500 with no assertion on it, or a script that quietly uses `undefined` | **Not counted** | Assert on status; log and guard inputs. |

 In the CLI's `--output ndjson` summary for that run, the same split is visible in `metrics.errors.segmentation.errorTypes`: The failed-assertion count is easy to misread. Here it is 1,983 across about 992 iterations, so about two requests per iteration: the failing assertion (Find Pets By Status) plus the request that could not complete (Get Pet). To check that, we ran each sabotage on its own for a minute: with only the unresolved variable, `requestsWithFailedAssertions` was 1,203 for about 1,203 iterations (one per iteration); with only the JSON-parse error, it was 0. One more difference to know about: the CLI's *live* `progress` events count only transport errors. In the JSON-parse-only run the live error rate stayed at 0.00 for the whole minute, while the final summary said 24.98%. Script errors show up only in the final summary, so do not gate on the live number. In the app, errors have their own tab: it shows the top error trends and classes, and lets you expand a class to see the ten most common responses. Failed assertions have a separate view with a Failure Trend and a Tests vs VU chart. Note that the request and response details behind an error are kept only for the current session; if you close the tab or quit Postman, you keep the error classes and counts but lose the sample responses. ### 8. Do not count on logs once the load starts

 When we ran the same broken collection with the Postman CLI's `--output ndjson` on the local runner, none of our `console.log` output appeared in the stream or in stderr. The docs we read do not say whether log output is visible during a performance run, and the CLI docs describe only stages and metrics on standard output. So treat `console.log` as a tool for the one-VU debugging pass in the app, and rely on assertions and thrown errors (which are counted) once the load is on. Remove noisy logging before you scale up, since it costs time on every iteration. ### 9. When everything fails at once, check the server

 Not every failure is in your script. In one of our sessions, a collection that had passed a few minutes earlier suddenly failed on almost every request, and never recovered: in a clean repeat of the experiment, 84% of requests ended up with failed assertions. The script was fine. The demo app had corrupted its own data, and from then on every request returned HTTP 500. Because a 500 is not an error in Postman's counts (pointer 5), the only symptom was a wall of failed assertions. Two quick checks tell script bugs from server bugs. First, send one valid request by hand (`curl` or the app) and see whether the server itself returns an error. Second, look at the server's own request log for the moment the status codes change. For Petstore in Docker, the container keeps one: If the 500s start at one instant and never stop, you are looking at a server that broke, not a script that is wrong. Restart it, and rerun. ### 10. Shrink the problem

 If a collection fails and you cannot tell where, cut it down, then add requests back until it breaks. In the app, run the performance test on a single folder, or skip requests in the run sequence. `postman performance run` has no option to select a folder or request and always runs the whole collection, so from the CLI either run a trimmed copy of the collection, or put a `pm.execution.skipRequest()` guard on each request you want to leave out, switched by a collection variable, as in Step 2. Use the fewest VUs and the shortest duration the test allows (duration is set in whole minutes), and fix one failure type at a time, starting with the ones that stop a request from completing. ## Once the script works: run it

 With a script you trust, trying it under load is short work: 1. **In the app:** open the collection (or a folder), click **Run**, set **Run type** to **Performance**, choose **App** as the run method, start with a handful of VUs for a minute, and watch the Summary, Errors and Tests views.
2. **In CI:** run it with the Postman CLI, and add a pass/fail threshold so a slow build fails the job.
3. **At scale:** run it from Postman Cloud when one machine cannot generate enough load, or when you need realistic origin and fixed IPs. Cloud runs need a paid plan.
 
 ```
postman performance run <collection-id> --peak-vu 5 --duration 1 --pass-if "less_than(p95, 500)"

```

 Think time and pacing are what let you raise the VU count without raising the request rate by accident, so set them before you scale. For the CLI and cloud details, including the cloud vs. laptop trade-offs, see [Cloud Performance Testing with Postman: From Laptop to CI](https://blog.postman.com/cloud-performance-testing-postman/) and the [Postman CLI performance testing docs](https://learning.postman.com/docs/postman-cli/postman-cli-run-performance-test). ## Wrapping up

 Thank you for reading all the way through. We know this was a long post. We wanted to put in one place everything it takes to write a performance test script that holds up under load: importing and trimming a collection, scoping variables so virtual users do not trip over each other, signing in once with setup and teardown collections, driving the test with data, writing assertions that mean something, and debugging the script before you add load. If you take one thing from it, make it this: get the script right at a small scale first, because a few virtual users will not fix a script that is wrong at one. Performance testing in Postman is evolving quickly, and several of the workarounds in this post are there only because the product is still catching up. Out-of-the-box think time and pacing settings, and richer logging that includes console output from many virtual users and not just errors, are on the way. When they arrive, parts of this post will get simpler. Stay tuned, and check back for updates. In the meantime, try the steps on your own collection, and tell us what worked and what did not. Your feedback helps shape what comes next. A big thank you to Brent Cromarty and Yumeng Wu, whose time, testing and thoughtful feedback shaped this post from the first draft to the last.