@postman/postman-plugin 0.5.0 → 0.6.0-rc.0

package/skills/performance-testing/references/gatling-import/README.md

@@ -0,0 +1,141 @@
+# Importing a Gatling project into Postman
+
+> Reference for the `performance-testing` skill. Convert the simulation, review the gap report, then the result is an ordinary performance run. Verifying it runs one iteration of real requests against the target, so confirm the target first — the same way any action with effects outside this session gets confirmed.
+
+## Overview
+A Gatling simulation is code: a scenario of `http()` requests, checks, feeders,
+pauses and flow control, plus a `setUp` that injects load and asserts on
+results. Postman splits the same thing in two:
+- the **collection** (requests, test scripts, variables, data file), and
+- the **run config** (`postman performance run` flags: VUs, duration, load profile, pass criteria).
+
+You do the whole translation by reading the source and applying the files next to
+this one — there is no importer to run. Two disciplines keep you honest, both
+described below: an **inventory** (list every construct first, so nothing is
+dropped silently) and a **self-verify** pass (prove every construct landed
+somewhere or is explained, and that the collection actually runs).
+
+A conversion that runs but silently drops a check, or quietly changes the load
+model, is worse than no conversion, because the user will trust the numbers.
+**The gap report is a first-class output, not an apology.**
+
+## Workflow
+
+1. **Discover.** Find the simulation(s): classes that `extends Simulation`,
+   Kotlin `: Simulation()`, or JS/TS `simulation((setUp) => …)`. Note the language
+   and build tool. If there is more than one simulation, ask which to convert.
+   Convert one simulation per output directory.
+2. **Inventory.** Read every source file the simulation touches and list **every
+   construct a conversion must account for** — see *Inventory: what to list*. This
+   is your checklist; each item gets a stable id. Pay attention to requests built
+   in loops or helper methods and to dynamic names — a shallow scan misses them.
+3. **Translate** each item using the files next to this one:
+   - `mapping.md`: requests, EL, checks, protocol settings, groups, flow control, custom code
+   - `feeders.md`: feeders → data file + distribution
+   - `injection.md`: injection profiles, throttle, assertions → run flags
+   - `unsupported.md`: what becomes a gap, and how to word it
+4. **Write outputs** to the output directory (formats below).
+5. **Verify** against the checklist in *Verify: self-review* — including, after you
+   confirm the target, one real smoke iteration via the existing
+   `postman collection run` command. Fix everything that fails and re-check, up to
+   3 rounds.
+6. **Report** to the user: counts (mapped / approximated / gap), the verify
+   result, and the top 3 things they must do by hand. Point them to MIGRATION.md.
+
+## Inventory: what to list
+List every construct below that appears in the simulation, each with a **stable
+id** (used verbatim in the MIGRATION.md coverage table). Kinds and id prefixes:
+
+- `req:<name>` — each `http("name").get/post(...)` request.
+- `check:<req>#<n>` — each check on a request (`status`, `jsonPath`, `jmesPath`, `regex`, `header`, `bodyString`, `substring`, `responseTimeInMillis`, …). A request with **no** `status` check still has Gatling's implicit 2xx-or-304 check — list it as `implicit-status:<req>`.
+- `scenario:<name>`, `group:<name>` — scenarios and groups.
+- `feeder:<file>` and `feed:<n>` — feeder sources and `feed(...)` calls (one logical data source emits both; see `feeders.md`).
+- `timing:<n>` — `pause`, `pace`, `rendezVous`.
+- `flow:<construct>#<n>` — `repeat`, `during`, `forever`, `doIf`, `tryMax`, `exitHereIfFailed`, `doSwitch`, … 
+- `inj#<n>` — each injection step (open or closed model).
+- `throttle#<n>`, `max-duration` — throttle / `maxDuration`.
+- `assert#<n>` — each `setUp(...).assertions(...)` entry.
+- `proto:<setting>` — each `http.baseUrl/header/acceptHeader/shareConnections/enableHttp2/...`.
+- `non_http:<proto>:<name>` — `ws`, `sse`, `grpc`, `mqtt`, … steps (and their checks).
+- `code:<n>` — custom-code `exec(session -> …)` lambdas.
+- `secret:<n>` — any literal that looks like a credential (API key, token, `Authorization` value). **Record only that it exists — never copy the literal anywhere.**
+
+A request built in a loop or helper, or named dynamically, still gets an id; find it by reading, not pattern-matching. If you are unsure a construct exists, list it and resolve it to a gap rather than omit it.
+
+## Output formats
+### `collection.json`: Postman collection v2.1
+- `info.schema` = `https://schema.getpostman.com/json/collection/v2.1.0/collection.json`
+- `info.description` is a plain string whose first line is exactly `imported-from: gatling` followed by two lines `source: <relative source path>` and `class: <simulation class/name>`. Example: `"imported-from: gatling\nsource: src/test/java/poc/BasicSimulation.java\nclass: BasicSimulation"`.
+- One collection per simulation. One folder per Gatling `group`; with **no** groups, requests sit at the collection root (a bare request name, no folder prefix — that is valid). Requests keep their Gatling names exactly (they drive per-request metrics), and **request leaf names must be unique** (a collection cannot hold two requests with the same path — see `repeat` in mapping.md).
+- Base URL → collection variable `baseUrl`. Requests use `{{baseUrl}}/path`.
+- Each request's test script ends with the translated checks. Mark translated custom code with `// REVIEW: translated from Gatling custom code (<inventory id>)`.
+
+### `environment.json`: Postman environment
+`{"name": "<simulation> (from Gatling)", "values": [{"key": "...", "value": "...", "enabled": true}]}`.
+Secrets become keys with an **empty value** and `"type": "secret"`. Never copy a
+secret literal from the source (see Critical rules). This file holds **secrets and
+externalised config only** — `baseUrl` and correlation values are collection variables, not
+environment keys. **Always write the file**, even when there is nothing to put in it: a
+simulation with no secrets and no externalised config gets `"values": []`. (An empty
+environment is correct and expected, not a defect.)
+
+### `data/<name>.csv`
+Copy feeder files that the simulation uses. Convert JSON array feeders to CSV if they are flat. If the simulation has **no feeder**, don't create a `data/` directory at all (and omit `--data-file` from run.sh).
+
+### `run.sh`
+```bash
+#!/usr/bin/env bash
+# Converted from <Simulation>. Replace <collection-uid> after pushing the collection to a workspace.
+postman performance run "<collection-uid>" \
+  --environment "<environment-uid>" \
+  --vu-count 20 --duration 5 --load-profile ramp-up \
+  --data-file data/users.csv \
+  --pass-if "less_than(error_rate, 1)"
+```
+Only flags that exist in `postman performance run --help` (check the user's installed
+version; don't assume a flag from a newer CLI). Duration is in whole minutes, rounded up.
+- `--environment` — include it whenever `environment.json` has any values (the secrets/config requests depend on). Requests using `{{secret}}`/config resolve to nothing without it. Tell the user to import and **populate** `environment.json`, then replace `<environment-uid>` with its UID. Omit the flag only when the environment is empty (`values: []`).
+- `--data-file` only if the simulation has a feeder; **omit the line entirely** when there is none (don't invent a data file).
+- `--pass-if`: **at most one**, chosen by the strict priority in `injection.md` (error-rate, then latency percentile, then mean/rps) — this overrides source order. If **no** source assertion matches any category, **omit `--pass-if` entirely**. Every non-chosen assertion goes to the gap report.
+
+### `MIGRATION.md`: gap report (also your accounting record)
+Sections, in order:
+1. **Summary**: source, counts (mapped / approximated / gap), verify result. The counts must equal the coverage-table tally; derive them from the table, don't hand-write them.
+2. **Load model**: the original injection profile, the chosen flags, and the arithmetic (see `injection.md`). Required even when the mapping is exact.
+3. **Coverage**: a table with one row per inventory id — this is the accounting that replaces a manifest. Columns: `id` · `kind` · `status` (`mapped` / `approximated` / `gap`) · `landed` (where it went, or why it was dropped). **Every inventory id appears here**; a missing row is a silently-dropped construct. Use these idioms in `landed`:
+   - request → `collection:<folder>/<request>` (root request → just the name)
+   - check / saveAs → `collection:<req> › test` (a `saveAs` value is script-set, so it is a test-script line, not a declared collection variable)
+   - protocol setting on every request → name each request it lands on
+   - scenario → `the collection itself`; group → `folder <name>`
+   - injection → the `run:` flags it set
+   - secret → `environment:<key> (placeholder, value not copied)`
+4. **Approximations**: one bullet per approximated id: `` `<id>` ``, what changed, why, what to check.
+5. **Gaps**: one bullet per gap id: `` `<id>` ``, what was dropped, why, and the manual workaround if there is one.
+6. **Secrets**: which environment keys the user must fill in.
+7. **Next steps**: push the collection, fill secrets, run a short test, compare with a Gatling baseline.
+
+Every `approximated` or `gap` id **must appear verbatim** in both the coverage table and its Approximations/Gaps bullet.
+
+## Verify: self-review
+Before claiming done, check each of these against your own output and fix every miss:
+
+1. **Accounting** — every inventory id has a row in the MIGRATION.md coverage table; every `approximated`/`gap` id also has its bullet. Nothing dropped silently.
+2. **Collection** — valid v2.1, `info.description` stamped `imported-from: gatling`, every request has a method and a URL, and no two requests share the same folder/name path.
+3. **Variables** — every `{{var}}` used anywhere in the collection is defined somewhere: a collection variable, an environment key, a data-file column, or set by an earlier request's script. An undefined `{{var}}` is a bug.
+4. **Secrets** — no secret literal appears in any output file (collection, environment, run.sh, MIGRATION.md). Re-read the source's credential-looking values and confirm none were copied.
+5. **run.sh** — run `postman performance run --help` and confirm every flag you used exists in this CLI version, values are valid (duration a whole number ≥ 1, load profile one of the listed names), and there is **at most one** `--pass-if`.
+6. **Smoke** — the one executable check. Tell the user it sends **one iteration** of the converted requests to the target host(s), name the host(s), and wait for a yes for any host that is not local. Then run the existing CLI:
+
+   ```
+   postman collection run collection.json -n 1 -e environment.json
+   ```
+
+   (add `-d data/<file>` when there is a feeder). Confirm every request executed with no transport error. A `pm.test` failure that comes from the conversion needs an explanation in MIGRATION.md; one that comes from the target (e.g. a 4xx the simulation also expected) just gets noted. If the user declines the traffic, or there is no CLI login / network, skip only this step and say in your report that no request was executed — the other five checks still hold.
+
+## Critical rules
+1. **Never copy a secret literal into any output.** That covers the collection, environment, run.sh and MIGRATION.md. Items of kind `secret` become an environment key with an empty value, and MIGRATION.md tells the user to fill it in. Don't put secrets in descriptions or metadata either.
+2. **Never drop an item silently.** Every inventory id gets a coverage-table row. If you aren't sure, choose `approximated` or `gap` and explain. Don't choose `mapped`.
+3. **Never change the load model silently.** Open-model (arrival-rate) injection has no exact equivalent. Always show the conversion arithmetic in MIGRATION.md → Load model.
+4. **Confirm before sending traffic.** The smoke sends one iteration to the target. Get a yes for any non-local host first. Never run `postman performance run` yourself; the user runs `run.sh`.
+5. **Keep request names identical** to the Gatling `http("…")` names, so results can be compared with old Gatling reports.
+6. **Don't claim done until the self-verify checklist passes.** If you can't get it to pass in 3 rounds, stop and report what is still failing.

package/skills/performance-testing/references/gatling-import/feeders.md

@@ -0,0 +1,31 @@
+# Feeders → data file + distribution
+
+## Sources (`feeder:*`)
+| Gatling | Postman | Status |
+|---|---|---|
+| `csv("f.csv")`, `tsv`, `ssv`, `separatedValues` | copy to `data/f.csv` (convert TSV/SSV to CSV) → `--data-file data/f.csv` | mapped |
+| `jsonFile("f.json")` (a flat array of objects) | `data/f.csv`, or keep JSON (`--data-file` accepts JSON) | mapped |
+| `jsonUrl(url)` | download once (with the user's OK) or leave as a gap | gap unless downloaded |
+| `jdbcFeeder`, `redisFeeder`, `sitemap` | export to CSV by hand | gap. Give the export query in MIGRATION.md |
+| `listFeeder` / `arrayFeeder` (inline data) | write the rows to `data/<name>.csv` | mapped |
+
+The file must sit in `$OUT/data/` so that `run.sh` and the smoke run can find it. Set `manifest.run.data_file` to the file the smoke run should use.
+
+## Strategy
+The Gatling default (no strategy) is **`queue`**. Each record is used once, and the run **crashes** when the records run out.
+| Gatling | `postman performance run --data-file` behaviour | Status |
+|---|---|---|
+| `.circular()` | with `--data-file`, local rows are distributed per the CLI's documented default (confirm in the installed `--help`; it has been random in recent CLIs). Each VU iteration picks a row | approximated. Say the distribution follows the CLI default, not Gatling's round-robin. A Postman Dataset (`--dataset-distribution round-robin`) is the exact match |
+| `.random()` | random | mapped |
+| `.shuffle()` | random (with replacement) | approximated |
+| `.queue()` / default | random; rows can repeat and the run never runs out | approximated. **Always** call out that uniqueness is lost: if the source relies on each row being used once (unique users, one-time tokens), the test will behave differently |
+| `.shard()` | none | gap |
+| `.batch()`, `.eager()`, `.transform(...)`, `.unzip()` | `eager` and `batch` are no-ops. `transform` → a pre-request script | approximated |
+
+## `feed(...)` calls (`feed:*`)
+`feed(f)` at the start of the scenario → each iteration gets a row, and the columns become variables `{{column}}`. Mapped, with `target: "data:data/<file>"`.
+`feed(f, n)` (several records at once) → gap.
+
+**One data source, two inventory ids.** The inventory emits a `feeder:*` id (the source + its distribution strategy) **and** a `feed:*` id (the binding that hands a row to each iteration), both describing one logical data file. Account for them split by concern: the `feed:*` id is **mapped** (`target: data:data/<file>` — row → `{{column}}` variables), and the `feeder:*` id carries the **strategy** status (e.g. `.circular()` → **approximated**, "distribution follows the CLI default, not round-robin"; default `queue` → **approximated**, "uniqueness lost"). Both may point at the same `data:` target; that is expected, not a duplicate.
+
+**Multiple feeders.** A scenario with more than one `feed(...)` (e.g. `feed(users).feed(products)`) has **no exact mapping**: `postman performance run` takes a single `--data-file` and the smoke run a single `-d`, so only one set of columns can bind. Do **not** emit two `--data-file` bindings and mark both mapped — one set would silently go unbound. Instead either: (a) **combine** the sources into one CSV/dataset by joining their columns, and document the changed row pairing/distribution in MIGRATION.md (**approximated**); or (b) map the primary feeder and record the others as **gaps**, naming which `{{columns}}` won't resolve. State the choice in the coverage table.

package/skills/performance-testing/references/gatling-import/injection.md

@@ -0,0 +1,88 @@
+# Load model: injection, throttle, duration, assertions → `postman performance run`
+
+## What Postman supports (verify against the installed `postman performance run --help`; don't assume a version)
+- **Closed model only.** `--vu-count N` virtual users each loop the collection until the run ends. There's no arrival rate and no target RPS.
+- `--load-profile`: `fixed` (N the whole time), `ramp-up` (grows to N), `spike` (a burst to N), `peak` (rises to N, holds, falls). Each has a fixed shape; you can't set stage times from the CLI.
+- `--duration` in whole minutes (≥ 1). `--pass-if` takes **one** condition: `less_than|greater_than|less_than_eq|greater_than_eq(avg|p90|p95|p99|error_rate|rps, value)`. `error_rate` is a percentage.
+- Cloud runs need `--vu-count` ≥ 10. For local runs, any value ≥ 1 works.
+
+## Injection (`inj:*`)
+**Closed steps: exact or near-exact.**
+| Gatling | Flags | Status |
+|---|---|---|
+| `constantConcurrentUsers(n).during(d)` alone | `--vu-count n --load-profile fixed --duration ceil(d)` | mapped (approximated if d isn't whole minutes: say "rounded up") |
+| `rampConcurrentUsers(a).to(b).during(d)`, then `constantConcurrentUsers(b).during(h)` | `--vu-count b --load-profile ramp-up --duration ceil(d+h)` | approximated: the ramp/hold ratio is fixed by the profile |
+| `rampConcurrentUsers(a).to(b)` alone | `--load-profile ramp-up` | approximated |
+| `incrementConcurrentUsers` (steps) | `ramp-up` to the final level | approximated: no stairs |
+
+**Open steps: always approximated.** Gatling open users run the journey **once** and leave. Postman VUs loop. To keep the same load on the server, match the concurrency using Little's law:
+
+> **VUs ≈ arrival rate (users/s) × journey time (s)**
+
+- **Know whether the injector's number is a count or a rate — this is the most common mistake.** `constantUsersPerSec(r)` and `rampUsersPerSec(a).to(b)` are **rates** (users **per second**) — use them directly. `rampUsers(n).during(d)` and `atOnceUsers(n)` are a **total count** of users, not a rate: `rampUsers(50).during(60s)` is 50 users spread over 60 s = an arrival rate of `50/60 ≈ 0.83 users/s`, **not** 50/s. Convert a count to a rate (`n/d`) *before* Little's law. Skipping this step inflates `--vu-count` by the factor `d`.
+- **Journey time** = the sum of pauses (use the mean for ranges, e.g. `pause(1,3)` → 2 s) + the expected response times. Use `0.3 s` per request if unknown, and say so — **but** if a path makes the latency evident (e.g. `/delay/1` ≈ 1 s, a Gatling request literally named "slow …"), use that value instead and note it. Pick one rule per conversion and state it, so two runs don't diverge.
+- **Cloud VU floor.** If the computed `--vu-count` is below 10 and the user will run on **cloud**, keep the computed value but add a one-line note that cloud requires ≥ 10 (so they raise it deliberately, knowing it increases load). For **local** runs any value ≥ 1 is fine. Never silently inflate the count to clear the floor.
+- **`pace(d)` is a floor, not an addend.** `pace` forces each iteration to take *at least* `d`; it does **not** add to the request/pause time, it subsumes it. So when a scenario has `pace(d)`, the journey time is `J = max(d, pauses + response times)`, **not** `pauses + response times + d`. Adding `pace` as a term overstates `J` and inflates `--vu-count`. Show the `max(...)` in MIGRATION.md.
+- **A loop inside the per-user journey changes what `J` is.** If the open-model journey wraps a `during(t) { … }` / `forever { … }` loop (often with `pace`), each arriving user stays busy for the **whole loop duration**, so `J` is that duration, not one pass. Example: `constantUsersPerSec(20)` over a journey of `during(5.minutes){ pace(5s).exec(...) }` → `J = 300 s`, so `VUs ≈ 20 × 300 = 6000`, not `20 × (one 5 s iteration)`. This is usually a very large number — **do not silently pick the one-iteration reading**; compute both, put the arithmetic and the chosen reading in MIGRATION.md → Load model, and tell the user to confirm, because it swings `--vu-count` by orders of magnitude. A finite closed cap (`maxDuration`, cloud VU limits) may force you lower; say so.
+- Round up to `--vu-count` ≥ 1. **Do not bump a sub-10 result up to 10 for cloud here** — the **Cloud VU floor** rule above governs that: keep the computed value and warn the user cloud needs ≥ 10, so load is never silently increased without their decision.
+
+| Gatling | Flags |
+|---|---|
+| `constantUsersPerSec(r).during(d)` | `--vu-count ceil(r × J) --load-profile fixed --duration ceil(d)` |
+| `rampUsersPerSec(a).to(b).during(d)` (then `constantUsersPerSec(b)…`) | `--vu-count ceil(b × J) --load-profile ramp-up`, with duration the sum of all steps |
+| `atOnceUsers(n)` | a burst: `--load-profile spike --vu-count n` if it's the main (only sustained) step. **When it coexists with a ramp/constant step, the sustained step is the dominant shape** — use that profile and its Little's-law VU count; fold the burst in as the initial spike and note it. Only when the burst's `n` exceeds the sustained VU count does it set the peak (use the larger, and say so) |
+| `rampUsers(n).during(d)` | **`n` is a total count, not a rate.** `n` users arrive evenly over `d`, so first convert to a rate `n/d` users/s, then `--vu-count ceil((n/d) × J)`, ramp-up. E.g. `rampUsers(50).during(60s)` → `50/60 ≈ 0.83/s`, **not** 50/s |
+| `stressPeakUsers(n).during(d)` | `--load-profile peak --vu-count ceil(peak rate × J)` |
+| `nothingFor(d)` | none. Add d to the explanation. Gap if it's the only step, otherwise approximated |
+| `.randomized()` | none: gap (arrivals aren't randomised) |
+
+When the chain has several steps, choose **one** profile for the dominant shape and put every step with its arithmetic in MIGRATION.md → Load model. Also write what the user should watch for: "Gatling measured N users arriving per second; Postman keeps V users busy. Compare throughput (rps) with your Gatling report rather than user counts."
+
+Example (show your working like this):
+```
+Source: rampUsersPerSec(1).to(10).during(60s), then constantUsersPerSec(10).during(120s)
+Journey: 2 requests × 0.3 s (assumed) + pause(1,2) mean 1.5 s = 2.1 s
+Peak VUs: 10 users/s × 2.1 s = 21 → --vu-count 21
+Duration: 60 + 120 = 180 s = 3 min → --duration 3
+Profile: ramp-up (one ramp then a hold; the ramp/hold split is fixed by the profile, not 1:2)
+```
+
+Count-based injectors — convert the count to a rate FIRST (this is the step that most often goes wrong):
+```
+Source: atOnceUsers(5), then rampUsers(50).during(60s)
+Rate:    rampUsers(50).during(60s) = 50 users over 60 s = 50/60 ≈ 0.83 users/s   ← NOT 50/s
+Journey: 3 requests × 0.3 s (assumed) + pause 0.5 s × 3 + /delay/1 ≈ 1 s = ~3.7 s
+Sustained VUs: 0.83 users/s × 3.7 s ≈ 3.08 → 4
+Burst:   atOnceUsers(5) = 5 users at once; 5 > 4, so the burst sets the peak → --vu-count 5
+Duration: 60 s = 1 min → --duration 1 ; Profile: ramp-up
+```
+(Reading `rampUsers(50)` as 50 users/s here would give `50 × 3.7 ≈ 185` VUs — ~40× too high.)
+
+## Throttle (`throttle:*`) and max duration
+- `throttle(reachRps(r).in(t), holdFor(h))`: there's no RPS cap. **Gap**, and say that Postman won't hold throughput at r. The user can lower `--vu-count` to get near it.
+- `maxDuration(d)`: `--duration` is already a hard stop. Mapped to `run:--duration` if d ≥ the computed duration. Otherwise use d, and approximate.
+
+## Assertions (`assert:*`)
+The CLI takes **at most one** `--pass-if`. Pick it by this **strict priority — this overrides the order the assertions appear in the source**:
+1. a global error-rate assertion (`failedRequests`/`successfulRequests` → `error_rate`)
+2. a global latency percentile (`p95`, then `p99`, then `p90`)
+3. a global `mean` (`avg`) or `requestsPerSec` (`rps`)
+
+Walk the list top-down and take the **first category that a source assertion matches**, even if a different assertion came first in the source. Example: a simulation with `responseTime().percentile(95).lt(800)` **and** `failedRequests().percent().lt(1)` → the `--pass-if` is `less_than(error_rate, 1)` (category 1 wins), and the p95 assertion is the **gap**, not the other way round.
+
+All non-chosen assertions are **gap**, reason "the CLI takes one pass condition". Suggest adding them as run criteria in the app, where several aggregate checks are allowed.
+
+**If no source assertion matches any category** (e.g. only `forAll`/`details(...)` per-request assertions, or only `responseTime().max()` which has no CLI metric), emit **no `--pass-if` flag at all** — this is correct and expected, not a defect. Record every assertion as a gap and tell the user to add run criteria in the app. A `run.sh` with zero `--pass-if` is valid.
+| Gatling | `--pass-if` | Notes |
+|---|---|---|
+| `global().failedRequests().percent().lt(x)` | `less_than(error_rate, x)` | approximated (see error-rate note below) |
+| `global().failedRequests().count().is(0)` | `less_than_eq(error_rate, 0)` | approximated (percentage instead of count; + error-rate note) |
+| `global().successfulRequests().percent().gt(x)` | `less_than(error_rate, 100 - x)` | approximated (see error-rate note below) |
+| `global().responseTime().percentile(95).lt(ms)` (Scala `percentile3`) | `less_than(p95, ms)` | mapped (also p90, p99. Other percentiles → the nearest, approximated) |
+| `global().responseTime().mean().lt(ms)` | `less_than(avg, ms)` | mapped |
+| `global().responseTime().max()` / `min()` / `stdDev()` | none | gap |
+| `global().requestsPerSec().gt(r)` | `greater_than(rps, r)` | mapped |
+| `forAll…` / `details("group", "req")…` | none (no per-request criteria) | gap |
+| `lte` / `gte` | `less_than_eq` / `greater_than_eq` | — |
+
+**Error-rate note (why failed/successful-request mappings are approximated).** Gatling's `failedRequests` counts a request as failed when a **check** fails, even on an HTTP 200. Postman's `error_rate` counts transport/runtime errors and may **not** count a request that returned a response but failed a translated `pm.test` (behaviour differs by runner). So a batch of 200s that all fail a JSON check would fail Gatling's gate but can **pass** `less_than(error_rate, …)`. Map `failedRequests`/`successfulRequests` → `error_rate` as **approximated**, say so in MIGRATION.md, and note it's a weaker gate than Gatling's (plus any hosted-runner limitation). If the failure the user cares about is a check, a latency percentile or `rps` criterion may be the more faithful gate.

package/skills/performance-testing/references/gatling-import/mapping.md

@@ -0,0 +1,91 @@
+# Mapping: requests, EL, checks, protocol, flow, custom code
+
+## Protocol settings (`proto:*`)
+| Gatling | Postman | Status |
+|---|---|---|
+| `.baseUrl("https://h")` | collection variable `baseUrl`; requests use `{{baseUrl}}/…` | mapped |
+| `.baseUrls(a, b)` | first one as `baseUrl`; note the round-robin | approximated |
+| `.header(k, v)`, `.headers(map)` | header on every request (or collection pre-request `pm.request.headers.upsert`) | mapped |
+| `.acceptHeader`, `.contentTypeHeader`, `.userAgentHeader`, `.authorizationHeader` … | the matching header on every request | mapped |
+| `.basicAuth(u, p)` | collection auth `basic`, with `{{user}}` / `{{password}}` from the environment | mapped |
+| `.shareConnections()` | none. The runtime manages connections | gap (no-op; performance may differ) |
+| `.enableHttp2()` | none. HTTP/1.1 only | gap |
+| `.inferHtmlResources()` | none. Embedded resources are not fetched | gap |
+| `.disableCaching()`, `.disableFollowRedirect()`, `.maxConnectionsPerHost()` | none, or the request setting `followRedirects: false` | gap / mapped for redirects |
+| `.warmUp(url)` | none | gap |
+
+If a header value is a secret (an inventory `secret` item, or a name like `x-api-key` or `authorization` with a literal), use `{{<camelCaseName>}}` and add an empty environment key.
+
+## Requests (`req:*`)
+- Name: keep the `http("…")` name exactly.
+- Method and path: `.get("/p")` → `GET {{baseUrl}}/p`. An absolute URL stays absolute.
+- `.queryParam(k, v)` → a URL query param. `.formParam(k, v)` → `body.mode: urlencoded`. `.body(StringBody("…")).asJson()` → `body.mode: raw`, `options.raw.language: json`, plus header `Content-Type: application/json`.
+- `.header(k, v)` on a request → that request's header.
+- `ElFileBody("x.json")` / `RawFileBody` → inline the file contents into the raw body (translate EL inside it).
+
+## EL → Postman variables
+| Gatling EL | Postman |
+|---|---|
+| `#{name}` | `{{name}}` |
+| `#{randomUuid()}` | `{{$guid}}` |
+| `#{randomInt()}` / `#{randomInt(a,b)}` | `{{$randomInt}}` (0–1000, approximated), or a pre-request script for a range |
+| `#{randomLong()}` | a pre-request script, stored in a variable |
+| `#{currentTimeMillis()}` | `{{$timestamp}}` is seconds, so use a pre-request script: `pm.variables.set('now', Date.now())` |
+| `#{name.size()}`, `#{name(0)}`, `#{name.random()}` | a pre-request script over the parsed variable |
+| `#{name.jsonStringify()}` | a pre-request script `JSON.stringify(...)` |
+| `#{i}` from `repeat(n, "i")` | see Flow → loops |
+
+Every `{{var}}` must be defined somewhere: the environment, collection variables, a data-file column, or set by an earlier script. The self-verify step checks this.
+
+## Checks (`check:*`) → test script
+Put the checks in the request's `test` event, in source order. Name each `pm.test` after what it asserts.
+| Gatling | Test script |
+|---|---|
+| `status().is(200)` (Kotlin: `shouldBe`) | `pm.test('status is 200', () => pm.response.to.have.status(200));` |
+| `status().in(200, 204)` | `pm.expect([200,204]).to.include(pm.response.code)` |
+| `jsonPath("$.a.b").is("x")` | `pm.expect(pm.response.json().a.b).to.eql('x')`. Gatling compares as a string unless `ofInt()` etc. is used, so compare `String(v)` when the source is a string literal |
+| `jsonPath(...).isEL("#{v}")` | compare with `pm.variables.get('v')` (see **Saved variables scope**: read with `pm.variables.get`, write with `pm.collectionVariables.set`) |
+| `jsonPath(...).exists()` / `.notExists()` | `pm.expect(value).to.not.be.undefined` / `.to.be.undefined` |
+| `jsonPath(...).saveAs("v")` | `pm.collectionVariables.set('v', value)`, and also a `pm.test` that the value exists. **approximated**: Gatling marks the request failed on a missing extraction but, by default, **continues** the scenario — so do **not** add `pm.execution.setNextRequest(null)` here; that would skip the rest of the iteration even though the source doesn't. Stop early only when the source wraps this in `exitHereIfFailed`/`exitBlockOnFail` (see Flow control); if a later request needs to know the extraction failed, track that in a variable. Manifest target: the request's test script (`collection:<req> › test: saveAs v`), **not** `collection-variable:` — the value is script-set, not a declared collection variable |
+| `jmesPath("a.b")` | same as jsonPath, using a JS property path |
+| `regex("p").saveAs("v")` | `const m = pm.response.text().match(/p/); pm.test(..., () => pm.expect(m).to.not.be.null); pm.collectionVariables.set('v', m && m[1] !== undefined ? m[1] : m && m[0])`. Gatling saves group 1 if there is one, otherwise the whole match |
+| `header("h").is(v)` | `pm.expect(pm.response.headers.get('h')).to.eql(v)` |
+| `bodyString().is/contains` | `pm.response.text()` |
+| `substring("s")` | `pm.expect(pm.response.text()).to.include('s')` |
+| `responseTimeInMillis().lt(n)` | `pm.expect(pm.response.responseTime).to.be.below(n)` |
+| `css(...)` / `xpath(...)` | cheerio (`require('cheerio')`) for CSS if the selector is simple. XPath → gap |
+| `checkIf(cond)` | wrap the assertion in an `if` that translates the condition. Approximated if the condition is custom code |
+
+**Implicit status check (`implicit-status:*`).** When a Gatling request declares no `status()` check, Gatling still fails it unless the status is 2xx or 304. Add `pm.test('status is 2xx/304 (Gatling implicit check)', () => pm.expect(pm.response.code === 304 || (pm.response.code >= 200 && pm.response.code < 300)).to.be.true);`. Status: mapped.
+
+**Saved variables scope.** For correlation, **write** with `pm.collectionVariables.set('v', value)` and **read** with `pm.variables.get('v')` (the general resolver sees collection scope, so the two are consistent — don't mix `pm.collectionVariables.get` and `pm.variables.get` for the same value). In a performance run each virtual user has its own variable scope, which matches Gatling's per-user `Session`. A value saved this way is set by a script at run time, so it is **not** a declared collection variable — in the MIGRATION.md coverage table a `saveAs` lands on the request's test script, not a `collection-variable`.
+
+**Name collisions with feeder columns.** Data-file (`iterationData`) values outrank collection variables when `{{x}}` / `pm.variables.get('x')` resolves (see `postman:variables`). So if a `saveAs`/session key has the **same name as a feeder column**, `pm.collectionVariables.set('x', …)` will **not** override it — `{{x}}` still resolves to the feeder's value, unlike Gatling where the later session write wins. When a saved key collides with a feeder column, **rename** the saved key (or the column) and use the renamed key consistently across the extraction, any custom-code translation, and the request substitutions; note the rename in MIGRATION.md.
+
+## Scenario, groups (`scenario:*`, `group:*`)
+- Scenario → the collection itself (name the collection after it). If `setUp` has several scenarios, convert the main one and list the others as a gap: one collection per run.
+- `group("g")` → a folder named `g` containing the requests in the group. Status: approximated. Postman reports per-request metrics, and there's no folder-level (transaction) timing. Say so.
+
+## Flow control (`flow:*`)
+| Gatling | Postman | Status |
+|---|---|---|
+| `exec` chain (sequential) | request order in the collection | mapped |
+| `repeat(n) { … }` / `repeat(n, "i")` | Use **one** request with a `setNextRequest` loop + a counter collection variable, so the single leaf runs n times. **Never unroll into n copies that share the same name**: a Postman collection can't hold two request leaves with the same path — so the "copies named `name`" shortcut is invalid. The loop also keeps the metric name identical (which is what unrolling was for). Only unroll if the body genuinely differs per iteration, and then give each copy a **distinct** name and note in MIGRATION.md that per-iteration metrics are split across those names. For `repeat(n, "i")`, set the counter as `{{i}}` in the loop script. **When the body is a chain of several requests** (`repeat(3){ A; B }`), loop the **whole body**, not one leaf: keep A and B as distinct requests and have the body's **last** request jump back to the **first** (`pm.execution.setNextRequest('A')`) while the counter < n, initialising/resetting the counter on first entry — so the order is A,B,A,B,A,B. A single-leaf loop only models a single-request body | approximated (explain the loop/metrics effect) |
+| `during(d) { … }` / `forever { … }` wrapping the main journey | The VU loop itself: a VU repeats the collection until the run ends | approximated (Gatling users in open models start and stop. Here VUs loop) |
+| `asLongAs(cond)`, `doWhile` | `setNextRequest` loop with a condition in the test script | approximated |
+| `doIf(cond) { r }` | in the pre-request of `r`: `if (!cond) pm.execution.skipRequest()`. The condition is translated to JS (session attribute → `pm.variables.get`) | **mapped** if the condition reduces to a simple equality/comparison on a session value — *even when written as a lambda* (e.g. `session -> session.getString("tier").equals("gold")` → `pm.variables.get('tier') === 'gold'`). **approximated** only if it calls out to logic you can't express as a plain JS comparison (library calls, computation, external state). A lambda by itself does not force "approximated"; judge the body |
+| `doIfOrElse`, `doSwitch`, `randomSwitch`, `roundRobinSwitch` | `skipRequest` logic per branch. `randomSwitch` percentages via `Math.random()` in a pre-request | approximated |
+| `tryMax(n) { r }` | none. A request that fails isn't retried | gap. Suggest checking the error rate instead |
+| `exitHereIfFailed` | in the test script: `if (pm.response.code >= 400) pm.execution.setNextRequest(null)` — ends the whole iteration | approximated (only stops on status failure, not on any failed check, unless you track that in a variable) |
+| `exitBlockOnFail { … }` | exits **only its block**, then resumes after it — so on failure jump to the **first request after the block** (`pm.execution.setNextRequest('<next>')`), **not** `null`. Ending the iteration would skip requests/cleanup that sit outside the block | approximated (status-failure only unless you track check failures in a variable) |
+| `stopLoadGenerator` / `crashLoadGenerator` | none | gap |
+
+## Custom code (`code:*`)
+`exec(session -> …)` (Java), `exec { session -> … }` (Kotlin), `exec(session => …)` (Scala, JS):
+- Translate it to a **pre-request script** on the next request.
+  - `session.set("k", v)` → `pm.collectionVariables.set('k', v)`
+  - `session.getString("k")` → `pm.collectionVariables.get('k')`
+  - `session.userId()` → `pm.info.iteration`, as an approximation
+  - `UUID.randomUUID()` → `crypto.randomUUID()` if available, otherwise `pm.variables.replaceIn('{{$guid}}')`
+- Always prefix it with `// REVIEW: translated from Gatling custom code (<id>)`. Status: approximated. List it in MIGRATION.md → Approximations, with the original code.
+- JVM library calls you can't translate (JDBC, crypto libraries, file IO) → gap.

package/skills/performance-testing/references/gatling-import/unsupported.md

@@ -0,0 +1,31 @@
+# What can't be carried over, and how to say so
+
+Postman performance runs are **HTTP(S) only** (GraphQL over HTTP and mTLS work). Load settings are the CLI flags in `injection.md`.
+
+## Always a gap
+| Construct | Inventory kind | Wording for MIGRATION.md |
+|---|---|---|
+| `ws(...)`, `sse(...)` | `non_http_step` | WebSocket/SSE steps aren't part of Postman performance runs. They were removed from the load test. Test the socket flow separately (Postman's WebSocket client works for functional checks). |
+| `grpc(...)`, `jms(...)`, `mqtt(...)`, `kafka(...)`, `amqp(...)` | `non_http_step` | This protocol isn't supported under load in Postman. These steps were removed. |
+| `rendezVous(n)` | `timing` | There's no way to synchronise virtual users. Users won't wait for each other. |
+| `pace(d)` | `timing` | There's no iteration pacing: VUs start the next iteration immediately. Add an explicit delay in the last request's test script only if the pacing matters (`setTimeout` isn't reliable under load, so prefer lowering `--vu-count`). |
+| `throttle(...)` | `throttle` | There's no RPS cap. Throughput isn't limited to the Gatling target. |
+| `tryMax(n)` | `flow` | Failed requests aren't retried. |
+| `stopLoadGenerator`, `crashLoadGenerator` | `flow` | There's no scripted run abort. Use `--pass-if` to fail the run afterwards. |
+| `.randomized()` on injection | `injection` | Arrivals aren't randomised. |
+| `.enableHttp2()`, `.inferHtmlResources()`, `.shareConnections()` | `protocol_setting` | See `mapping.md`. |
+| second and later assertions | `assertion` | The CLI takes one `--pass-if`. |
+| `forAll` / `details(...)` assertions | `assertion` | There are no per-request pass criteria. |
+| JDBC/Redis feeders | `feeder` | Export to CSV first. |
+| extra scenarios in `setUp` | `scenario` | One collection per run. Convert them separately and run them in parallel. |
+
+## Pauses
+`pause(d)` and `pause(min, max)` (`timing`) have no first-class think time. Always a **gap**; how it affects the result depends on the injection model:
+- **Open model:** the pause is part of the journey time, so it already feeds the Little's-law `--vu-count` arithmetic in `injection.md`. Dropping the think time alone (keeping the computed VU count) means VUs send faster than Gatling users did. Say which metric (rps) to compare with the Gatling baseline.
+- **Closed model:** there is no journey-time arithmetic to fold into — the VU count is the source concurrency directly. The pause is simply dropped: VUs loop with no think time, so they issue more requests per VU than Gatling did. Record it as a gap and tell the user throughput (rps) will be higher than Gatling's; they can lower `--vu-count` to compensate.
+- If the user explicitly wants think time: a pre-request script with a busy-wait isn't acceptable under load. Record it as a gap, and suggest lowering `--vu-count` in proportion.
+
+## Wording rules
+- One bullet per id: `` `<id>` ``, what changed, why, what to do. Keep it to 1–2 lines.
+- Never write "not supported yet" or promise a roadmap. State today's behaviour.
+- If the gap changes the results (pauses, pace, throttle, queue feeders, open-model injection), say which metric to compare with the Gatling baseline.

package/skills/postman-mcp-server/SKILL.md

@@ -9,7 +9,7 @@ MCP exposes workspace resources directly to an agent. Existing collections,
 specs, examples, and environments provide maintained API knowledge; fetching
 the relevant entity preserves that context when a local CLI workflow is not
 available. For repository edits and Git review, prefer the local workflows in
-**api-engineer** and **bootstrap** when available.
+**api-engineer** when available.
 
 Each tool definition exposed to the model consumes context whenever it is
 included in a request. Prefer the smallest available toolset that covers the

package/skills/variables/SKILL.md

@@ -47,8 +47,8 @@ postman environment var set api_key --secret-id <secret-id> --vault-id <vault-id
 
 The environment then carries the vault/secret IDs rather than the value.
 Secret resolution and permission to view the secret are distinct; a teammate's
-ability to run a request need not expose the credential to them. Use
-**bootstrap** when the vault operation needs unresolved authentication.
+ability to run a request need not expose the credential to them. Vault
+operations require a signed-in CLI.
 
 ## Verification
 

package/skills/webhook-testing/SKILL.md

@@ -23,7 +23,7 @@ how to use it:
   to fire it again.
 
 The command is singular, and every subcommand needs a signed-in session. Run what you need,
-and read `bootstrap` only if a command fails with a setup error such as `Authentication required`.
+and sign in only if a command fails with a setup error such as `Authentication required`.
 When all you have is the URL, its subdomain is the webhook id.
 
 For capture or inspection alone, create or reuse a webhook and inspect its

package/skills/workspaces/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: workspaces
+description: Use when initializing Postman in a repository, binding it to a Postman workspace, interpreting what `postman init` did, or when a CLI command fails because the plan, credits, or usage quota don't allow the operation. Treats the workspace as the place where a service's API work and its evidence live, kept separate from the services it depends on. Use for requests such as "set up Postman in this repo" or "connect this repo to our workspace".
+---
+
+# Workspaces
+
+A Postman workspace is where a service's API work happens and where its context
+builds up: the contracts, collections, environments, and mocks, plus the runs
+and results that show what was checked. It lives in Git beside the code, works
+the same on a laptop or a build agent, and is shared when the work should be
+seen. People use it to audit what was done, by whom, on whose behalf, and with
+what result. Agents use it to read verified work instead of re-deriving it.
+
+1. `postman init` is the starting point. It gives the repository its place of
+   work: Postman files beside the code and, when that is the intent, a
+   workspace bound to them. `postman status` shows whether that is already
+   done, so init runs only when it adds something. Init is safe to repeat and
+   reports what it did: a binding it marks as inferred is a candidate contract
+   to confirm, and a partial result, with local files written but no workspace
+   created, is progress to inspect rather than redo.
+2. One workspace holds the context of one service: one Git repository, or in a
+   monorepo one remote URL and the subpath of one service.
+   `.postman/resources.yaml` records that owner, so every skill, CI job, and
+   teammate resolves the same context. A confirmed binding is worth reusing;
+   replacing it sends the work, and its evidence, to the wrong service.
+3. Other services keep their own workspaces. Their collections, environments,
+   and mocks come in as dependencies through **api-discovery**, so this
+   workspace reuses what another team maintains without taking it over. The
+   context graph links the two, which is how a change on one side reaches work
+   on the other.
+
+## Claiming the work
+
+An agent can start in a guest session, and the work it does there is kept.
+When free credits or a plan limit stop an operation, retrying won't help; the
+person claiming the work is what lets it continue. Wording such as "usage limit
+exceeded", "usage quota has been exceeded", a limit "reached", "breached" or
+"exceeded" for the account, team, or plan, or an operation that "does not allow
+more than" or "requires at least" a stated amount signals one. A temporary rate
+limit or a fixed per-resource validation cap does not. Check which session the
+CLI is using:
+
+- Guest session: tell the user, in its own paragraph, that signing up for a
+  Postman account claims the work done so far and adds the credits needed to
+  continue. Offer to start signup for them; the CLI can produce a link to hand
+  over and waits while they finish in the browser.
+- Signed-in account: tell the user, in its own paragraph, that they need to
+  upgrade their plan at https://postman.postman.co/settings/team/billing.
+
+## Verification
+
+Report the binding in place and what `postman init` did.