> ## Documentation Index
> Fetch the complete documentation index at: https://bazable.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Postman Integration

> Generate Postman Collection v2.1 files from your Bazable contract and run them with Newman locally, in mock mode, or in CI.

Bazable ships end-to-end Postman support. You can generate a **Postman Collection v2.1** from your contract, run it against a live API or the built-in mock server with **Newman**, and wire the same run into CI. Every new flag is additive and backward compatible: your existing OpenAPI, `serve`, `test`, and `ci` workflows keep working unchanged.

## What you get

<CardGroup cols={2}>
  <Card title="Collection generation" icon="file-export" href="/commands/export">
    `bazable export --postman` builds a v2.1 collection with realistic example bodies and status/schema test scripts.
  </Card>

  <Card title="Live testing with Newman" icon="vial" href="/commands/test">
    `bazable test --newman` generates a temporary collection and runs it through Newman with any reporters you choose.
  </Card>

  <Card title="Mock verification" icon="server" href="/commands/serve">
    `bazable serve --verify` starts the mock server, then runs Newman against it to catch drift between mock and contract.
  </Card>

  <Card title="CI workflow" icon="github" href="/commands/ci">
    `bazable ci --newman` appends a Newman step to the generated GitHub Actions workflow.
  </Card>
</CardGroup>

## Requirements

<Steps>
  <Step title="A Bazable contract">
    Any `bazable.config.json` with one or more endpoints. Generate one with [`bazable init`](/commands/init) and [`bazable extract`](/commands/extract) if you don't have one yet.
  </Step>

  <Step title="Newman (optional)">
    Install globally for faster runs:

    ```bash theme={null}
    npm install -g newman
    ```

    If Newman isn't installed, Bazable automatically falls back to `npx newman`.
  </Step>
</Steps>

## Collection contents

Exported collections include:

* One request per endpoint in your contract.
* Pre-generated example request bodies with realistic values (via Faker).
* Test scripts that assert:
  * Response status code is in the 2xx range.
  * If a response schema is defined, each field exists and has the expected type.

## Generate a Postman collection

<CodeGroup>
  ```bash Shorthand theme={null}
  bazable export --postman -o postman.json
  ```

  ```bash Explicit format theme={null}
  bazable export --format postman -o postman.json
  ```
</CodeGroup>

Open `postman.json` in Postman (**File → Import**) or ship it with your repo so teammates can hit your endpoints without any setup.

## Test with Newman

[`bazable test --newman`](/commands/test) reads your contract, generates a Postman collection in memory, and runs `newman run` against it.

<CodeGroup>
  ```bash Default reporter theme={null}
  bazable test --newman
  ```

  ```bash Multiple reporters theme={null}
  bazable test --newman --reporter cli,junit
  ```

  ```bash Pass env vars theme={null}
  bazable test --newman --env-var TOKEN=abc123 --env-var API_BASE=https://api.example.com
  ```
</CodeGroup>

<Note>
  If you have stored credentials from [`bazable login`](/cloud/login), the token is injected as the `token` environment variable in the Newman run.
</Note>

Exit codes: `0` when all tests pass, `1` otherwise.

## Verify the mock server

[`bazable serve --verify`](/commands/serve) boots the mock server on your `--port` (default `4000`) and immediately runs Newman against every endpoint. It's the fastest way to catch a mock/contract mismatch before pushing.

```bash theme={null}
bazable serve --verify
```

## Generate backend stubs with a collection

[`bazable gen backend --postman`](/commands/generate) writes a `postman_collection.json` next to your router stubs so you can hit the generated server immediately.

<CodeGroup>
  ```bash Express + collection theme={null}
  bazable gen backend --framework express --postman
  ```

  ```bash Hono + test instructions theme={null}
  bazable gen backend --framework hono --postman --test
  ```
</CodeGroup>

`--test` prints the exact `newman run` command to execute against the running stub server.

## End-to-end workflow

<Steps>
  <Step title="Generate backend stubs and a collection">
    ```bash theme={null}
    bazable gen backend --framework express --postman
    ```
  </Step>

  <Step title="Start the mock server">
    ```bash theme={null}
    bazable serve --port 3000 &
    ```
  </Step>

  <Step title="Verify the mock">
    ```bash theme={null}
    bazable serve --verify
    # or directly
    newman run postman_collection.json
    ```
  </Step>

  <Step title="Export for external tools">
    ```bash theme={null}
    bazable export --postman -o postman.json
    ```
  </Step>

  <Step title="Run in CI against a real deployment">
    ```bash theme={null}
    bazable test --newman --env-var API_BASE=https://api.example.com
    ```
  </Step>
</Steps>

## CI setup

Generate a GitHub Actions workflow that exports a collection and runs Newman on every pull request:

```bash theme={null}
bazable ci --newman
```

The generated `.github/workflows/bazable.yml` appends:

```yaml theme={null}
- name: Export Postman collection
  run: bazable export --postman -o postman_collection.json

- name: Run Postman collection with Newman
  run: npx newman run postman_collection.json --reporters cli,junit
```

See [`bazable ci`](/commands/ci) for the full workflow shape.

## Security

Bazable is defensive by default:

* All URLs are validated with `isUrlAllowed` (only `http`/`https`).
* Environment variables passed to Newman are sanitized to prevent injection.
* All subprocesses are spawned without a shell (`spawnSafe`), so nothing you pass is interpreted by a parent shell.

## Related

<CardGroup cols={2}>
  <Card title="bazable export" icon="file-export" href="/commands/export">
    OpenAPI and Postman export flags.
  </Card>

  <Card title="bazable test" icon="vial" href="/commands/test">
    Direct HTTP tests and Newman mode.
  </Card>

  <Card title="bazable serve" icon="server" href="/commands/serve">
    Mock server and `--verify` mode.
  </Card>

  <Card title="bazable ci" icon="github" href="/commands/ci">
    GitHub Actions with a Newman step.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.