# Test your API contracts with Portman

Portman is Apideck’s open-source tool for turning an OpenAPI specification into a Postman collection with automated tests. Use it when an exploratory request in the API Explorer needs to become a repeatable check.

[Portman website](https://www.getportman.com/) · [GitHub repository](https://github.com/apideck-libraries/portman) · [Configuration examples](https://github.com/apideck-libraries/portman/tree/main/examples)

## Where it fits

| Tool | Use it for |
| --- | --- |
| [API Explorer](/api-explorer) | Inspect one request and response while developing an integration. |
| Portman | Generate requests and assertions from the API contract, customize test inputs, and keep the collection reproducible. |
| Postman or Newman | Execute the generated collection interactively or in an automated test run. |
| [API Logs](/logs) | Investigate what Apideck and the downstream connector actually exchanged. |

## Generate your first collection

Download the API’s OpenAPI specification from its reference page. For Accounting, generate a local collection with:

```bash
npx @apideck/portman \
  --url https://specs.apideck.com/accounting.yml \
  --output accounting.postman.json
```

This command generates the collection; it does not execute its API requests. Import `accounting.postman.json` into Postman to inspect the requests and generated tests.

Before running a request, configure its authorization and Apideck application, consumer and service headers. Choose a test connection with records that you can safely create, change or delete: a generated collection can include write operations.

## Make the tests useful for your integration

Start with one workflow, such as reading invoices from your test company. Check both the response structure and the values your application depends on. A valid schema alone does not establish that an invoice has the right currency, customer or balance.

Portman supports contract assertions, custom content checks, variation tests and integration-test sequences. Its configuration can assign variables and override request inputs. Use the [repository examples](https://github.com/apideck-libraries/portman/tree/main/examples) to target the operations you need, then commit the specification and configuration alongside your integration.

Test each supported connector against its actual [coverage](/apis/accounting/coverage). A shared schema does not imply identical connector capabilities.

## Run in CI

After reviewing the requests and setting up test data, use Newman to run the collection. Portman also exposes `--runNewman` and Newman configuration options; the [CLI reference](https://github.com/apideck-libraries/portman#cli-usage) documents them.

Keep credentials in your CI secret store. Pin the tool version and specification revision for reproducible runs. Include fixture setup and cleanup for write tests, and retain failed assertions with the request ID so you can follow up in [Logs](/logs).