API testing using Postman and GitHub workflow

Introduction

Ensuring that code changes do not disrupt the current production flow is critical, especially for APIs where the API contract is paramount. A simple, effective, and reusable approach is to leverage existing tools like Postman and GitHub. By capitalising on the efforts made in setting up a Postman collection and its testing scripts—whether by QA, developers, or other team members—we can centralise contract testing in Postman. With the help of GitHub Actions, we can automate API testing runs, seamlessly integrating them into the CI/CD pipeline via the Postman API.

Postman

In Postman, we can create a collection of endpoints and set up testing scripts for each endpoint. Utilising Postbot, an AI tool provided by Postman, we can generate initial test scripts quickly. While these AI-generated scripts provide a good starting point, it is essential to refine them to meet specific business needs.

Example

Using a free API like Chuck Norris Jokes, we can create endpoints in a Postman collection. With Postbot, we generate post-response scripts to test the payload. Running the collection provides immediate feedback on the response payload, allowing for quick validation.

Recap & Potential Next Steps

With the collection and response payload tests in place, we can further enhance our setup by adding environment variables and pre-request scripts, leveraging Postbot to expedite this process.

GitHub 

Postman Integration

To integrate Postman API requests into GitHub Action workflows, we need to retrieve the Postman API Key, Collection ID, and Environment ID, and store them in GitHub secrets/variables.

API Key

The API Key, a Personal Access Token (PAT), can be created in the user settings under API Keys. Note that Postman currently limits users to five PATs.

Collection ID

Select the collection in Postman, click share, and copy the ID.

Environment ID

Go to environments in Postman, select the environment, click share, and copy the ID.

GitHub Environments

These values should be added to the GitHub repository settings under the Environments tab.

After setting it up, the settings related to actions look this way:

After configuring these settings, the relevant actions will reflect these variables. The variables’ names (POSTMAN_COLLECTION_ID and POSTMAN_ENVIRONMENT_ID) remain consistent, ensuring seamless integration within the GitHub Workflow YAML file.

Regarding the API Key, we can use it as a GitHub secret, either as a repo or organisation secret.

YAML usage:

Note: The names of these environment inputs MUST match the GitHub environment variables/secrets names under repository settings.

Workflow

Now, here’s the fun part, the GitHub workflow YAML file.

Here’s a sample GitHub workflow YAML file for API testing using Postman:

name: api-test-postman

on:
  # push:
  #   branches:
  #     - main
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target Environment'
        required: true
        default: 'development'
        type: choice
        options:
        - development
        - staging
        - production
  # uncomment the following lines to run on a schedule
  # schedule: # by default, gets last commit on default branch 
  #   - cron: '0 10 * * 1-5' # At 10:00 UTC on every day-of-week from Monday through Friday

jobs:

  test-api:
    runs-on: ubuntu-latest
    environment:
      name: ${{inputs.environment}}
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v4 # by default, gets last commit on default branch 


      # Install Node on the runner
      - name: Install Node
        uses: actions/setup-node@v4
        with:
          node-version: "20.x"
          # cache: 'npm' # useful when the current repo has a package.json file


      # Install the newman command line utility 
      - name: Install newman
        run: |
          npm install -g newman


      # parse environment response to extract the proper json and save it to file
      - name: get-environment-json
        run: |
          curl -s https://api.postman.com/environments/${{vars.POSTMAN_ENVIRONMENT_ID}}?apikey=${{secrets.ORG_POSTMAN_API_KEY}} | jq '.environment' > env.json
          cat env.json


      # get collection json and save it to file
      - name: get-collection-json
        run: |
          curl -s https://api.postman.com/collections/${{vars.POSTMAN_COLLECTION_ID}}?apikey=${{secrets.ORG_POSTMAN_API_KEY}} > col.json
          cat col.json


      # Run the POSTMAN collection
      - name: Run POSTMAN collection
        run: |
          newman run col.json -e env.json --verbose --delay-request 2000

This setup installs Node.js and the newman tool, downloads the Postman collection and environment, and runs the collection using newman. Detailed documentation on newman can be found here.

This example uses workflow dispatch for manual triggering but can be adapted to run on every commit, pull request, or on a schedule using cron expressions.

To run this example, we can use the workflow dispatch.

Remarks

The example is a simple one with workflow dispatch only, but you can easily adapt it to run for every commit, pull request, or even as a scheduled one. For scheduling, we can use this site to experiment with cron expressions to find the appropriate expressions for our needs.

Conclusion 

Integrating Postman API testing with GitHub workflows offers a streamlined and efficient approach to ensure API contract integrity and robustness throughout the development lifecycle. By leveraging Postman’s capabilities for creating and managing collections of endpoints and test scripts, and automating their execution using GitHub Actions, we can achieve continuous integration and delivery (CI/CD) seamlessly. This setup not only capitalises on the efforts of developers and QA engineers but also enhances the reliability of API testing through automation.

The outlined process demonstrates how to set up and utilise Postman collections, integrate them with GitHub environments, and automate the tests using newman in a GitHub workflow. The simplicity and reusability of this method make it a practical choice for maintaining API stability, detecting issues early, and ensuring that changes do not disrupt the production environment.

As organisations increasingly adopt DevOps practices, integrating tools like Postman and GitHub becomes crucial for maintaining high standards of code quality and operational efficiency. This approach to API testing exemplifies how modern tools and automation can transform development workflows, making them more robust, reliable, and scalable.

By following these steps and adapting the workflow to specific project needs, teams can enhance their API testing processes, ensuring that their APIs remain consistent, reliable, and performant across different environments and stages of development.

André Pedroso

Previous story

Meet Pavlo, our iOS maverick

Next story

Mental health apps in 2024: The digital path to wellness