Collection runner

The runner sends the HTTP requests of a collection (or one folder) one after another. Each request runs with its scripts and its Tests tab, so a run doubles as a regression check.

The Runner tab and postguy-cli run --collection use the same engine.

Open the runner

Runner options

Run becomes Cancel while a run is in progress. Results stream in per request, grouped by iteration, with a progress bar.

Results

• A summary row shows passed, failed and skipped counts, the duration, and a stopped badge with the reason when the run ended early.
• The filters All, Passed, Failed and Skipped narrow the list.
• Each request row shows a PASS, FAIL, ERROR or SKIP badge.
• Select a row to see its details:
  • URL and error.
  • Script failures (phase, origin, line).
  • Tests with assertion badges.
  • pg.report fields.
  • For a failed request, an excerpt of the response body (first 1,024 characters).
• The Download report row writes the run in any of the report formats.

A run reads one snapshot of the collection and writes no history entries. When a script changes variables, the runner reloads the collection so later requests see them.

Iterations and data files

An iteration runs the whole request plan once. Postguy picks the iteration count in this order:

1. An explicit count, if you set one.
2. Otherwise one iteration per data row.
3. Otherwise 1.

In the Runner tab, a count of 1 with a data file loaded means "one iteration per row". Set a count above 1 to override it. The CLI passes --iterations through as given.

Row n is used for iteration n. Its columns become variables in the Data scope. That scope sits above the environment and below runtime and local values (see Variables). Scripts read them with pm.iterationData (see the scripting API). If an iteration has no row (more iterations than rows), the data variable stays unresolved.

username,expected_status
alice,200
bob,403

[
  { "username": "alice", "expected_status": 200 },
  { "username": "bob", "expected_status": 403 }
]

Use {{username}} in a URL, header or body to read the column.

Sequencing from scripts

A setNextRequest loop is cut off after 10,000 requests in one iteration, with a warning.

See Scripts and tests for the phases and Scripting API for the full list of globals (pm, pg, bru).

Stored runs

Every finished run is saved as .postguy/runs/<collection-id>/<run-id>.json in the workspace.

• Only the newest 20 runs per collection are kept. Older files are deleted when a new run is saved.
• You cannot delete a single run from the UI yet.
• A run file larger than 32 MiB is not read back.

Report formats

The Download report row offers all of these formats, and postguy-cli run --reporters writes them. Date and time use the local time zone.

CSV, Excel and PDF share one table.

Requests table columns

#, Iteration, Folder, Request, Method, URL, Status code, Result, Response time (ms), Size (bytes), Assertions passed, Assertions failed, Tests passed, Tests failed, Started at, Failure details, Response excerpt (failed only), then one column per key set with pg.report.set (in order of first appearance). Result is PASS, FAIL, ERROR or SKIPPED.

Tests table columns (Excel Tests sheet)

#, Iteration, Folder, Request, Kind (Assertion or Test), Name, Status (PASSED, FAILED, SKIPPED), Message.

pg.report accepts at most 100 keys, key length 128 characters and values of 32 KiB. See the scripting API.

Command line

postguy-cli run --collection runs the same engine without a window. Use it in scripts and CI. The binary ships in the release archives and in the Windows installer. See Installation.

postguy-cli run --collection ID_OR_NAME --workspace DIR \
  [--folder F] [--environment E] [--iterations N] [--delay MS] [--data FILE] \
  [--bail] [--requests ID,ID] [--reporters cli,json,junit,html,csv,xlsx,pdf] \
  [--out DIR] [--root DIR]

• A name must match exactly one item. An unknown or ambiguous name prints the candidates (name (id)) and exits 2.
• The cli reporter prints to stdout.
• Every other reporter writes <out>/postguy-run-<run id>.<ext> (xml for junit) and prints wrote <path>.
• Reporters run in the order given.

The command stores the run in the workspace like the Runner tab does, so it changes .postguy/runs/.

GitHub Actions

This job installs the CLI from a release, runs a collection stored in the repository and uploads the JUnit file.

The archive name follows postguy-cli-<version>-linux-<arch>.tar.gz and holds a directory with the postguy-cli binary. Set POSTGUY_VERSION to a version that exists on the releases page.

name: api-tests
on: [push, pull_request]

jobs:
  run-collection:
    runs-on: ubuntu-latest
    env:
      POSTGUY_VERSION: "0.0.3"   # a release that ships the CLI tarball; use a newer one when it does
    steps:
      - uses: actions/checkout@v4

      - name: Install postguy-cli
        run: |
          name="postguy-cli-${POSTGUY_VERSION}-linux-x86_64"
          curl -fL -o cli.tar.gz \
            "https://github.com/zuramai/postguy/releases/download/v${POSTGUY_VERSION}/${name}.tar.gz"
          tar -xzf cli.tar.gz
          echo "$PWD/${name}" >> "$GITHUB_PATH"

      - name: Run the collection
        run: |
          postguy-cli run \
            --collection "Smoke tests" \
            --workspace ./postguy-workspace \
            --environment "CI" \
            --reporters cli,junit \
            --out reports \
            --bail

      - name: Upload the report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: junit
          path: reports/*.xml

• The step fails when postguy-cli exits with 1 or 2.
• --reporters cli,junit keeps the console text and writes the XML in one run.
• Use a dedicated environment without secrets for CI, or provide secret values through your own mechanism. Secret variable values live in .postguy/secrets.json, which is not part of the files you commit (see Privacy and security).