Api Testing

API Testing

Overview

Three tools, matched to what already exists:

Don't reach for the heavier tool when the lighter one already answers the question — a one-off endpoint check doesn't need a collection, and a collection run doesn't need Playwright.

postman request — over curl, not instead of testing

A single request with Postman's resolution built in: -e resolves {{variables}} from an environment file the same way a collection run would, --auth-* flags cover basic/bearer/digest/oauth/aws/etc. without hand-building headers, and --retry/--timeout handle flaky endpoints. --script-post-request can run pm.test(...) assertions inline — the exit code counts failed assertions, not just HTTP status, so a 200 with a failing test still exits nonzero. Useful for a quick check or a CI health check; not the place to accumulate assertions that should outlive one command — those belong saved in a collection.

collection run — the assertion suite

Debugging a request's behavior during a run (why a pm.test failed, what a request actually sends) means reading the request's own YAML — see the collection-schema-v3 skill for that file format before assuming a field's shape.

Runs every request in a collection (or a subset via -i, repeatable), executing whatever pm.test scripts are already saved in it. -d/--iteration-data (or the beta --iteration-data-dataset + --iteration-data-view pair) drives data-driven runs across a CSV/JSON file or a Postman Dataset. -r junit,html for CI-consumable reports. --use-mock/--mock redirects the run at a mock instead of a real backend (see the api-mocking skill) — reach for this to test request/assertion logic without depending on a live service.

application test — contract-matching real traffic

This doesn't send its own requests. It runs your existing test command (--command "npx playwright test", or config-driven via postman.config.cjs targets), captures the network traffic that command generates, and matches/asserts it against your Postman collections — answering "did my app's actual calls conform to the contract," not "does this endpoint respond correctly." --capture-only skips the matching step entirely and just exports what was captured as a new v3 collection, organized by host — a way to bootstrap a collection from real traffic rather than authoring one from scratch. Results upload to Postman automatically after each run; --report-events=false skips that for a run that shouldn't be recorded.

Critical Rules

1. Don't reach for application test for something a plain collection run covers. It exists specifically for matching captured app traffic (via Playwright or similar), not for driving requests itself.
2. postman request's exit code reflects failed pm.test assertions, not HTTP status alone. A nonzero exit on a 200 response usually means a post-request script assertion failed, not a network problem.
3. Assertions meant to be reused belong in the collection, not on the command line. A --script-post-request test on collection run runs once and leaves nothing for the next person; save it as a pm.test in the request instead.
4. --use-mock is the way to test without a live backend — prefer it over standing up ad hoc fakes or skipping tests that need a dependency.

Verification

State the actual result (pass/fail counts, exit code), not just that the command ran. For application test, state whether it ran in match mode or --capture-only — they answer different questions and shouldn't be reported the same way.