Postman review: pricing, alternatives and tutorial

A collection is a tree of folders and requests, each request carrying its URL, headers, body, authorisation and scripts. Values that change between runs are written as double-brace variables and resolved at send time from five scopes: global, collection, environment, iteration data and local. When a name exists in more than one scope, the narrowest wins, so a local variable set by a script beats the environment, which beats the collection. Most confusing failures in shared collections come from this: a stale global or collection value silently overriding what the environment was meant to supply. Secrets belong in the Postman Vault, read with pm.vault, rather than in environments that sync to a team workspace.

Each request, folder and collection can carry a pre-request script and a post-response script, written in JavaScript and run in Postman’s sandbox rather than in Node.js. Scripts inherit down the tree, so a collection-level script runs for every request. Assertions use pm.test with pm.expect, which is Chai’s BDD syntax, plus helpers such as pm.response.to.have.status and jsonSchema checks. The sandbox explains both the convenience and the ceiling: there is no build step and nothing to install, but there is also no ordinary module system, so shared logic is copied between scripts, held in collection-level scripts, or published to a package library that the CLI can only use on paid plans.

Postman 12, released in early 2026, connects a workspace to a Git repository on your machine. In Local View, edits are written as Collection v3 YAML files under a postman/ folder, one file per request rather than one large JSON document, and switching branches in Git switches what Postman shows. Cloud View is what consumers of the workspace see; local work reaches it when it is pushed, for example by postman workspace push in a pipeline after a merge. The change matters for testing because collections can finally be reviewed in a pull request, but it splits the world into v2.1 JSON and v3 YAML collections, and the tooling around them behaves differently.

Newman, the open source runner that put Postman collections into CI for a decade, is described in Postman’s own documentation as no longer maintained. It only understands v2.1 JSON and cannot run collections created or updated in Postman 12. Its replacement is the Postman CLI, a signed binary installed with npm or an install script and also bundled with the desktop app. postman collection run takes a file path or a collection ID: a local file runs without signing in, while a run by ID, or a local collection linked to the cloud, uploads results to Postman when you are signed in. Most Newman flags have direct equivalents, which keeps the migration mostly mechanical.

Organise folders by resource or user journey, not by HTTP method, and keep each request independent enough to run alone after a setup folder. Put authorisation on the collection and let requests inherit it, so a token change is one edit. Put shared assertions, such as status class and response time, in a collection-level post-response script, and keep request-level scripts for checks specific to that endpoint. Name variables by scope and purpose, for example baseUrl in the environment and orderId set at run time, and never store a secret in an environment that syncs to a team workspace. If the team works in Git, adopt Local View from the start rather than migrating later: per-request YAML files make every change reviewable, and branches let a feature’s API tests travel with the feature. In our experience the single biggest maintainability win is deciding where logic lives before the collection has two hundred requests.

Most API regression packs are flows: create a resource, read it back, change it, delete it, and check that unauthorised and invalid requests fail the right way. Set the id from each response into a run-scoped variable and read it in the next request’s URL. For negative tests, duplicate the request into a folder named for the failure case and assert on the status and the error body, not only the status, because a 400 with the wrong message is still a defect. Use pm.execution.skipRequest in a pre-request script when a precondition is missing, rather than letting a later request fail with a confusing error.

Postman publishes an official action, postmanlabs/postman-cli-action, which installs the CLI and runs whatever command you give it. A collection file in the repository runs without an API key; a run by collection ID, or one that should upload results to Postman, needs a key from a repository secret. Pass secrets as environment variables with --env-var rather than committing them in an environment file. One constraint shapes the pipeline: JUnit, JSON and HTML reporters work only for v2.1 JSON collections, while v3 YAML collections get the terminal report only. If your CI dashboard depends on JUnit XML, keep an exported v2.1 copy for the pipeline or rely on the run results uploaded to Postman.

Treat the move to Postman 12 as two separate migrations. First, swap the runner: newman run becomes postman collection run, and -e, -g, -r and most other flags carry over, so most pipeline changes are a find and replace followed by a test run. Second, decide whether to convert collections to v3 with postman collection migrate. Converting gives you per-request YAML and Git review, but loses the JUnit, JSON and HTML reporters in the CLI and cuts off any remaining Newman jobs. Migrate one collection end to end, including CI and reporting, before converting the rest, and keep backups of the v2.1 exports until every consumer has moved.

Review collections the way you review code. Search regularly for duplicated script blocks and move them up to the folder or collection level. Delete requests nobody runs. Keep assertions specific: checking that a field exists catches less than checking its type and allowed values, and a JSON schema check catches drift in fields nobody thought to assert. Watch for tests that depend on data created by a previous run, which pass on the author’s machine and fail in CI. Finally, be honest about when a collection has outgrown the tool: if the pack needs a page of helper functions, typed models and generated data, a code-based framework will cost less to maintain than the scripts.