Dev48
Language
  • About
  • Services
  • Industries
  • Technologies
  • Articles
  • Contacts
Book a call
    Home/Articles/How to write postman performance test scripts that scale
Dev48
info@dev48.org+375 29 320-40-96WhatsApp@isky_by

© 2026 · All rights reserved.

How to Write Postman Performance Test Scripts That Scale

Фото: Pankaj Patel (Unsplash) — https://unsplash.com/photos/closeup-photo-of-computer-code-screengrab-SXihyA4oEJs?utm_source=dev48&utm_medium=referral

Source: Postman Blog•November 18, 2026 at 04:31 PM

How to Write Postman Performance Test Scripts That Scale

Learn how to write Postman performance test scripts: chain requests, add assertions, sign in with setup collections, feed data, and debug before scaling load. The post How to Write Postman Performance Test Scripts That Scale appeared first on Postman Blog .

November 18, 2026

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

  • Get a collection: import your OpenAPI spec, or record it with the Postman proxy, fork one, or write it.
  • Script it: chain values between requests and control the pace.
  • Assert on correctness and on a response-time budget.
  • Sign in and clean up with setup and teardown collections.
  • Feed it data with a data file or a dataset.
  • 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, 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:

  • Click Import.
  • 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.
  • 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.
  • Press Enter to import and wait for it to finish. Then rename the new collection to Petstore Load.

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.

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.
  • 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.
  • A collection someone else built: Fork it (it stays linked to the original) or import the file. See Fork elements.
  • From scratch: + → Collection in the sidebar, or postman collection new "Orders API" for a local one. See Create a collection.

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, listed here from broadest to narrowest:

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. 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.

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.

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.

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:

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:

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:

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:

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:

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).

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:

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:

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.

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:

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.

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:

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:

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.

6. Make missing input loud

← All articles

What this article says

More in Software Development

All →
Self-Service, Punchout and Hosted Catalog: The Three B2B Ecommerce Flows and How They Work
Vtex

Self-Service, Punchout and Hosted Catalog: The Three B2B Ecommerce Flows and How They Work

How to advertise on Facebook in 2026: A complete guide
Hootsuite

How to advertise on Facebook in 2026: A complete guide

Social media hiring in 2026: Roles, salaries, and team tips
Hootsuite

Social media hiring in 2026: Roles, salaries, and team tips

Why your software needs a CBOM
SonarSource

Why your software needs a CBOM

How to use AI prompts to create your online course
Teachable

How to use AI prompts to create your online course

What drives the cost of AI at work
Microsoft

What drives the cost of AI at work

More from Postman

Build a Developer Portal with Postman and Fern in a Day
Postman

Build a Developer Portal with Postman and Fern in a Day

Fern is now Postman’s home for API Dev Portals
Postman

Fern is now Postman’s home for API Dev Portals

What’s new in Postman: Kafka, MCP tests, RAML
Postman

What’s new in Postman: Kafka, MCP tests, RAML

Sharing API Simulations Across Coding Agent Sessions
Postman

Sharing API Simulations Across Coding Agent Sessions

One Terminal, Entire Agentic SDLC: Live Nov 17 at 10 AM PST
Postman

One Terminal, Entire Agentic SDLC: Live Nov 17 at 10 AM PST

Handling a leaked credential with the Postman plugin
Postman

Handling a leaked credential with the Postman plugin