Lesson 9: REST API Testing

Goal

Create a test to validate REST API transactions for Create and Search

Prerequisites

Have basic understanding of REST API/Web services

Starting code

Start tag: lesson/14

Steps

Using Rest API’s provides great flexibility in terms of the number of transactions. To access the REST services we need to log in with a user with administration permissions (like External01@fostermoore.com/External01), and access the menu Open APIs

Once inside there will be 3 core REST Api services:

• POST/hero: Which will create the hero
• GET/hero/{businessIdentifier}: Which can search a hero based on the business identifier allocated to the hero/get
• GET/heroes: For general search

Scenario: Create a hero via REST API

Also a new json file called PostHero,json which will contain the structure we are going to submit via the POST service for heroes.

Now, let’s go back to the Open API UI interface where we can identify some of the core elements required for our automation:

1. We need the URI or resource identification to submit or post the request
2. A template that contains all details required for submission and element types supported

We are going to use new steps for the REST Api testing

I (POST|PUT) rest webservice template (S+) with uri (.*)

I expect webservice status code (.*)

I validate rest webservice result against (.*)

To get the template for our test automation we need to copy the structure from the structure section and paste it on the Json file created

{
  "name": "string",
  "secretIdentities": [
    {
      "firstName": "string",
      "middleNames": "string",
      "lastName": "string"
    }
  ],
  "registrationDate": "2021-03-15",
  "yearOfArrival": 0,
  "costumeYn": true,
  "capeYn": true,
  "superPowers": [
    {
      "name": "agility"
    }
  ],
  "confidants": [
    {
      "individualName": {
        "firstName": "string",
        "middleNames": "string",
        "lastName": "string"
      },
      "type": "personal",
      "emails": [
        {
          "email": "user@example.com",
          "_ConfirmEmail": "string"
        }
      ],
      "mobiles": [
        {
          "phoneCountryCode": "AF",
          "phoneNumber": "string"
        }
      ],
      "trustLevel": "1"
    }
  ],
  "sidekicks": [
    {
      "lookupYn": true
    }
  ]
}

For the feature file we are going to create the following example:

Scenario: Create a hero via REST API

  Given I set application to heroes
    When I logon as External01@fostermoore.com with password External01
    Given I set application to heroes
    And I POST rest webservice template /tests/hercules/tests/H009/PostHero.json with uri heroes-api/v1/hero
    Then I expect webservice status code 201

Error codes for REST API can be found on the Step definition page for REST Api testing

Attempting to run the test above will trigger the Magellan Error screen which will provide a series of links with functionality to debug any issues. If we click the link Open JSON response (status: 400) we can see a new popup with information about the errors found. The problem here is that we are trying to validate Error 201 against a response that contains an Error 400, to solve this issue we need to update our request file to reflect valid data so we can submit our service again and get the right status 201

Let’s update the file with valid details so we can get status 201

Now we are on the file, let’s update with valid details

{
  "name" : "Super Verne",
  "secretIdentities" : [
    {
      "firstName" : "Secret",
      "middleNames" : "I",
      "lastName" : "Dentity"
    }
  ],
  "yearOfArrival" : 2001,
  "costumeYn" : true,
  "capeYn" : false,
  "superPowers" : [
    {
      "name" : "agility"
    }
  ],
  "confidants" : [ ],
  "sidekicks" : [ ]
}

As you can see we created a simple test where we validate the status code 201 is correct.

Scenario description for Retrieve (GET)

We are going to update the scenario we are using for create to validate the service transaction using GET. Think on GET as search. Sometimes GET can use 1 parameter or no parameter at all.

Actions we are going to perform in this scenario: Get via REST API a Super Hero recently created We are going to update the test created before and we are going to Get the created super hero via REST API using

Our new steps that will append at the end of the HappyPath will be

When I GET rest webservice with uri heroes-api/v1/hero/${rest.txnBusinessIdentifier}
Then I expect webservice status code 200

You are going to notice that for the last section on get we are using a variable. These variables are explained on the step definition page.

Because the step Get requires a Business Identifier, this identifier will be automatically extracted from the POST step we are using above.

If we execute the step now we are going to find the successful result at the bottom

Let’s add more complexity by adding the validation of data coming back from the GET. To do this we are going to copy the content of the result and store it o a JSON file. The first step is to create a new file called ResponseHero.Json

Once the file is created we are going to copy the content of the response into the file

1. Click Open JSON response (status: 200)
2. Copy the content of the file
3. Paste it on the ResponseHero.json file

Let’s go back to the test and add a new step called And I validate rest webservice result against /tests/hercules/tests/H009/ResponseHero.Json . The step will validate the response of the service against the file that we just created. Let’s run the test again to see the results!

