[opensourcedex]

portman is a free, open source api development & testing project written in TypeScript and released under Apache-2.0. It has 685 GitHub stars, 62 forks and 56 open issues, and was last pushed 9 days ago. On this registry it ranks #96 of 103 tracked projects in API Development & Testing, with 5 head-to-head comparisons available.

What is portman?

What it is

Portman is a TypeScript command-line tool that ports an OpenAPI document into a Postman collection. It reads the request and response properties defined in an OpenAPI specification and uses them to build the collection, then injects contract and variation tests into the generated requests with a minimum of configuration. The project lives in the API development and testing ecosystem, bridging the contract-first OpenAPI world and the Postman collection format. It is published under the Apache-2.0 license, carries 685 stars and 62 forks, and its repository is five years old with 56 open issues.

The concrete problem it solves is the manual gap between a specification and a runnable test collection. Instead of hand-writing a Postman request for every method-and-endpoint combination defined in a spec, and hand-writing the assertions that check the response against the contract, Portman generates both. It supports OpenAPI 3.0 and OpenAPI 3.1, produces one request per method and endpoint combination, and attaches a set of contract tests to each. The generated collection can then be uploaded to Postman or executed through Newman, and the whole flow can be driven from a configuration file so it fits into a CI/CD pipeline as one CLI invocation.

Key capabilities

  • Converts an OpenAPI document into a Postman collection, with support for both OpenAPI 3.0 and OpenAPI 3.1.
  • Injects Postman contract tests derived from the request and response properties in the specification.
  • Injects variation tests and integration tests into the collection.
  • Injects pre-request and test scripts at either the collection level or the operation level.
  • Modifies Postman requests through overwrite and assign-overwrite configuration.
  • Fuzzes Postman requests.
  • Uploads the resulting collection to the Postman app and runs it with Newman.
  • Splits configuration across multiple files using $ref and manages all options in a JSON or YAML config file.

Who uses it and how

  • API teams running contract-first workflows, keeping Postman collections aligned with the OpenAPI document that defines them.
  • CI/CD pipelines that install the Portman CLI, generate the collection, and execute the tests through Newman on every change.
  • Developers seeding a test suite on an existing spec: running Portman with no explicit configuration produces a collection with contract tests and mirrors the default contract-tests configuration file.
  • Test authors extending generated collections with variation, integration, and fuzzing tests, plus custom pre-request and test scripts.
  • Teams that keep environment variables in a .env file, copied from .env.example, and customize the ___.default.json config files in the root directory.

Getting started

