Automate API tests and Debug in Docker with Postman’s Newman

This post was co-written by Joyce Lin, Head of Developer Relations at Postman.

Over 20 million developers use the Postman API platform, and its Collections feature is a standout within the community. At its core, a collection is a group of API calls. 

While not all collections evolve into anything more complex, many are foundational building blocks for Postman’s more advanced features. For example, a collection can contain API tests and documentation, inform mock servers, or represent a sequence of API calls.

Storing API requests in a collection lets users explore, run, and share their work with others. We’ll explain why that matters and how you can start using Postman’s Newman Docker extension.

Why run a Postman collection in Docker Desktop?

Since a collection is a sequence of API calls, it can represent any API workflow imaginable. For example, here are some use cases for running collections during development: 

• Automation – Automate API testing to run tests locally
• Status checks – Run collections to assess the current status and health of your API
• Debugging – Log test results and filter by test failures to debug unexpected API behavior
• Execution – Run collections to execute an API workflow against different environment configurations

For each use case, you may want to run collections in different scenarios. Here are some scenarios involving API test automation: 

• Testing locally during development
• Testing as part of a CI/CD pipeline
• Testing based on an event trigger
• Health checking on a predetermined schedule

And you can run collections in several ways. One method leverages Newman — Postman’s open-source library — with Docker. You can use Newman from your command line or with functions, scripts, and containerized applications. You can even run your collection from Docker Desktop!

Getting started with Newman in Docker Desktop

The Postman Docker Extension uses Postman’s Newman image to run a collection and display the results. In this section, we’ll test drive the extension and run our first collection.

Setting up

1. Install the latest version of Docker Desktop. Install the Newman extension for Docker Desktop.
2. Sign up for a free Postman account and generate an API key. This will let you access your Postman data like collections and environments.
3. Log into your Postman account and create a Postman collection. If you don’t have a Postman collection yet, you can fork this sample collection to your own workspace. Afterwards, this forked collection will appear as your own collection.

Running a Postman collection

1. Enter your Postman API key and click “Get Postman Collections.”

2. Choose which collection you want to run.

3. (Optional) Select an environment to run alongside your collection. In a Postman environment, you can define different server configurations and credentials corresponding to each server environment.

4. Click “Run Collection” and review the results of your API calls. You can filter by failed tests and drill down into the details.

5. Repeat this process with other collections and environments as needed.

Contribute to this extension or make your own

This extension is an open source, community project, so feel free to contribute your ideas. Or you can fork it and make it your own. Give Newman a try by visiting Docker Hub and opening the extension within Docker Desktop. You can also install Newman directly within Docker Desktop’s Extensions Marketplace. 

Want to experiment even further? You can bring your own ideas to life via our Extensions SDK GitHub page. Here you’ll find useful code samples to kickstart your next project. 

Special thanks from Joyce to Postman for supporting open-source projects like Newman, empowering the community to build integrations, and to Software Development Engineer in Test (SDET) Danny Dainton for his UI work around collection run results.