The test will result on a complete failure because some of the details coming back from Verne are dynamic for example all the Ids are dynamic on the response. To solve this validation scenario you can use the following variables:

#IGNORE# – Will skip the validation of the value.
#NONBLANK# – Only checks if there is value. Won’t validate if the value is expected.
#UNORDERED# – Indicates that the list is not ordered. Only checks if all of the items are in the list but won’t check the order

In our particular scenario we will use #NONBLANK#, the reason is because we want to make sure the fields with IDs are generated and contains a value.

{
  "txnBusinessIdentifier" : "#NONBLANK#",
  "txnVersionIdentifier" : "#NONBLANK#",
  "txnIdentifier" : "#NONBLANK#",
  "txnUid" : "#NONBLANK#",
  "txnDataset" : "heroes",
  "name" : "Difyzptsvs",
  "secretIdentities" : [
    {
      "recId" : "#NONBLANK#",
      "firstName" : "Secret",
      "middleNames" : "I",
      "lastName" : "Dentity"
    }
  ],
  "status" : "active",
  "registrationDate" : "2021-03-20",
  "yearOfArrival" : 2001,
  "costumeYn" : true,
  "capeYn" : false,
  "superPowers" : [
    {
      "recId" : "#NONBLANK#",
      "name" : "agility"
    }
  ],
  "confidants" : [ ],
  "sidekicks" : [ ]
}

If we try to run the test again, we will see that the test now has status PASS.

With the new step we manage to automate a response JSON, if by any chance the structure changes in the future our test can identify the changes.

Using variables on REST API Testing

Magellan allows usage of variables that can be consume by the JSON files. Variables can help to create scenario that can be reused and maintained very easily.

Let’s recap over the POST scenario. We can attempt to write the same scenario by using variables, rather than pure values on the JSON.

• The first step is to make a copy of the existing Request file ResponseHero.json and call it ResponseHeroVariables.json
• The second step is to make a copy of the existing Feature file RestHappyPathPostHero and call it RestHappyPathPostHeroVariables.feature
• The third step is to make a copy of the existing PostHero.json file and call it PostHeroVariables.json

With the new files copied we want to override the new test but using variables.

Feature: heroes/tests/hercules/tests/H009/RestHappyPathPostHeroVariables

  Scenario: Create a hero via REST API using varibales
    Given I set application to heroes
      And I create a variable called name with value Super Verne
      And I create a variable called firstName with value Joe
      And I create a variable called middleNames with value M
      And I create a variable called lastName with value Verne
      And I create a variable called yearOfArrival with value 1980
      And I create a variable called power with value agility
    When I logon as External01@fostermoore.com with password External01
    Given I set application to heroes
      And I POST rest webservice template /tests/hercules/tests/H009/PostHeroVariables.json with uri heroes-api/v1/hero
    Then I expect webservice status code 201
    When I GET rest webservice with uri heroes-api/v1/hero/${rest.txnBusinessIdentifier}
    Then I expect webservice status code 200
      And I validate rest webservice result against /tests/hercules/tests/H009/ResponseHeroVariables.Json

Now we override the PostHeroVariables.json with the variables that we created on the feature file

{
  "name" : "${name}",
  "secretIdentities" : [
    {
      "firstName" : "${firstName}",
      "middleNames" : "${middleNames}",
      "lastName" : "${lastName}"
    }
  ],
  "yearOfArrival" : "${yearOfArrival}",
  "costumeYn" : true,
  "capeYn" : false,
  "superPowers" : [
    {
      "name" : "${power}"
    }
  ],
  "confidants" : [ ],
  "sidekicks" : [ ]
}

And the last file which is ResponseHeroVariables.Json that contains the answer from the server once we submit the request.

{
  "txnBusinessIdentifier" : "#NONBLANK#",
  "txnVersionIdentifier" : "#NONBLANK#",
  "txnIdentifier" : "#NONBLANK#",
  "txnUid" : "#NONBLANK#",
  "txnDataset" : "heroes",
  "name" : "${name}",
  "secretIdentities" : [
    {
      "recId" : "#NONBLANK#",
      "firstName" : "${firstName}",
      "middleNames" : "${middleNames}",
      "lastName" : "${lastName}"
    }
  ],
  "status" : "active",
  "registrationDate" : "#(dateonly)today#",
  "yearOfArrival" : 1980,
  "costumeYn" : true,
  "capeYn" : false,
  "superPowers" : [
    {
      "recId" : "#NONBLANK#",
      "name" : "${power}"
    }
  ],
  "confidants" : [ ],
  "sidekicks" : [ ]
}

As a result now we can parameterize our test with variables and reuse the same file to post different combinations.

Recap

In this lessons we discover:

• How to POST requests using Hercules
• Hot to GET request using Hercules
• Validated status code
• Use variables on REST

Additional info about data validation step definitions here