Introduction

If you've been involved with application development or testing, you've probably used Postman to test API endpoints. In this post I'm going to create a sample endpoint, write Postman tests for the endpoint, and create a Github workflow to run those Postman tests whenever I push changes to the repo. The code we'll walk through can also be found in my repo.

So let's get started.

The app

The point of this article is to walk through creating Postman tests and getting them running in a pipeline, so I'm not going to spend a lot of time with the sample app. To get an endpoint stood up quickly, I'm using an open source tool called JSON server.

I'll avoid the temptation to tell you all the awesome things that JSON server can do for you. For now, I'll just say I can spin up a fully functional endpoint with just docker and a JSON file.

This endpoint is going to be pretty basic, and will provide basic CRUD operations for a list of albums.

The json file looks like this:

{
    "albums": [
        {
          "id": 1,
          "artist": "The Beatles",
          "title": "Please Please Me",
          "year": "1963"
        },
        {
          "id": 2,
          "artist": "The Beatles",
          "title": "With the Beatles",
          "year": "1963"
        },
        {
          "id": 3,
          "artist": "The Beatles",
          "title": "A Hard Day's Night",
          "year": "1964"
        },
        {
          "id": 4,
          "artist": "The Beatles",
          "title": "Beatles for Sale",
          "year": "1964"
        },
        {
          "id": 5,
          "artist": "The Beatles",
          "title": "Help!",
          "year": "1965"
        },
        {
          "id": 6,
          "artist": "The Beatles",
          "title": "Rubber Soul",
          "year": "1965"
        },
        {
          "id": 7,
          "artist": "The Beatles",
          "title": "Revolver",
          "year": "1966"
        },
        {
          "id": 8,
          "artist": "The Beatles",
          "title": "Sgt. Pepper's Lonely Hearts Club Band",
          "year": "1967"
        },
        {
          "id": 9,
          "artist": "The Beatles",
          "title": "The Beatles (White Album)",
          "year": "1968"
        },
        {
          "id": 10,
          "artist": "The Beatles",
          "title": "Yellow Submarine",
          "year": "1969"
        },
        {
          "id": 11,
          "artist": "The Beatles",
          "title": "Abbey Road",
          "year": "1969"
        },
        {
          "id": 12,
          "artist": "The Beatles",
          "title": "Let It Be",
          "year": "1970"
        }
      ]
  }

With just this file (and Docker) I can start my endpoint like this:

docker run -d -p 3005:80 -v /Users/denniswhalen/postman-workflow/db.json:/data/db.json clue/json-server

You should now be about the hit that endpoint at http://localhost:3005/albums

Once we get some data back, we can create some Postman tests.

The Postman tests

I'll assume you have familiarity with Postman. If you don't you can check out my previous post to get started, and of course there are many other fine resources available to get you started.

My first test is just going to do a GET request to http://localhost:3005/albums, verify that I get a response with status code of 200, and validate the schema of the response.

The test for my Postman request looks like this:

I'm kind of glossing over this cool little Postman test that is validating the schema, but if you've never used Postman for schema validation it's definitely worth some more research. FYI, I used https://www.liquid-technologies.com/online-json-to-schema-converter to generate the expected schema.

Once I have my Postman test complete and have confirmed the test passes when it should and fails when it should, I will add it to my code repo. What repo you say? Well I guess I haven't mentioned that yet, but we're going to store our Postman collection is a Github repo. To do that you just need to use Postman to export the collection as a json file, and then add that file to your repo just like you would any other file.

If you push that change to Github, BOOM, you will see no workflow has run:

Well of course. That's because we haven't created a workflow yet. We want a workflow that will run our Postman tests whenever code is pushed. If the Postman tests fails, we want the build to fail. Let's create the workflow now.

The workflow

To allow Github to find the workflow file, the file needs to be in the ./.github/workflows folder. I'm naming my file workflow.yml, but the name doesn't matter. Only the file extension (.yml or .yaml) and file location matters.

Let's take a look at the .yml file for this workflow:

name: run Postman API tests
on: 
  push:
    branches:
      - 'main'
      - 'feature/**'
    paths-ignore:
      - 'Postman Collections/**'
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@v2

      - name: start the app
        run: |
          docker run -d -p 3005:80 -v ${{ github.workspace }}/db.json:/data/db.json clue/json-server

      - name: run postman tests
        uses: matt-ball/newman-action@master
        with:
          collection: "Postman Collections/albums.json"

This workflow is pretty basic and hopefully the steps of the "build" job make sense:

• checkout - pull the code from the repo
• start the app - starts the json-server endpoint
• run postman tests - runs the postman tests in a container that has the Postman dependencies

After adding the workflow.yml file to the repo and pushing, you he now see a workflow running un the actions tab in Github.

Hopefully you'll see something like this, indicating the test build was successful:

If you open the "run postman steps" step you should see something like this, providing more detail about you Postmen test results:

Wrap-up

So there we go, we created an endpoint, wrote a cool Postman test, and created a repo with a workflow to run the tests. That wasn't too painful, right?

For our example, I mentioned exporting the Postman collection to json and adding it to the repo like you would with other files. There are a couple of other options for dealing with the Postman collection that I will cover in a future post.

The code I've talked about here can be found in my repo.

And finally, to get notifications for my future posts, feel free to subscribe to my blog site. Thanks!