The Reimagined API-First Workflow, Part 2: for Testers

Abhijit Kane

November 29, 2021· 5 mins

API testing has been a key part of Postman’s value proposition from day one. And with the new Postman API Platform, our testing abilities have gotten a major boost with features that help address a stronger focus on API quality. Postman Collections (representing documentation, mock servers, and test suites) are synchronized with the repository. This means that API-first testing based on Postman Collections is possible without going out of Postman’s workflow, while also relying on the CI/CD tools that you’re already used to.

In this post, we’ll use a combination of Postman’s collection runner, command-line companion (Newman), and CI/CD tools to add a layer of testing to our “Hello API-first world” API created in the last post.

Let’s set up the test workflow and the integration with CircleCI:

1. Head over to the Test tab of any of your API’s versions: this is where most of your test workflows will live. Ensure there are test collections added to the API. Powerful scripting and asynchronous capabilities let you test many aspects of an API’s behavior. If you want to ensure the correct message is returned each time, here’s how you might assert that in a request:
   
2. These tests can be executed in Postman against an environment of your choice—perhaps local for the developer or beta for the QA team. With Postman v9, there’s a single Test interface where you can add collections and view recent collection run results.
   
3. If you add API tests in a new collection, make sure you add it to the API and push to the underlying repository. Adding the collection can be done via the Add Test link in the test tab.
   
4. You can use Newman in your CI system to ensure that the tests are run with every push to the repo. If you’ve set up the integration with Git as described in part 1, you’ll find the test collections in the /postman/collections directory in your repository. You can reference the collections directly from the repository tree—this enables you to test APIs across branches and aligns with the branching support that Postman provides.
   
5. The integrations with CircleCI and TravisCI let you view the status of your pipelines right in Postman. You can view builds and their status across branches, and even trigger builds from Postman. In our example, we set up a CircleCI pipeline for our project. This is what the last few runs of the pipeline look like (you can spot Newman executing our tests collection, as well as some unit tests we added):
   
6. To set up the integration:
   1. Head over to the Test tab for the API version, and select the CI/CD tool you use. In this example, we’ve used CircleCI.
   2. Enter your personal access token. For CircleCI, https://circleci.com/docs/2.0/managing-api-tokens/ describes how you can generate a token. This is what Postman uses to pull relevant data. Set a nickname that helps you identify your integration, and the project that you want to show builds for.
   3. You’ll see a list of recent builds, with the branch they ran on.
   4. Use the Run Build link to trigger a build on a specific branch. This can be done by developers when collections are updated in Postman. If you’re using the new Git integration described earlier, the pipeline will run automatically when code is pushed, or collections are updated and pushed.

This workflow helps to visualize build health as a property of the API. Links to CI/CD projects, which might be spread across wiki pages or internal documentation are now consolidated under one API construct, with easy navigation to the source code and interfaces that define the API.

Once the test workbench is set up, making changes to the API’s interface might involve the following steps:

1. Switch to a “feature” branch for a change you want to make to the implementation. The interface change would have been made on the develop branch using Postman’s real-time collaboration capabilities.
2. Update your code in an IDE. Postman can be used during development to debug individual endpoints.
3. Use Postman to switch to the relevant branch and update the test collections as required.
   
4. You can use Postman’s collection runner to execute tests against the local application.
5. Commit and push the source code and the updated collection to the repository.
6. On the develop branch, you’ll see the CI builds reflect the status for the branch you pushed.
   
7. Once implementation is complete and the pull request is merged, the develop branch will have the code and updated test collections.

We’re working to add support for other CI providers as well, and we’d love to know what your API-first testing workflow looks like and how Postman can help. Reach out with a comment below. You can also give product feedback through our Community forum and GitHub repository.

Try Postman now