Trello API testing with Postman, Circleci, Newman

In this blog will be sharing about how to test Trello API with Postman and push all the code to Github and then run them in Circleci with Newman command line interface. Before configuring project, make sure that you have account for Postman, Circleci, Trello and Github.

Agenda

1. About PostMan and Trello
2. Fetching the list of boards
3. Sending a GET request
4. Getting access to Trello API
5. Create a board
6. Create two lists
7. The TODO List
8. The DONE List
9. Creating a card
10. Moving the card between lists
11. Invalid operations for cards
12. Delete Board
13. Run in Postman
14. Configure folder structure
15. Configure and commit code to GitHub
16. Configure project in CircleCI
17. Running scripts from CLI using Newman and view the result in CircleCI

About Postman and the Trello API

Postman is a lightweight tool the interact with Web Services. By abstracting low-level commands, such as cURL, and by structuring request formation, Postman allows us to create complex requests and explore APIs with ease.

Fetching the list of boards

Let’s first see if we can fetch some public data.

The Trello API has an endpoint that allows us to fetch data of all public boards of an user (on the API referenced as a “member”). The cURL call to this endpoint has the following format:

curl --request GET --url https://api.trello.com/1/members/id/boards

The cURL call tells us two things:

1 — We need to send a GET request;

2 — The endpoint URL starts with the https://api.trello.com address, on the version 1, on the resource members. We will need to pass the user ID or username. Inside the resource which represents the account, the boards resource gives us the information about public boards.

On Postman, this cURL call can be written like this:

Whats happening here, as we can see {{trelloAPIURL}} and {{userName}}. These are the variables that can be set in environment global variables in Postman.

Create environment global variables in postman

Once environment set, we can see the values for url something like this;

Now we send this request, Postman will display the JSON response on the bottom of the app.

Getting access to Trello API

However, to create and modify entities using the Trello API, we need to identify ourselves in the HTTP requests.

As a step 0, we need to be sure that we can interact with the Trello API.

The documentation for the Trello API tell us we will need two pieces of information to confirm to Trello our identity: Our API Key and an OAuth token, both associated uniquely to our Trello account.

Once getting the key and token we can set this in environment global variables.

Create a Board

Ok, we can access the Trello API using our keys and fetch data from it.

The next step is to perform some actions. Let’s start with the first action of the CRUD: A new board shall be created!

The Trello API exposes an endpoint for creating new boards. The cURL call would be of the following format:

curl --request POST --url https://api.trello.com/1/boards/?name=name

It says we should make a POST request to the boards endpoint, passing the name of the board we want to create.

On Postman, this would be our request:

We will send a POST request. The Trello’s address, token, and key came from the environment variables, as before. Now, however, we have the additional parameter name.

When we send this request, Trello creates the board on its backend and provides to us the data about the newly created board

The most important information, for our purposes, is the new board ID. It will allow us to reference specifically this board on future requests. To do it, we need to save this information in a variable.

Since we want to use information provided by the response, we must use the Test tab. In this tab, the object pm.response provides all information of the request’s response. Since we know that we are dealing with a JSON API, we can interpret the response as a JSON object and, thus, extract the idattribute as we would do in any JavaScript program.

pm.response.json().id;

The pm.environment.set function allows us to update or create an environment variable. Therefore, it’s straightforward to save our board ID to be used in the following requests.

Create two lists

Our board is created and we have a reference to it. It’s time to create some lists…

The endpoint to create lists is accessed by the following cURL command:

curl --request POST --url 'https://api.trello.com/1/lists?name=name&idBoard=idBoard'

As expected, since we are dealing with creating a new entity, we have to send a POST request. The endpoint for creating with lists is lists.

The creation requires the attributes name and idBoard (besides our access tokens). So, we can reuse the tokens variables, fetch the board ID value we’ve saved, and pick from environment variables.

Now lets go to “Test” tab and create a script that would, check the response, verify the list name is the same we have sent on the request

Next lets run this and check what’s happening, if all good should get response as 200.

The DONE List

The DONE list will follow the same pattern as the TODO List: All checks and procedures of the previous section can be duplicated.

We create it on the same endpoint, using a defined variable — getting as response the data of the list.

Now let’s run this and check the result;

Creating a card

With our lists created, we can populate them with cards.

The endpoint to create cards is accessed by the following cURL command:

curl --request POST --url https://api.trello.com/1/cards?idList=idList

Again, in order to create a new entity, we will send a POST request. The endpoint address is the same as before. The endpoint for creating with cards is cards.

Now lets run this endpoint and get the result as below;

The card’s information that comes with the response is as below:

Some checks can be performed on these response:

1 — The response status

pm.test(“Status code is 200”, function () {
 pm.response.to.have.status(200);
});

2 — The Card name

pm.test(“Name to equal That’s a Bug”, function () {
 const data = pm.response.json();
 pm.expect(data.name).to.eql(pm.environment.get(“ThatsABugCardName”))
});

