Update to Postman

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -1,103 +1,57 @@
 ---
 name: api-testing
-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.
+description: Use when testing an endpoint, running collection assertions, or checking real application traffic against an API contract. Reuses saved requests and reports what live, mocked, or captured-traffic results actually establish. Use for requests such as "test this endpoint".
 ---
 
 # API Testing
 
-## Overview
-
-Three tools, matched to what already exists:
-
-| Have | Use |
-| --- | --- |
-| Just a URL to check, with no saved request | `postman request` |
-| A request already saved in a collection | `postman collection run <collection-path> -i <request-id-name-or-path>` |
-| A collection with `pm.test` assertions saved in it | `postman collection run` |
-| A real app (browser flow, CLI, service) whose traffic should match a collection's contract | `postman application test` |
-
-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.
-
-Before constructing a URL, headers, auth, and body on the command line, look
-for a matching `*.request.yaml` under `postman/collections/`. If it exists,
-execute the saved request through its collection:
-
-```bash
-postman collection run "postman/collections/Orders API" -i "create order"
-```
-
-Do not copy the saved YAML fields into `postman request`; that bypasses the
-collection's inherited variables, auth, scripts, and maintained payload. The
-`postman request` positional target is a URL, not a `.request.yaml` path. When
-there is no saved request but its body already lives in a separate file, keep
-the file as the source of truth with `--body @path/to/payload.json` instead of
-inlining its contents.
-
-## `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.
-5. **Reuse a saved request instead of reconstructing it.** If a matching v3
-   request exists, use `collection run <collection-path> -i <request>`; reserve
-   `postman request` for genuinely ad-hoc requests.
+Saved requests preserve the auth, payloads, variables, and assertions that make
+an API check reproducible. The useful result is evidence about an intended
+guarantee; a successful HTTP exchange alone does not establish correctness.
+
+1. Choose the smallest execution mode that answers the question:
+
+   | Evidence needed | Use |
+   | --- | --- |
+   | One endpoint with no saved request | `postman request <url>` |
+   | Behavior of an existing saved request | `postman collection run <collection-path> -i <request-id-name-or-path>` |
+   | Reusable regression checks | `postman collection run <path-or-id>` |
+   | Whether a real app's calls match the contract | `postman application test` |
+
+2. Reuse a matching request under `postman/collections/` before reconstructing
+   its HTTP fields. Running it through the collection retains inherited auth,
+   variables, and scripts. `postman request` takes a URL, not a request YAML
+   path; for an unsaved request with an existing payload file, `--body @path`
+   preserves that file as the source. See **collection-schema-v3** when
+   editing the saved request.
+3. Derive assertions from the contract and the behavior at risk. A test that
+   merely repeats the current implementation can bless its bug. Preserve
+   existing guarantees and add checks for the changed behavior; put reusable
+   `pm.test` assertions in the collection so later runs and teammates inherit
+   them. Inline `--script-post-request` assertions suit a one-off check.
+4. Choose a real or mocked target according to the claim. `--use-mock` lets a
+   collection run exercise request and assertion logic without a live
+   backend; `--mock` alone only starts one. `--use-mock` replaces the
+   variable's whole value, base path included (see **api-mocking**). Passing
+   against that mock does not verify the service the mock stands in for.
+5. Reuse environment resolution with `-e` and **variables**. Use a CSV/JSON
+   file through `-d` for simple iteration; use **datasets** when the inputs
+   need queries, joins, or reusable views. Export reports such as
+   `-r junit,html` when **ci-integration** needs evidence beyond terminal output.
+6. Use `application test` when the application's actual traffic is the subject.
+   It runs an existing command, such as `--command "npx playwright test"`,
+   captures its traffic, and matches it against collections. `--capture-only`
+   instead exports a v3 collection organized by host; that captures behavior
+   without validating it. Results are recorded in the connected workspace by
+   default; `--report-events=false` keeps the run local when required.
+
+Use command-specific `-h` for supported options and **bootstrap** for unresolved
+CLI setup or authentication when using workspace resources. A bare URL or
+local collection does not require a workspace binding.
 
 ## 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.
+Report the target, tested behavior, assertion counts, and exit code. The exit
+code reflects failed assertions, not HTTP status alone: a 200 can fail a test.
+For application testing, distinguish matching from capture-only mode, and for
+mocked runs state which real behavior remains unverified.