Configuration

Portman config

Structure of the portman-config file and how to target OpenAPI operations with operationIds, method and path, wildcards and exclusions.

The Portman config file (portman-config.json or .yaml, passed with -c) tells Portman which tests to inject, which variables to assign, which request data to overwrite and which scripts to add. Every section targets OpenAPI operations by operationId or by method and path.

Top-level structure

Property	Description
`version`	The Portman configuration version.
`tests`	Definitions for generated tests. Contains `contractTests`, `contentTests`, `variationTests`, `integrationTests` and `extendTests`.
`assignVariables`	Set Postman collection variables for easier automation. See Assign variables.
`overwrites`	Custom additions or modifications of request data. See Overwrites.
`operationPreRequestScripts`	Postman pre-request scripts per request. See Pre-request scripts.
`globals`	Customizations that apply to the whole collection. See Globals.

Inside tests:

Property	Description
`contractTests`	Autogenerated contract tests.
`contentTests`	Tests that check response content.
`variationTests`	Extra request variations, including fuzzing.
`integrationTests`	Integration tests. Each has a `name` (the folder generated in the Integration Tests folder) and `operations` (the operations to perform).
`extendTests`	Your own Postman test scripts.

A minimal config:

json

{  "version": 1.0,  "tests": {    "contractTests": [      {        "openApiOperation": "*::/crm/*",        "statusSuccess": {          "enabled": true        }      }    ]  },  "globals": {    "stripResponseExamples": true  }}

The same file in YAML:

yaml

version: 1tests:  contractTests:    - openApiOperation: '*::/crm/*'      statusSuccess:        enabled: trueglobals:  stripResponseExamples: true

Targeting operations

Each entry in contractTests, contentTests, variationTests, extendTests, assignVariables, overwrites and operationPreRequestScripts uses one of these targets:

Target	Type	Example
`openApiOperationId`	string	`leadsAll`
`openApiOperationIds`	array	`["leadsAll", "companiesAll", "contactsAll"]`
`openApiOperation`	string	`GET::/crm/leads`
`excludeForOperations`	array	`["leadsAdd", "GET::/crm/leads/{id}"]`

openApiOperationId is optional in OpenAPI. For documents without operationIds, use openApiOperation: the unique combination of method and path, separated by ::.

excludeForOperations skips operations for that entry. It accepts both the operationId and the openApiOperation format, and is most useful together with wildcards.

Wildcards

openApiOperation supports wildcards for the method and the path. Always put quotes around the target.

Pattern	Matches
`"GET::/crm/leads"`	Only `GET` on `/crm/leads`.
`"*::/crm/leads"`	All methods (get, put, post, delete, options, head, patch, trace) on `/crm/leads`.
`"GET::/crm/*"`	`GET` on any path below `/crm`, like `/crm/companies` and `/crm/leads`.
`"::/crm/"`	All methods on any path below `/crm`.

Example: a response time check on every CRM operation except two:

json

{  "openApiOperation": "*::/crm/*",  "excludeForOperations": ["leadsAdd", "GET::/crm/leads/{id}"],  "responseTime": {    "enabled": true,    "maxMs": 300  }}

Splitting the config with $ref

You can split a large configuration into multiple files, or reuse parts across setups, with $ref. A reference points to a local or remote JSON or YAML file plus the path to the definition:

json

{  "version": 1.0,  "tests": {    "contractTests": {      "$ref": "./examples/config-references/definitions/test-contracts.json#/contractTests"    }  },  "globals": {    "$ref": "https://raw.githubusercontent.com/apideck-libraries/portman/main/examples/config-references/definitions/globals.json#/globals"  }}

Editor support

YAML configs in the Portman examples start with a $schema reference to the Portman config JSON schema, which gives you validation and autocompletion in editors that support it:

yaml

$schema: https://raw.githubusercontent.com/apideck-libraries/portman/main/src/utils/portman-config-schema.jsonversion: 1

Source: Portman README

Postman sync

Contract tests