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

Collection generation

bazable export --postman builds a v2.1 collection with realistic example bodies and status/schema test scripts.

Live testing with Newman

bazable test --newman generates a temporary collection and runs it through Newman with any reporters you choose.

Mock verification

bazable serve --verify starts the mock server, then runs Newman against it to catch drift between mock and contract.

CI workflow

bazable ci --newman appends a Newman step to the generated GitHub Actions workflow.

Requirements

1. A Bazable contract

   Any bazable.config.json with one or more endpoints. Generate one with bazable init and bazable extract if you don’t have one yet.

2. Newman (optional)

   Install globally for faster runs:

   npm install -g newman
   

   If Newman isn’t installed, Bazable automatically falls back to npx newman.

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

Shorthand

bazable export --postman -o postman.json

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 reads your contract, generates a Postman collection in memory, and runs newman run against it.

Default reporter

bazable test --newman

If you have stored credentials from bazable login, the token is injected as the token environment variable in the Newman run.

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

Verify the mock server

bazable serve --verify 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.

bazable serve --verify

Generate backend stubs with a collection

bazable gen backend --postman writes a postman_collection.json next to your router stubs so you can hit the generated server immediately.

Express + collection

bazable gen backend --framework express --postman

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

End-to-end workflow

1. Generate backend stubs and a collection

   bazable gen backend --framework express --postman
   
2. Start the mock server

   bazable serve --port 3000 &
   
3. Verify the mock

   bazable serve --verify
   # or directly
   newman run postman_collection.json
   
4. Export for external tools

   bazable export --postman -o postman.json
   
5. Run in CI against a real deployment

   bazable test --newman --env-var API_BASE=https://api.example.com
   

CI setup

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

bazable ci --newman

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

- 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 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

bazable export

OpenAPI and Postman export flags.

bazable test

Direct HTTP tests and Newman mode.

bazable serve

Mock server and --verify mode.

bazable ci

GitHub Actions with a Newman step.