Quickstart

This guide takes you from an OpenAPI document to a Postman collection with contract tests, and then runs those tests against your API with Newman. No configuration file is needed for the first run.

1. Generate a collection from your spec

Point Portman at a local OpenAPI file with -l:

npx @apideck/portman -l my-openapi-spec.yaml

or at a hosted spec with -u:

npx @apideck/portman -u https://petstore3.swagger.io/api/v3/openapi.json

Portman generates a Postman collection with a request for every method and path combination in your spec, and adds a set of contract tests to each request. Without an output location, the collection is written to ./tmp/converted/${specName}.json. Use -o to choose the location:

npx @apideck/portman -l my-openapi-spec.yaml -o ./collection.postman.json

You can import that file into Postman to inspect the requests and the generated tests.

2. Know what the default tests check

Running Portman without a configuration file is the same as running it with this portman-config.json:

{  "version": 1,  "tests": {    "contractTests": [      {        "openApiOperation": "*::/*",        "statusSuccess": {          "enabled": true        },        "contentType": {          "enabled": true        },        "jsonBody": {          "enabled": true        },        "schemaValidation": {          "enabled": true        }      }    ]  }}

For every operation this checks that the response status is 2xx, that the Content-Type header matches the spec, that the body is JSON, and that the body matches the JSON schema from the spec. See Contract tests for all options.

3. Run the tests against your API

Override the server URL from the spec with -b and run the collection with Newman using -n:

npx @apideck/portman -l my-openapi-spec.yaml -b http://localhost:3050 -n true

Newman runs every request and reports which contract tests passed or failed. See Running tests with Newman for Newman options and iteration data.

4. Add your own configuration

Save the default configuration above as portman-config.json, change it, and pass it with -c:

npx @apideck/portman -l my-openapi-spec.yaml -c portman-config.json -b http://localhost:3050 -n true

The configuration file can also be YAML. From here you can add variation tests, chain requests with variables, overwrite request data and more. The templates are ready-made starting points.

Use the interactive setup

Instead of writing files by hand, you can let Portman set them up:

portman --init

The --init option helps you configure the CLI options interactively and puts the default config and env file in place.

Set up from the default files

Alternatively:

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