Run the CLI without installing globally through `npx portman

project readme (upstream, from github) — read inline

portman-hero

Total Downloads Latest Stable Version Total Downloads

Portman 👨🏽‍🚀

Port OpenAPI Spec to Postman Collection, with contract & variation tests included!

Portman leverages OpenAPI documents, with all its defined API request/response properties, to power your Postman collection. Let Portman do all the work and inject contract & variation tests with a minimum of configuration. Customize the Postman requests & variables with a wide range of options to assign & overwrite variables.

[!IMPORTANT]
Important Change: If you are using version 1.28.0 with a custom Postman config file specified by the --postmanConfigFile flag, please ensure that the parametersResolution option is set to either "Example" or "Schema". The options requestParametersResolution and exampleParametersResolution are deprecated openapi-to-postman options.

Why use Portman?

Convert your OpenAPI spec to Postman, generate contract & variation tests, upload the Postman collection & run the tests through Newman. Include the Portman CLI as part of an automated process for injecting the power of Portman directly into your CI/CD pipeline.

Read the full blog post

Features

With Portman, you can:

  • Convert an OpenAPI document to a Postman collection
    • Support for OpenAPI 3.0
    • Support for OpenAPI 3.1
  • Extend the Postman collection with capabilities
    • Inject Postman Contract Tests - learn more
    • Assign collection variables - learn more
    • Inject Postman Variation Tests - learn more
    • Inject Postman Integration Tests
    • Inject Postman with Pre-request & Tests scripts on a collection or operation level - learn more
    • Modify Postman requests - learn more here and here
    • Fuzz Postman requests - learn more
  • Upload the Postman collection to your Postman app - learn more
  • Test the Postman collection with Newman - learn more
  • Split the configuration into multiple files using $ref
  • Manage everything in config file for easy local or CI/CD usage - learn more

Getting started

  1. Install Portman
  2. Initialize Portman CLI configuration by running: $ portman --init

OR

  1. Install Portman
  2. Copy .env.example to .env and add environment variables you need available to your collection
  3. Copy/rename and customize each of the ____.default.json config files in the root directory to suit your needs
  4. Start converting your OpenAPI document to Postman

OR

If you have an existing OpenAPI specification, try running Portman without any special setup to see how it can generate a Postman collection with contract tests with it's default configuration.

  1. Install Portman
  2. Run portman on your OpenAPI spec, ie:
  • npx portman -l my-openapi-spec.yaml
  • (if your spec is hosted use the -u parameter, ie:
    • npx portman -u https://petstore3.swagger.io/api/v3/openapi.json

This will generate a postman collection that contains a request for every method:endpoint combination defined in your spec, and include a set of "Contract Tests" for each one. You can learn more about contract tests, and how to examine the generated collection here.

(Running portman with no explicit configuration is the same as running it with this configuration file)

All configuration options to convert from OpenAPI to Postman can be found in the openapi-to-postman package documentation. All configuration options to filter flags/tags/methods/operations/... from OpenAPI can be found in the openapi-format package documentation or using the online openapi-format playground.

Installation

Local Installation (recommended)

You can add the Portman CLI to the node_modules by using:

$ npm install --save @apideck/portman

or using yarn:

$ yarn add @apideck/portman

Note that this will require you to run the Portman CLI with npx @apideck/portman -l your-openapi-file.yaml or, if you are using an older version of npm, ./node_modules/.bin/portman -l your-openapi-file.yaml.

Global Installation

$ npm install -g @apideck/portman

NPX usage

To execute the CLI without installing it via npm, use the npx method.

$ npx @apideck/portman -l your-openapi-file.yaml

CLI Usage

Usage: -u  -l  -b  -t 

Options:
 --help                     Show help                                                                        [boolean]
 --version                  Show version number                                                              [boolean]
 --url,-u                   URL of OAS to port to Postman collection                                         [string]
 --local, -l                Use local OAS to port to Postman collection                                      [string]
 --baseUrl, -b              Override spec baseUrl to use in Postman                                          [string]
 --output, -o               Write the Postman collection to an output file                                   [string]
 --oaOutput                 Write the (filtered) OpenAPI file to an output file                              [string]
 --runNewman, -n            Run Newman on newly created collection                                           [boolean]
 --newmanRunOptions         JSON stringified object to pass options for configuring Newman                   [string]
 --newmanOptionsFile        Path/URL to Newman options file to pass options for configuring Newman           [string]
 --newmanIterationData, -d  Iteration data to run Newman with newly created collection                       [string]
 --localPostman             Use local Postman collection, skips OpenAPI conversion                           [string]
 --syncPostman              Upload generated collection to Postman (default: false)                          [boolean]
 --syncPostmanCollectionIds Synchronises the IDs of newly created postman collections with those already
                            on Postman, useful when you want to use Postman pull request (default: false)    [boolean]
 --postmanFastSync          Postman sync creates new collection (new UID),instead of update (default: false) [boolean]
 --postmanRefreshCache      Postman sync will refresh all local cached Postman API data (default: false)     [boolean]
 --postmanUid, -p           Postman collection UID to upload with the generated Postman collection           [string]
 --postmanWorkspaceName     Postman Workspace name to target the upload of the generated Postman collection  [string]
 --includeTests, -t         Inject Portman test suite (default: true)                                        [boolean]
 --bundleContractTests      Bundle Portman contract tests in a separate folder in Postman (default: false)   [boolean]
 --portmanConfigFile, -c    Path/URL to Portman settings config file (portman-config.json)                   [string]
 --postmanConfigFile,-s     Path to openapi-to-postman config file (postman-config.json)                     [string]
 --filterFile               Path/URL to openapi-format config file (oas-format-filter.json)                  [string]
 --envFile                  Path to the .env file to inject environment variables                            [string]
 --collectionName           Overwrite OpenAPI title to set the Postman collection name                       [string]
 --cliOptionsFile           Path/URL to Portman CLI options file                                             [string]
 --ignoreCircularRefs       Ignore circular references in OpenAPI spec (default: false)

readme truncated — read the full docs on github

Frequently asked questions

Is portman free to use?

portman is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does portman do?

Port OpenAPI Specs to Postman Collections, inject test suite and run via Newman 👨🏽‍🚀

What is portman written in?

portman is primarily written in TypeScript. Its source is publicly available at https://github.com/apideck-libraries/portman, and it has 685 GitHub stars.