Nailing Down API Testing With Karate Framework

API testing, be it REST, SOAP, JSON, XML or GraphQL, can be tricky – both from perspectives of the testing code itself and from maintaining it up to date as it evolves over time. However, by using Karate Framework you can overcome these struggles! Karate Framework helps get rid of the boilerplate code which is involved in performing the requests and asserting the response contents. In addition, it provides a descriptive language based on Cucumber that allows tests to be easily written and understood even by non-programmers.

In order to demonstrate a bit of the framework, we need first an accessible API. Let’s use a playground project from Best Buy. The setup is fairly easy to have it up and running in a few minutes. After the playground API is running, it is time to get started with the API testing.

Let’s use a Maven archetype to boost the project quickly.
Our development environment will be Intellij Idea CE with Cucumber Plugin, Java 8 and Maven 3. 

Create a folder to host the test project and run the command below:

mvn archetype:generate \
-DarchetypeGroupId=com.intuit.karate \
-DarchetypeArtifactId=karate-archetype \
-DarchetypeVersion=0.5.0 \
-DgroupId=io.testproject \
-DartifactId=api-testing

At this point, you have the project structure ready to start writing the tests. The archetype comes with some testing samples, but we will write our own. Let’s create one package folder and name it features under src/test/java. This is where all the feature files will reside.

In order to run tests on feature files, you will need one class at the root of our features folder like the one below:

APITest.java
package features;

import com.intuit.karate.junit4.Karate;
import org.junit.runner.RunWith;

@RunWith(Karate.class)
public class APITest { }

This class is needed so the Maven test phase picks up the test files and runs all the tests recursively on the sub-folders. Now we can proceed and create our first feature file. Let’s create a file called products.feature under src/test/java/features/products.

This is how your project structure should look like:

 

 

 

 

 

 

 

 

We can add the first test as below:

products.feature
Feature: Verify that products are properly returned by the API

  Background:
    * url 'http://localhost:3030'

  Scenario: Products are returned on GET

    Given   path 'products'
     When method get
     Then status 200

This is a very basic test: it just verifies that after we perform a GET on the /products endpoint, we should receive an HTTP code 200 that implies a successful call. After we are finished we can call mvn test and see the test output. The feature file will be executed, with all the scenarios and steps on it.

Let’s add another scenario to check more advanced tests:

products.feature
#existing content of products.feature

  Scenario: Specific product has minimum required data to be displayed

    Given  path 'products/9132294'
    When method get
    Then status 200
     And  match $ == { price: #notnull, description: #notnull, image: #notnull  }

Now we are navigating to a specific product and verifying it contains the minimum information to be displayed in the website. We need to check whether it has price, description and image. Let’s run the mvn test again.

We can see our first test failure. The == operator tells the framework to expect exactly the 3 fields in question, but as the response has several others, it fails. In order to verify the response has at least the 3 fields we expect, we need to correct it by using the contains operator:

products.feature
#existing content of products.feature

  Scenario: Specific product has minimum required data to be displayed

    Given  path 'products/9132294'
    When method get
    Then status 200
     And  match $ contains { price: #notnull, description: #notnull, image: #notnull  }

And now the test works as expected. Karate implements JsonPath expressions to traverse on the response fields, which makes it easier to interact. We can add one small example to our last feature:

products.feature
#existing content of products.feature

  Scenario: Specific product has minimum required data to be displayed

    Given  path 'products/9132294'
    When method get
    Then status 200
     And  match $ contains { price: #notnull, description: #notnull, image: #notnull  }
     And  match $.categories contains { id: #notnull, name: #notnull, createdAt: #notnull, updatedAt: #notnull }

That’s it, we are now able to navigate to the categories array and evaluate its content without writing complicated matchers or delicate string manipulations.

This tutorial highlights some of the core features of Karate Framework that will allow you to create a bullet-proof API Testing with very little setup, a learning curve and deliver robust and easy-to-maintain tests. For a more comprehensive feature list, please check Karate project in Github. The code found on this sample project can be found at my Github.

What do you think of API testing with Karate Framework?  You are welcome to leave your thoughts and questions in the comment section below.  Happy Testing!  😎