Introduction
Portman is an open-source CLI that converts an OpenAPI spec into a Postman collection with contract tests and runs it with Newman.
Portman is an open-source command-line tool by Apideck that converts an OpenAPI document into a Postman collection and injects contract tests, variation tests and other test scripts based on that document. It can then upload the collection to Postman and run the tests with Newman, locally or in a CI/CD pipeline.
Why Portman
Your OpenAPI document already describes every request and response your API supports: paths, methods, parameters, status codes, content types and JSON schemas. Portman uses that description to generate the tests for you, so the contract you publish is the contract you test.
- Convert an OpenAPI spec to Postman, generate contract and variation tests, upload the collection to Postman and run the tests through Newman.
- Add the Portman CLI to an automated process to run those tests in your CI/CD pipeline.
- Keep everything in configuration files that work the same way locally and in CI.
Portman started as a pull request on the openapi-to-postman package. Apideck collaborated with the original author, Tim Haselaars, to extend it into Portman.
How it works
- Portman reads your OpenAPI document from a local file (
-l) or a URL (-u). - Optionally, it filters the document (for example to a set of tags or operations) using openapi-format.
- It converts the document to a Postman collection with openapi-to-postman. Each method and path combination becomes a request.
- It applies your Portman configuration: it injects tests, assigns variables, overwrites request data and adds scripts.
- It writes the collection to disk and, if you ask it to, uploads it to Postman and runs it with Newman.
Running Portman without a configuration file generates a request for every operation, each with a default set of contract tests. See Quickstart.
Features
- Convert an OpenAPI document to a Postman collection, with support for OpenAPI 3.0 and OpenAPI 3.1.
- Inject contract tests that check status codes, content types, JSON bodies, JSON schemas, headers and response times.
- Assign collection variables from responses to chain requests together.
- Inject variation tests for happy and unhappy paths.
- Inject integration tests.
- Inject pre-request scripts and test scripts on a collection or operation level.
- Modify Postman requests with overwrites.
- Fuzz Postman requests to trigger validation errors.
- Upload the collection to Postman.
- Run the collection with Newman.
- Split the configuration into multiple files using
$ref. - Manage all CLI options in a config file for local or CI/CD usage.