Update to Postman

{
  "description": "Runs tests against an API from the command line — a single ad-hoc request, a full collection of pm.test assertions, or matching real captured app traffic against a collection contract. Use when the user asks to \"test this endpoint,\" \"run this collection,\" \"check the API still works,\" or \"verify my app's requests match the contract.\" Covers `postman request`, `postman collection run`, and `postman application test`. Depends on bootstrap when the target is a cloud collection or workspace-bound environment; a bare URL or local collection needs nothing from bootstrap.",
  "included_files": [],
  "name": "api-testing",
  "skill_md_contents": "---\nname: api-testing\ndescription: Runs tests against an API from the command line — a single ad-hoc request, a full collection of pm.test assertions, or matching real captured app traffic against a collection contract. Use when the user asks to \"test this endpoint,\" \"run this collection,\" \"check the API still works,\" or \"verify my app's requests match the contract.\" Covers `postman request`, `postman collection run`, and `postman application test`. Depends on bootstrap when the target is a cloud collection or workspace-bound environment; a bare URL or local collection needs nothing from bootstrap.\n---\n\n# API Testing\n\n## Overview\n\nThree tools, matched to what already exists:\n\n| Have | Use |\n| --- | --- |\n| Just a URL to check, with no saved request | `postman request` |\n| A request already saved in a collection | `postman collection run <collection-path> -i <request-id-name-or-path>` |\n| A collection with `pm.test` assertions saved in it | `postman collection run` |\n| A real app (browser flow, CLI, service) whose traffic should match a collection's contract | `postman application test` |\n\nDon't reach for the heavier tool when the lighter one already answers the\nquestion — a one-off endpoint check doesn't need a collection, and a\ncollection run doesn't need Playwright.\n\n## `postman request` — over curl, not instead of testing\n\nA single request with Postman's resolution built in: `-e` resolves\n`{{variables}}` from an environment file the same way a collection run\nwould, `--auth-*` flags cover basic/bearer/digest/oauth/aws/etc. without\nhand-building headers, and `--retry`/`--timeout` handle flaky endpoints.\n`--script-post-request` can run `pm.test(...)` assertions inline — the exit\ncode counts *failed assertions*, not just HTTP status, so a 200 with a\nfailing test still exits nonzero. Useful for a quick check or a CI health\ncheck; not the place to accumulate assertions that should outlive one\ncommand — those belong saved in a collection.\n\nBefore constructing a URL, headers, auth, and body on the command line, look\nfor a matching `*.request.yaml` under `postman/collections/`. If it exists,\nexecute the saved request through its collection:\n\n```bash\npostman collection run \"postman/collections/Orders API\" -i \"create order\"\n```\n\nDo not copy the saved YAML fields into `postman request`; that bypasses the\ncollection's inherited variables, auth, scripts, and maintained payload. The\n`postman request` positional target is a URL, not a `.request.yaml` path. When\nthere is no saved request but its body already lives in a separate file, keep\nthe file as the source of truth with `--body @path/to/payload.json` instead of\ninlining its contents.\n\n## `collection run` — the assertion suite\n\nDebugging a request's behavior during a run (why a `pm.test` failed, what a\nrequest actually sends) means reading the request's own YAML — see the\n`collection-schema-v3` skill for that file format before assuming a field's\nshape.\n\nRuns every request in a collection (or a subset via `-i`, repeatable),\nexecuting whatever `pm.test` scripts are already saved in it.\n`-d`/`--iteration-data` (or the beta `--iteration-data-dataset` +\n`--iteration-data-view` pair) drives data-driven runs across a CSV/JSON\nfile or a Postman Dataset. `-r junit,html` for CI-consumable reports.\n`--use-mock`/`--mock` redirects the run at a mock instead of a real backend\n(see the `api-mocking` skill) — reach for this to test request/assertion\nlogic without depending on a live service.\n\n## `application test` — contract-matching real traffic\n\nThis doesn't send its own requests. It runs your existing test command\n(`--command \"npx playwright test\"`, or config-driven via\n`postman.config.cjs` targets), captures the network traffic that command\ngenerates, and matches/asserts it against your Postman collections —\nanswering \"did my app's actual calls conform to the contract,\" not \"does\nthis endpoint respond correctly.\" `--capture-only` skips the matching step\nentirely and just exports what was captured as a new v3 collection,\norganized by host — a way to bootstrap a collection from real traffic\nrather than authoring one from scratch. Results upload to Postman\nautomatically after each run; `--report-events=false` skips that for a run\nthat shouldn't be recorded.\n\n## Critical Rules\n\n1. **Don't reach for `application test` for something a plain\n   `collection run` covers.** It exists specifically for matching *captured*\n   app traffic (via Playwright or similar), not for driving requests itself.\n2. **`postman request`'s exit code reflects failed `pm.test` assertions, not\n   HTTP status alone.** A nonzero exit on a 200 response usually means a\n   post-request script assertion failed, not a network problem.\n3. **Assertions meant to be reused belong in the collection, not on the\n   command line.** A `--script-post-request` test on `collection run` runs\n   once and leaves nothing for the next person; save it as a `pm.test` in\n   the request instead.\n4. **`--use-mock` is the way to test without a live backend** — prefer it\n   over standing up ad hoc fakes or skipping tests that need a dependency.\n5. **Reuse a saved request instead of reconstructing it.** If a matching v3\n   request exists, use `collection run <collection-path> -i <request>`; reserve\n   `postman request` for genuinely ad-hoc requests.\n\n## Verification\n\nState the actual result (pass/fail counts, exit code), not just that the\ncommand ran. For `application test`, state whether it ran in match mode or\n`--capture-only` — they answer different questions and shouldn't be\nreported the same way.\n"
}