3 — If the card was created on the correct list

pm.test(“Created on correct list”, function () {
 const data = pm.response.json();
 pm.expect(data.idList).to.eql(pm.environment.get(“TODOListId”));
});

4 — If the card was created on the correct board

pm.test(“Created on correct board”, function () {
 const data = pm.response.json();
 pm.expect(data.idBoard).to.eql(pm.environment.get(“trelloBoardid”));
});

5 — If the card’s default status is “no votes nor attachments”

Moving the card between lists

Now that a card is created the TODO list, we will move this card to the DONE list.

The endpoint to update cards is accessed by the following cURL command:

curl --request PUT --url https://api.trello.com/1/cards/id

Now, instead of a POST request to a specific list, we will send a PUT request for a specific card.

In a REST API, the PUT request creates or updates an entity, similarly to the POST request. However, PUT request are idempotent — meaning that performing the same request repeatedly has the same effect as one call.

The call to the cards/id endpoint allow us to update almost all attributes that we could have set on the card creation.

Now let’s run this in postman, the response comes with all information about the card, with the updated list ID:

Invalid operations

Let’s say we send a move request for a card that does not exist — maybe it never existed, or another application have deleted between our creation and move requests.

How would Trello respond to it ?

Let’s send the following request:

Now verify the result, should get some meaning full message.

The response has code 404: Not Found. And the body of it is a simple text, but now saying that Trello searched for the resource, but couldn’t find.

Deleting the board

We have already Created, Retrieved, and Updated boards, lists and cards. Now it’s time to Delete our board.

The endpoint to delete boards is accessed by the following cURL command:

curl --request DELETE --url https://api.trello.com/1/boards/id

The domain is the same for Creating Boards, but the request type is different: We will be sending a DELETE, because we want to remove an entity from the database.

On Postman, the request is also similar to the board creation, but with a different type.

Using environment variable that already stored the “BoardID”, we can refer this id and then delete the board.

After sending the request, we get 200 OK as response, with a null-like body:

After sending the request, we get 200 OK as response, with a null-like body:

Cool, so far we have completed the CRUD methods for Trello with postman. Now lets export this as collections and then configure simple folder structure and the push the code to Github.

Export collections from postman

Within postman from left had menu for the project click on “…” and click o Export button, and save it local disk with name “PostmanTrelloCollections.json”

In same way export environment variables too from settings menu.

Done, now lets create simple folder structure in local disk.

Create project folder as “trellopostman”, under this create folder as “tests” and then push the two collections files that already downloaded in previous step.

Push code to GitHub

Make sure you have an account and then follow the command to push. Learn more about creating git repository here — https://opensource.com/article/18/1/step-step-guide-git

sample commands 
git status
git add .
git commit -m “made some changes”
git push -u origin master

Lets Integrate with CircleCI

Make sure to create an account in Circleci and also the project that would point to your github account and repository.

Please refer this link to know more about how to create project and map to github — https://github.com/dwyl/learn-circleci

Under project “trellopostman” that already we created in previous step, create the folder called .circle and create a config.yml as below

version: 2.1
orbs:
newman: postman/newman@0.0.2
jobs:
build:
executor: newman/postman-newman-docker
steps:
- checkout
- newman/newman-run:
collection: ./tests/PostmanTrelloCollections.json
environment: ./tests/TrelloEnv.json

Make sure that the collections points to correct folder ex. tests. All the magic done by “executor: newman/postman-newman-docker” in config.yml file. If we observe here we can see “newman” as a step.

What is NewMan

Newman is a command line Collection Runner for Postman. It allows you to run and test a Postman Collection directly from the command line. It is built with extensibility in mind so that you can easily integrate it with your continuous integration servers and build systems.

Newman maintains feature parity with Postman and allows you to run collections the way they are executed inside the collection runner in the Postman app. Learn more about Newman here https://learning.getpostman.com/docs/postman/collection_runs/command_line_integration_with_newman/

How to run scripts from command line

Newman allows you to run Postman test collections whenever code is pushed to your repository. Once all commit is done to Github repository as in previous step and CircleCI/config.yml configured now run “git push” from command line, this would run the scripts in CircleCI as below;

Without CircleCI if you wish to run from command line still we can do that.

First, export both your environment and collection as JSON files. Then, simply tell Newman where your environment and collection are and run it.

After run should get result something like this;

Final Thoughts

Thanks for reading👩‍💻

I hope these short instructions helps someone out there. And I would like to know if you have better or worse experiences with E2E Postman, NewMan, Github and CircleCI.

If you want to play with this collection, you can download it https://github.com/gururajhm/trellopostman

Next time

In next blog, we will build upon the tests developed with Postman BDD and also Contract Testing to run the tests on command line and CI using Newman.

References

CRUD Testing with Postman and Trello API

Trello API — https://developers.trello.com/reference/#membersidboards

Postman — https://www.getpostman.com/

Circleci — https://circleci.com/