# Portman

> Portman is an open-source (Apache 2.0) CLI by Apideck that converts an OpenAPI 3.x document into a Postman collection, injects contract tests (status code, content-type, JSON body, JSON Schema validation, headers, response time), content tests, variation tests and fuzzing tests, and runs them with Newman. It exits with code 1 when any assertion fails, so it works as a CI gate against API contract drift.

Quick start: `npx @apideck/portman -l openapi.yaml --runNewman -b http://localhost:3000`

## Getting started

- [Introduction](https://getportman.com/docs): Portman is an open-source CLI that converts an OpenAPI spec into a Postman collection with contract tests and runs it with Newman.
- [Installation](https://getportman.com/docs/installation): Install the Portman CLI locally in your project, globally with npm, or run it without installing using npx.
- [Quickstart](https://getportman.com/docs/quickstart): Generate your first Postman collection with contract tests from an OpenAPI spec, then run it against your API with Newman.

## CLI

- [CLI options](https://getportman.com/docs/cli-options): Every Portman CLI flag, with aliases, types and defaults, plus common command examples for converting specs and running tests.
- [CLI options file](https://getportman.com/docs/cli-options-file): Store all Portman CLI options in a JSON or YAML file and pass it with --cliOptionsFile, ideal for versioned CI/CD setups.
- [Environment variables](https://getportman.com/docs/environment-variables): Expose environment variables prefixed with PORTMAN_ as camelCase Postman variables, from your shell or a spec-specific .env file.
- [Running tests with Newman](https://getportman.com/docs/newman): Run the generated Postman collection with Newman from Portman, override the base URL, add iteration data and pass Newman options.
- [Postman sync](https://getportman.com/docs/postman-sync): Upload the generated collection to your Postman workspace with --syncPostman, using a Postman API key, collection UID and workspace name.

## Configuration

- [Portman config](https://getportman.com/docs/portman-config): Structure of the portman-config file and how to target OpenAPI operations with operationIds, method and path, wildcards and exclusions.
- [Contract tests](https://getportman.com/docs/contract-tests): Generate Postman contract tests from OpenAPI that check status codes, content type, JSON body, JSON schema, headers and response time.
- [Variation tests](https://getportman.com/docs/variation-tests): Add extra Postman requests per operation with changed inputs to test happy-path variants and expected 4xx/5xx error responses.
- [Content tests](https://getportman.com/docs/content-tests): Assert specific values in API response bodies and headers with Portman contentTests, using value, contains, oneOf, length and assert checks.
- [Extend tests](https://getportman.com/docs/extend-tests): Add your own Postman test scripts to generated requests with Portman extendTests, inline or from files, appended or prepended.
- [Assign variables](https://getportman.com/docs/assign-variables): Capture values from responses, headers or request bodies into Postman collection variables to chain requests in Portman.
- [Overwrites](https://getportman.com/docs/overwrites): Change Postman request data generated from OpenAPI with Portman overwrites for body, query params, path variables, headers, base URL and auth.
- [Fuzzing](https://getportman.com/docs/fuzzing): Generate fuzzed Postman requests from OpenAPI constraints to trigger and contract-test your API's validation and error responses.
- [Pre-request scripts](https://getportman.com/docs/pre-request-scripts): Inject Postman pre-request scripts on specific operations with operationPreRequestScripts, inline or loaded from a JavaScript file.
- [Globals](https://getportman.com/docs/globals): Collection-wide Portman settings for variables, scripts, search and replace, request ordering, variable casing and authorization.

## Guides

- [Run Portman in GitHub Actions](https://getportman.com/docs/ci-github-actions): Run Portman contract tests in a GitHub Actions workflow with npx, a CLI options file, secrets as PORTMAN_ variables and Newman.
- [Filtering operations](https://getportman.com/docs/filtering-operations): Limit which OpenAPI operations Portman converts and tests using an openapi-format filter file with tags, methods, operationIds and flags.
- [Output](https://getportman.com/docs/output): Where Portman writes the generated Postman collection, how to set the output path, and how to save the filtered OpenAPI document.

## Reference

- [FAQ](https://getportman.com/docs/faq): Answers to common Portman questions about Postman accounts, OpenAPI versions, config formats, missing operationIds, Newman and CI usage.
- [Troubleshooting](https://getportman.com/docs/troubleshooting): Fixes for common Portman issues, including redirect tests, unknown schema formats, Postman sync errors, circular refs and config changes.
- [Ecosystem](https://getportman.com/docs/ecosystem): Open-source tools from the Portman maintainers that complete the workflow: Inspectr, openapi-format and postman-to-k6.

## Templates

- [Baseline contract tests](https://getportman.com/docs/templates/baseline-contract-tests): Start contract testing every operation in your spec with one rule.
- [Strict response validation](https://getportman.com/docs/templates/strict-response-validation): Catch undocumented response fields, wrong content types and missing headers.
- [Response time budget](https://getportman.com/docs/templates/performance-budget): Fail the run when endpoints respond slower than an agreed budget.
- [Auth token chaining](https://getportman.com/docs/templates/auth-token-chaining): Get an access token from a token endpoint and use it for every other request.
- [CRUD flow chaining](https://getportman.com/docs/templates/crud-flow-chaining): Create a record, then read, update and delete that same record.
- [Negative testing with variations](https://getportman.com/docs/templates/negative-testing): Verify that bad credentials and invalid input return the documented 4xx errors.
- [Fuzz create and update requests](https://getportman.com/docs/templates/fuzzing): Automatically probe validation with missing fields and out-of-range values.
- [Response content assertions](https://getportman.com/docs/templates/content-assertions): Check that responses contain specific values, not just the right shape.
- [Read-only smoke tests](https://getportman.com/docs/templates/targeted-subset): Test only safe GET operations, for example against production.
- [Pre-request script setup](https://getportman.com/docs/templates/pre-request-setup): Prepare dynamic data before requests run, from iteration data or computed values.

## Comparisons

- [Portman vs Schemathesis](https://getportman.com/compare/portman-vs-schemathesis): Pick Schemathesis when you want property-based testing that generates many inputs per operation, including negative and stateful sequences, from an OpenAPI or GraphQL schema. Pick Portman when you want a deterministic, reviewable Postman collection of contract tests that runs with Newman in CI and can be synced to Postman. The two answer different questions and can run side by side.
- [Portman vs Specmatic](https://getportman.com/compare/portman-vs-specmatic): Pick Specmatic when you want one tool to turn API specs (OpenAPI, AsyncAPI, gRPC, GraphQL and more) into contract tests, mocks for consumers and backward-compatibility checks, including an MCP server for coding agents. Pick Portman when your workflow is built around Postman and Newman and you want the spec turned into an editable Postman collection with contract, content and variation tests.
- [Portman vs Pact and PactFlow](https://getportman.com/compare/portman-vs-pactflow): Pick Pact (and PactFlow) when you need consumer-driven contracts: consumers record what they use, and providers are checked against it before deploy with can-i-deploy. Pick Portman when you want to test that a running API matches its own OpenAPI spec. They fit together: PactFlow’s bi-directional contract testing accepts Postman/Newman results as provider verification evidence.
- [Postman’s OpenAPI import vs Portman](https://getportman.com/compare/portman-vs-postman): Postman can generate a collection from an OpenAPI spec with folders, requests and response examples, and keep it in sync; tests are added by hand or with Agent Mode. Portman builds on the same converter (openapi-to-postman) and Newman, and adds generated contract, content and variation tests from a config file in CI. Use Postman’s import for exploring and documenting an API, and Portman when you want the tests generated and run from the spec.
- [A maintained Dredd alternative](https://getportman.com/compare/dredd-alternative): Dredd’s repository was archived on 8 November 2024 and its last release (14.1.0) dates from November 2021, so it no longer receives fixes. If you validate an API against its OpenAPI 3 description in CI, Portman covers the same job, adds response-time limits, content tests and variation tests, and is actively maintained. If you rely on API Blueprint, Portman is not a drop-in replacement because it only reads OpenAPI 3.0 and 3.1.
- [A Step CI alternative for OpenAPI contract testing](https://getportman.com/compare/step-ci-alternative): Step CI is not archived, but its repository has had no commits since August 2024 and its last release (2.8.2) was in June 2024. If your main use is checking a REST API against its OpenAPI spec in CI, Portman generates those tests from the spec and is actively maintained. If you rely on Step CI’s multi-protocol workflows (GraphQL, gRPC, tRPC, SOAP) or load testing, Portman does not cover them.

## Optional

- [Full documentation in one file](https://getportman.com/llms-full.txt)
- [GitHub repository](https://github.com/apideck-libraries/portman)
- [npm package](https://www.npmjs.com/package/@apideck/portman)
- Agent skill: `npx skills add apideck/api-skills --skill apideck-portman`