Update to Postman

{
  "description": "Runs services, frontends, tests or demos against stand-ins for their HTTP dependencies, served as one environment locally or at a deployed URL. Use when you add or change code that calls other services and need to run it, test it, prove a fix or reproduce an upstream failure (timeouts, 5xx, 409, 429) end to end, locally or in CI, without the real services because they're unreachable, need credentials, cost money, have side effects or don't exist yet. Also answers what happens to a request, or to the data it writes, when a service it calls goes down, is slow or returns errors (\"what happens to a booking if the email service is down?\"), by exercising relevant failures and observing caller outcomes. Applies even when nobody says mock or simulation, and a `postman/simulations/` directory in the repository is itself a reason to load this before changing code it covers. To give a frontend or another team a stand-in for an API, use api-mocking. Covers `postman simulation`.",
  "included_files": [
    {
      "relative_path": "reference/context_file.md",
      "size_in_bytes": 10413
    },
    {
      "relative_path": "reference/sim_yaml_schema.md",
      "size_in_bytes": 3835
    }
  ],
  "name": "api-simulation",
  "skill_md_contents": "---\nname: api-simulation\ndescription: Runs services, frontends, tests or demos against stand-ins for their HTTP dependencies, served as one environment locally or at a deployed URL. Use when you add or change code that calls other services and need to run it, test it, prove a fix or reproduce an upstream failure (timeouts, 5xx, 409, 429) end to end, locally or in CI, without the real services because they're unreachable, need credentials, cost money, have side effects or don't exist yet. Also answers what happens to a request, or to the data it writes, when a service it calls goes down, is slow or returns errors (\"what happens to a booking if the email service is down?\"), by exercising relevant failures and observing caller outcomes. Applies even when nobody says mock or simulation, and a `postman/simulations/` directory in the repository is itself a reason to load this before changing code it covers. To give a frontend or another team a stand-in for an API, use api-mocking. Covers `postman simulation`.\n---\n\n# API Simulation\n\nSimulation lets you control how dependencies behave and explore how your code\nresponds to different outcomes. This makes it easier to test assumptions\nrepeatedly without real calls changing data, spending money, or notifying\nsomeone. Simulation context records those assumptions, the evidence supporting\nthem, and what remains unknown. As sessions build on this context, it helps\nsurface incorrect assumptions and avoid repeated investigation.\n\nTogether, the simulation and its context provide a place to explore changes\nand identify what still needs validation against the real dependencies.\n\nCheck whether an existing simulation in `postman/simulations/` covers the\ndependency interactions relevant to the task. Reusing its mocks and wiring\ncan avoid rebuilding an environment; extend it only where the behavior you\nneed to exercise is missing.\n\nThe `<name>.context.yaml` beside a simulation records those assumptions, their\nsupporting evidence, and unresolved questions so later sessions can build on\nearlier findings. For example, a timeout from `/payments` does not establish\nwhether the payment failed or completed before the response arrived. The\ncontext file will document what has been established about the real provider\nand identify what still needs verification.\n\nA simulation serves several mocks as one environment: by default behind a\nproxy that answers for the dependencies' own hostnames, so the code under test\nkeeps the base URLs it ships with, or on one local port where each member is\nreached by its routeKey.\n\nSimulation adds value when the result depends on real HTTP behavior, such as\nclient configuration, serialization, timeouts or retries, and the real\ndependencies are unavailable or unsuitable for the exercise. Stubbing the\nHTTP client can bypass those behaviors. Choose verification that exercises\nwhat matters to the task: an existing test may already answer a local logic\nquestion, while a claim about the provider may need its contract or a real\nservice check. A simulation's log shows what each stand-in was asked.\n\nDefine the expected outcome and what observation would distinguish correct\nfrom incorrect behavior, including side effects when relevant. A request\nthrough the changed path shows that it ran; its response and resulting state\ndetermine whether the expectation held. Choose boundary and failure cases\nfrom the behavior changed and the consequences of getting it wrong.\n\n`postman simulation` needs CLI 1.70.0 or later (`postman --version`; an older\nCLI answers `postman simulation -h` with its general help).\n\n## Building it\n\n- **Members are the code's HTTP dependencies.** Databases, queues and caches\n  aren't; run them locally. **api-discovery** can find calls made through\n  shared code; ask about the repo by its `git remote` name, because a close\n  name matches another repo.\n- **Each member needs a mock: see `api-mocking`,** which looks for the owning\n  team's published mock before building one. Finding and pulling an owner's\n  mock needs a signed-in CLI; check `postman status` first, and signed out,\n  build each mock and record that the owner search was skipped. For a question, one built from\n  the contract will do; one that invents responses can send the caller down a\n  path the real service never would. In a mock you build, answer `501` for calls this path\n  doesn't make: a `404` reads to the caller like a real \"not found\".\n- **Bring in each mock you don't own as a dependency first, then build the\n  simulation over them.** `postman dependency add mock <name-or-id>` declares\n  it in `.postman/resources.yaml` and materialises it under\n  `postman/.dependencies/`, and the member's `path:` points there; `-w\n  <workspace>` resolves a name from the workspace that owns it.\n- **Prefix each mock's `pm.state` keys with its name.** As of CLI 1.73.0,\n  members of a local run read each other's keys, so two mocks storing\n  `orders` overwrite each other.\n\n## Running it\n\nThe run is a server that never exits, so a foreground command never returns.\nStart it in the background, its log in a file:\n\n```bash\npostman simulation run postman/simulations/checkout-dev.sim.yaml --proxy --output ndjson > sim.ndjson 2> sim.err &\n```\n\n`--proxy` is how to run it unless something below rules it out: nothing about\nthe code changes for the run — not a base URL, not a config file, not an SDK's\nbuilt-in host — and because nothing the proxy answers for has to resolve, an\ninternal hostname with no DNS record works.\n\nIt's up when `sim.ndjson` has a `listening` event; a start-up error is in\n`sim.err`, a busy proxy port among them. Stop it with\n`pkill -INT -f \"simulation run .*<file>.sim.yaml\"`. Nothing reloads: restart\nit after a mock edit.\n\nRead `postman simulation run --help` before driving it. The flags, what the\ncaller's own process needs in order to reach the proxy, and what to do about a\nclient that ignores it are all there and change with the CLI, so take them\nfrom the command rather than from here.\n\nWhat decides whether a proxied run proves anything is `origin:`. A member with\nnone in the `.sim.yaml` is never matched, so its traffic reaches the real\nservice and a run can come up having intercepted nothing — `simulation create`\ncopies that field from the mock's manifest, so editing the manifest alone\nwon't fix it ([reference/sim_yaml_schema.md](reference/sim_yaml_schema.md)).\n\n## Running it on one port instead\n\n`--port` puts every member on one local port, each addressable by its routeKey,\nwith the code under test pointed at that port. Reach for it when a client has\nno proxy setting to honour, and when you want to address a member yourself —\neach one keeps a stable URL for the whole run, so a mock's control routes and\nits individual responses are a curl away.\n\n## Reading the log\n\nA passing test command doesn't show the dependency path ran: read\n`sim.ndjson`. A member with no `request` events isn't wired or isn't on this\npath. Some answers come from the simulation itself and mean wiring, not code:\n\n- `404 Unknown simulation member`, on a one-port run: a base URL lost its\n  routeKey, or a client sent the wrong `x-mock-slug`.\n- `501`, or a generated mock's `404 Endpoint not defined`: a call the mock\n  doesn't model yet.\n- `502 Proxy error`: the member's process died, usually an async throw in a\n  mock without `interceptRequests: true`. It stays down and logs nothing\n  until you restart; run that mock alone with `postman mock run` to see why.\n\n## When a dependency goes down\n\nChoose failures from the outcome the user needs to understand. A failure\nbefore a write, a timeout after a write may have completed, and a failure\nduring compensation can expose different risks: lost work, duplicate writes\nor unreleased resources. Read the caller to identify relevant paths, then\nexercise the ones whose runtime behavior remains uncertain.\n\nIsolating one failure helps attribute the result. Combine failures or model\npartial completion when the question depends on their interaction. The\ninjection must represent the event being investigated: delaying a response\nalone does not establish whether a write completed before the timeout.\nExamples of available techniques:\n\n- **Unreachable:** point its base URL at a port nothing listens on. This one\n  needs the one-port run, since under `--proxy` the base URLs are the point.\n- **Hanging:** give its member a `latency` condition longer than the\n  client's timeout. If the client sets none, that is the finding: Node's\n  `fetch` waits about five minutes, so say so rather than wait it out.\n- **An error with a JSON body:** the `error` condition.\n- **An error with an HTML body,** as proxies send: a copy of its mock whose\n  default handler answers `500` with HTML. No condition can do this.\n\nOnly `overrides.conditions` on a member change it. Members always serve\ntheir default handler and ignore `x-mock-scenario`, and a `scenarios` entry\nwith just a `path`, as the Postman app writes, does nothing. Fields and the\nother conditions are in [reference/sim_yaml_schema.md](reference/sim_yaml_schema.md). An injected\nfailure never reaches the mock and isn't logged, so judge it by what the\ncaller did, and check the other members' logs for side effects, such as\nstock reserved and never released.\n\n## Its context document\n\nEvery simulation is created with a `<name>.context.yaml` beside it, holding\nwhat the code is believed to rely on about the dependencies it calls — who the\ncaller is taken to be, which plan or permission is assumed, the order calls go\nin, what gets retried, the shape of the data — and what each belief rests on.\nThe `.sim.yaml` says what the simulation is, not what the services it stands in\nfor do, so this is the record that saves a session the search.\n\nRead relevant claims before investigating the dependencies, and assess whether\ntheir evidence still applies to this task. Write what you established back\ninto the document before you finish. Each claim carries a `status`,\nthe `reason` the evidence adds up to it, the `verification` that was done and\nwhat it showed, and a `source` to re-check it against, so the next session can\ntell a claim a contract promises from one a request actually demonstrated.\nPreserve existing claims and their evidence when updating the file, including\nunresolved assumptions and historical findings. Its fixed schema and guidance\non evidence and reuse are in\n[reference/context_file.md](reference/context_file.md); read that before\nwriting to it.\n\n## Keeping it\n\nCommit your own mocks, the `.sim.yaml`, its context document and what\n`postman dependency add` changed, so the next session or CI reruns it in one\ncommand. Don't commit\n`postman/.dependencies/`: a copy goes stale when its owner updates theirs,\nand `postman dependency install` restores it. Don't commit `sim.ndjson`: the\nCLI redacts common auth headers and fields, but other headers and bodies are\nlogged as sent. In CI, `postman dependency install` needs `POSTMAN_API_KEY`,\nand `postman collection run <collection> --simulation <file> --port <n>`\nstarts and stops the simulation around a collection run.\n\n`postman simulation push` uploads every member to the workspace, so ask\nfirst. It fails on a pulled member, which keeps its owner's `id:`; copy it to\n`postman/mocks/` and delete that line.\n\n## Rules\n\n1. **What you're testing is never a member.** It must run for real, or the\n   test only proves the mock.\n2. **Pull the owner's mock even if it's deployed.** Only members take\n   conditions and appear in the log, and a private mock server wants a key\n   your code won't send.\n3. **`simulation deploy` is public by default,** unlike `mock deploy`. Ask\n   before deploying without `--private`; a local run needs no deploy.\n\n## Before you say it works\n\nClaim a simulation passes only after the code under test ran and you observed\nthe expected response or state change. Use its calls in the log to confirm\nthe dependency path was exercised; for injected failures, use the caller\noutcomes described above. If startup failed or the relevant path never ran,\nreport that limitation. Say what a pass proves,\nyour code against these stand-ins rather than the real services, what still\nneeds the real service before release, and where each mock came from,\nincluding when you skipped the owner's.\n\nThen write what you established back into `<name>.context.yaml`, so the next\nsession starts where this one ended. Add or update claims that help a later\nsession reuse the findings. For each claim the run settled or contradicted,\nupdate its `status`, the `verification` that was done and the `source` to\nre-check it against. Scope what you claim to what you actually\nexercised — \"held in the scenarios run\" rather than \"works\" — since the record\nis read later as evidence, and the two don't mean the same thing.\n[reference/context_file.md](reference/context_file.md) has what each field is\nfor.\n"
}