Introducing the new Postman CLI to automate your API testing

Postman has long been your close companion for API testing, empowering you to feel confident when working with APIs. You can use the Postman API Platform to manually test your APIs and validate if your APIs match your expectations, and even script these manual validations into tests and assertions that you can run using the Postman Collection Runner. Testing is essential whenever there is a change released to production so that you are continuously delivering high-quality APIs and maintaining this quality over time. However, running your API tests manually every time can be cumbersome, prone to human errors, and might often be missed. Automating your testing as part of your continuous integration (CI) and continuous deployment (CD) systems ensures that testing becomes an integral part of your workflows—so you have one less thing to worry about!

Today, we are super excited to announce the release of Postman CLI to help you with automating your API testing.

Introducing Postman CLI

Just like Postman has been your companion for testing your APIs manually, Postman CLI will now be your close companion for automating your API testing. Postman CLI will help you test your APIs from the command-line interface and comes with exciting functionalities such as logging in/logging out, running your collections using simple commands, and running governance and security rules validations for API schemas.

Once you script your commands you can easily run them in CI/CD systems. Moreover, your experience of analyzing and debugging your failed tests will be enhanced because your test results will automatically be posted to Postman.

We understand that working with CLI commands can be difficult and don’t want you to spend your time going through numerous Help pages to figure out the commands. So, we’re introducing some brand-new features with Postman v10 that will help you get your CLI commands with single clicks.

How to use Postman CLI to run your collections locally

You can now easily download Postman CLI, copy your commands, and try running a Postman Collection locally.

Step 1. On the Collection Runner, select Automate runs via CLI and click on Download Postman CLI. Copy the command and paste it into your terminal to start the download and install Postman CLI locally:

Step 2. Generate your Postman API key or Keep your API key handy if you already have one for easy login. You need the API key to log in on Postman CLI so we can authenticate you and authorize you for running your collections:

Step 3. Copy the command from Postman CLI code-gen and Paste it to your terminal:

Step 4. Check the results using the link generated on the terminal. Easily debug your test failures on Postman or view important run metrics such as average response times. You can also quickly run your collection again on Postman:

The above command uses the unique identifier of your collection (collection ID) to run the collection. You can also export your collection file and run the same by mentioning the collection file path in your command as shown below:

postman collection run MyCollections/TestSuites/testsuite1.json

Run your collections in CI/CD

Once you are confident in running your collections locally and have the final command handy, copy these commands and paste them in your CI/CD scripts to make them a part of your workflows. This is a one-time setup that will help you automate your API testing. Now let’s walk through the step-by-step process to do this:

Step 1. Click on Configure Command under the Run in CI/CD Menu:

Step 2. Select configurations such as the postman Environment file to run this with, the Operating System of your CI/CD system, and the CI/CD provider. Copy the generated script:

Step 3. Paste the same into your build or deployment scripts of your CI or CD Provider. As an example, we have pasted this in Bitbucket’s bitbucket-pipelines.yml file for our demo repository:

Step 4. Generate an API key on Postman and put it in the variables section of your CI/CD provider. As an example, we’ve shown you how to do this in Bitbucket:

Step 5. Run a build/deployment pipeline:

Step 6: Check results using the link produced in your build logs:

Note: By default, a test failure will cause your build or deployment to fail. To learn how to suppress this, read more in our Learning Center.

The above steps run the Postman Collection by fetching the live collection from our servers. If you wish to run your collection JSON from your repository, you can do so by exporting your collection, committing it to your repository, and running the collection using its file path.

Once you automate your collection runs in your CI/CD, anytime any build or deployment is done, your collection runs will automatically be triggered. We hope automating your API tests will be even easier so that you can now use your time writing more tests rather than figuring out ways to automate them.

Run your collections with Postman CLI on remote Git branches

With the release of Postman v9, you could integrate your repository and work on remote Git branches directly from Postman. You can now update, add, or remove your tests or assertions in your specific branch and run the tests in your CI/CD systems specific to the changes on this branch.

If you are wondering how this will help you, let’s take a step back and see how you could previously go about automating your tests:

Approach 1: Run your collections using the collection ID

postman run collection my-collection-id

Here, you would fetch your Postman Collections that are saved at our end and run the same in the pipeline. The problem with this approach is that once you update the collection, it will run these updated tests in all your pipeline—dev, beta, stage, prod, and so on. Any failing test would also fail any/all of the CI/CD pipelines that have automation testing integrated.

Approach 2: Export your collection file to Git and run the same

postman run collection /postman/collections/my-collection-file.json

In this approach, you would export your updated collection JSON (containing your tests and assertions) from Postman and save it in your Git repository (such as GitLab, GitHub, Bitbucket, etc.). You would then run your specific branch in CI/CD to test your implementation changes against your API. This approach solves the problem you faced with Approach 1, however it comes with its own challenges such as exporting and importing collections manually each time you need to work on any testing-related changes and making sure you are using the correct collection file in Postman.

How Postman v10 provides new solutions

With Postman v10 we are solving all the above problems. By integrating your Postman APIs with your Git repositories, you can directly work on your branches from Postman and commit changes to these branches directly, thereby eliminating the need to export your Postman Collection. Read more details on how to use the updated Postman API Platform here.

Here are the steps to automate your API testing once you have integrated your Git repository:

Step 1. Once integrated with your Git repository for your Postman Collections on the API Builder, click on Test and Automation:

Step 2. Click on Generate CI Configuration and select the appropriate configuration. Copy the generated script:

Step 3. Paste your snippet in your build configuration file. Make sure to provide your Postman API key as a CI variable. As an example, we have shown the snippet in the Bitbucket Pipelines:

Step 4. Run your builds and check the results:

You can take this further and integrate your build pipelines with Postman. This will ensure all your builds are also reported back to Postman and you have a one-stop shop for all your automation testing and pipeline runs. If you would like to identify why a build failed, you can easily do so by expanding the build information as shown below:

Know more about using CI Integrations with Postman CLI in our Learning Center.

Runs tab: your go-to place for test reports

You now have access to a new tab called Runs available under your collection. This tab will give you all your past collection runs done via Collection Runner or Postman CLI. It will further enable you to view the counts of all, failed, passed, or skipped tests along with metrics such as average response times. You can perform comparisons across different runs/reports by using features such as sorting, filtering, or navigating across pages and looking at old results. If you want to view or analyze a certain report in detail, you can click and view the same as shown below:

Collaborate with your teammates

Postman enables you to collaborate with your teammates while building, testing, and publishing APIs. The run results support collaboration by showing runs done by other team members in your Postman workspace and vice versa. If you want your team member to look at a test that has failed, you can use the shared-link feature to share the report with them. If they’re already part of the workspace, they’ll be able to access the report directly. If not, they will be asked to join the workspace.

We hope you find these new features useful in enabling your test automation journeys.

Sign up here for early access to Postman CLI or schedule a time with a product manager to learn more.