Organising a Postman test suite

A collection with ten requests organises itself. One with three hundred, edited by five people over two years, doesn't. Requests get duplicated, tests depend on each other in ways nobody remembers, and the suite starts failing for reasons that have nothing to do with the API. This lesson collects the habits that keep a Postman suite trustworthy as it grows, and ends with the question every team reaches eventually: when should the tests move out of Postman and into code?

Structure

Group by what the API does, not by who wrote the test or when. One folder per resource or feature, and inside it, folders for each kind of check:

TestingAPIs (collection)
├── Auth                      ← logins that save tokens; run first
├── Products
│   ├── List and filter
│   ├── Product by ID
│   └── Create, read, update, delete   ← makes its own data, removes it at the end
├── Todos
│   └── ...
└── Smoke                     ← five fast requests to run after every deployment

The Smokefolder deserves a mention. A handful of fast, read-only requests that touch each important part of the API make a good check after every deployment, run with Newman's --folder. The full suite can run less often.

Checks every response should pass belong in a folder or collection script, written once:

// Folder-level post-response script: runs after every request in the folder
pm.test("no server errors", () => {
  pm.expect(pm.response.code, "status").to.be.below(500);
});

That one test runs after every request in the folder, and a 500 anywhere shows up even on requests whose own tests forgot to check the status.

Independent folders

The most expensive problem in large suites is hidden order: a request that only passes because another one ran earlier and left something behind. Run that folder on its own, or in a different order, and it fails. Some order is deliberate, like the create, read, delete chain in lesson 5. The rule is to keep each dependency inside one folder:

• Each folder can run on its own with --folder and pass.
• A folder that needs a token logs in itself, or fetches one in a pre-request script when it's missing.
• A folder that needs data creates it, and deletes it at the end.
• No folder reads a variable that a different folder set.

Test it occasionally by running each folder alone. Any folder that fails alone has a hidden dependency.

Test data

Tests that read shared data break when someone else changes it. This tutorial ran into it directly: the shared test API gained an extra electronics product after its seed data was written, so any test asserting the original count would have failed. Three rules avoid most of it:

• Create the records you assert exact values on, with unique names, and delete them afterwards.
• For data you didn't create, assert properties: every item matches the filter, the count is at least the page size.
• Seed data with known, fixed IDs is fine to read; never change it in a test.

Names

Request names and test names are the only documentation most suites get, and in CI they're the only thing anyone sees. Name requests after what they check, A missing product returns 404, and tests as sentences that should be true, the error names the missing ID. A failure then reads as a statement that turned out false, which is exactly what a bug report needs.

Version control

A collection kept only in Postman has no review and limited history. Export it, along with environments and data files, into the repository of the API it tests, and change it through pull requests like code. Postman also offers its own integrations with Git hosts, which keep a workspace and a repository in step. Either way, the point is that a change to the tests is reviewed by someone, and a broken test can be traced to the change that broke it.

Exported collections are JSON, and every script is stored as an array of lines, so diffs are readable once you're used to them. Two things to check in every review: that no exported file contains a real token or key, and that the collection still runs with Newman. The tutorial collection is built by a script for this reason, so it can be regenerated and re-run whenever the API changes.

Flaky tests

A test that sometimes fails for no reason is worse than no test, because people learn to ignore red. The usual causes:

When to move to code

Postman is excellent for exploring an API, for collections that testers and developers share, and for suites up to a few hundred requests with modest logic. Some signs that tests would be better as code, in a framework like Playwright, pytest, Jest or REST Assured:

• Scripts are long, repeated between requests, and copy-pasted rather than shared.
• Tests need real programming: loops over generated data, helpers, mocks, comparisons with a database.
• The team wants tests reviewed line by line alongside the code they test, and the exported JSON gets in the way.
• Tests need to run inside the application's own build, against a server started for the test.

Moving isn't all-or-nothing. Plenty of teams keep a Postman collection for exploration, onboarding and smoke checks, and write the deep regression suite in code. The REST tutorial's lesson on automating tests with codeis the next step if you go that way; everything you've written as pm.test translates almost line for line.

Postman or code?