Cerberus Testing

The Open Source Test Automation Platform

Start Now
By Antoine CraskePosted on Posted in Software Testing Tutorial

Welcome to this Cerberus Testing step-by-step tutorial for testing REST APIs.

This guide will help you understand the test automation workflow and good practices supported by the Cerberus Testing open source framework. 

At the end of this article, you will be able to automate APIs tests for REST/JSON. You will learn how to configure your service library, create and execute the test case. 

We will perform the test of a public REST APIs on this JSON placeholder playground. You can use this tutorial to implement your own APIs test, being in REST or other protocols. 

If you are new to Cerberus Testing, we recommend that you start by having a look at our GitHub page, website and overview video. This tutorial is also available as a video.

Prerequisites

The following elements are required in order to successfully complete this tutorial:

  • A Cerberus Testing instance in version 4.x, self-hosted or SaaS.
  • A Cerberus Testing account granted with a “Test” role.
  • A Cerberus Testing environment (by default “QA” and “UAT” are set up).

If you decided to implement your own Test, you need to:

  • Have access to the API under test, both in terms of networking, authentication and authorization.
  • Define the Test action and controls you want to perform.

If you have any questions on those prerequisites, have a look at our documentation, videos or contact your administrator. Feel free to interact with the community on our slack channel or submit a GitHub issue.

Step 1 — Set up the API Application and Endpoints

This section describes the initial setup and integration to enable the API test automation.

The first step is to understand the API interface to define the request behavior and content. Then, we will create the application under test with its various environments definition. That way, we can configure our API calls, all linked to the same application.

1.1 Clarify the API behavior and request

Let’s start by understanding the API to be tested. Being a REST API, we can have a look at the available documentation on the website and the swagger portal if available.

In our case, being a public API available with a web playground, we can even directly access the API definition and samples.

Figure 1: The sample GET request of our REST API under test

We understand from the playground that it is a REST/JSON API to be called with the GET method to retrieve a particular “todo” task. 

No specific API call parameters are identified, simplifying the request we need to perform.

1.3 Create The Application under Test

First, we need to create the Application to link to the API library and test cases.

You can access the menu in the “Application / Application” toolbar. The following page appears to be filled with the various configuration elements.

On this first page, be careful to select the Application type “SRV” to explicitly state that your application is an API.

Figure 2: The application to create of type “SRV” for APIs test

Once done, the “Environments” tab let you define the various test execution contexts composed by a country and a test environment.

You can attach different endpoints and parameters to each of those.

Figure 3: Each application can contains its set of test environments

1.2 Configure The API Call in the Service Library

We can now configure the API call inside Cerberus Testing in the “Application / Service Library” menu.

Configure the following parameters according to our use-case:

  • Type: “REST”. Note that other APIs typologies are available. If you want to test a GraphQL API, the same REST protocol applies.
  • Method: “GET”. Other invocation modes are available, such as POST.
  • Service Path: Here we define the GET endpoint URL. This value can be dynamically set using the application definition. We will show this capability at the end of this tutorial.
Figure 4: A service library is available, linked to applications and with various protocols

Step 2 — Create The Test Case

We will now build our test case to be run against the application we just created.

Similarly, we will access the required menu, define our test case content and share tips related to the test creation process.

Figure 5: We can then create a Test Case in the main menu

Click on “Create Test Case” to display the creation pop-up, that we will fill with the required information.

Figure 6: Test Case are described in plain text, starting with header information

Clicking on “Create”, you will confirm the test case creation.

Step 3 — Define The Step, Action and Control

We can now configure the test case content using the low code library: Step, Action and Control.

A Step is a collection of Actions and Controls for the main stages of your test. With a good design of those elements, you will be able to reuse them across tests to improve your test maintainability.

3.1 Add the Test Case Step

We can now add a Step via the “Add Step” button and enter the corresponding description. Use clear descriptions in order to have clear test readability. This improve the test maintainability and reuse.

3.2 Add the Test Case Action and Controls

In this step, we will detail the various actions and controls that should be performed during the tests. The commands are executed in their order of appearance.

Figure 7: A Test Case contains Actions and Controls arranged into Steps

We listed below the parameters that you can use:

  1. Call the REST API
    • Action callService: Perform the call to the reference API library service.
  2. Verify the API call
    • Control verifyStringEqual: Verify the status code of the last API call to be a success (200) using the dynamic variable %SYSTEM.LASTSERVICE_HTTPSTATUS%.
  3. Verify the API answer:
    • Control verifyNumericEqual: Check that the user ID retrieved is a value 1 parsing the JSON response.

For the parameter definition, two possibilities are up to you:

  1. Declaring in the control itself the JSON to be parsed. For instance “$.userId”.
  2. Defining a test case variable of type “GetFromJson”, configured with “$.userId”.

Both approaches are available and working fine. In fact, the second one brings more flexibility and scalability if you want to reuse your test as a template with different values.

We confirm the changes by clicking on the “Save Test Case” button in the top right corner.

Step 4 — Run The Test Case

We are now ready to execute our Test Case! Navigate to the Run page by going to “Run / Run Test Case”. By default, the other options are not available until you run the test once in a specific environment.

4.1 Launch the Test via the Run Test Page

The Test Case is selected by default so we can define the execution parameters scrolling down on the page.

Figure 8: We can run the tests in the various available environments

Confirm the following parameters :

  • Environment: Select one or more environments where the Test Case should be executed. In our case, pick “QA”.
  • Country: Check one or more countries where you would like to run the Test Case. One more time, the country you select must be defined in the Application. Pick “UK”.
  • Robot Settings: Any robot can be taken at that stage, as we only perform an API call. If our test was combining web and API actions, for instance, we should take the correct robot.
  • Execution Settings: Mainly related to the traceability levels for the test, test infrastructure and queuing mechanisms (retry, priority, …).

Launch the Test Case and see it running live by clicking on “Run TestCase (and See Result)”.

4.2 Follow the Test Case Execution

You will see this page appearing after the test launch.

Figure 9: Execution traceability is available with rich logging features

If you encounter an issue at this stage, we listed here the common themes:

  • Verify your Application definition, especially for the test environment and country. If you encounter a message related to those parameters, this is probably the problem.
  • Verify your Test Case activated Environment. If you cannot launch your test in a Production environment, you will need to explicitly activate it in the Test Case Header. 
  • Verify that your Robot is correctly running and accessible on the ports you configured. You can manage them on the “Run/Robots” page.

Step 5 — Analyze The Test Case Report

It is now time to analyze the result of our test case execution!

Once your Test Case is finished, the progress bar on the top will display your Test Status. The main ones are OK or KO, you can access more detailed information in the Cerberus Testing Documentation on Execution Status.

We described here the various tabs and their corresponding usage :

  • Steps: History of all your Test Case Step, Action and Control performed, with executed data and links to the various screenshots, for instance.
  • Properties: Find here all the Properties used for your test. As we did not define one here, this tab is empty.
  • Execution Details: Traceability related to the Test Case execution, including start and end times, status and ID. It is from this tab that you can open a ticket to an external platform if it is configured.
  • Environment: Describes the Test Case environment context.
  • Robot: Traceability of your Robot test infrastructure and browsers.
  • Traceability: Contains the changes made to the execution, if any.

Common API Testing Automation Scenarios 

In reality, API testing tends to be more complex than the simple case of this tutorial.

So, in this section, we share common themes encountered with API test automation: authentication, test data variables and white-box testing.

Authentication Header

REST APIs are the de-facto standards for exposing business services. But they require layers of authentication to then handle authorizations.

An usual way is to use tokens in the forms of request header, Bearer token or specific body parameters. 

You can configure the token in the application environment definition. In our example, we configure it using the parameter “variable 1”.

Figure 10: We can add more environments as required

This allows you to have a single API call in your library that dynamically retrieves its authentication tokens depending on the environment execution.

Test Data Variables

In addition to a sample API call, we quickly want to test other use-cases for the same API request and response.

This is where using a test case template with different action and control data, help to expand a test suite while keeping it maintainable.

The definition of a test case variable is called a “Property” inside Cerberus Testing. You can configure a specific parameter to parse JSON with the following definition.

Figure 11: Properties help to decouple the test case implementation from its test data

That way, your test case can be added to the Test Library, while each test case can define its specific test parameters.

White-box Testing

As it happens, APIs are consumed directly but they can also be embedded into complete applications.

This is why we could want to perform Full Stack Testing. For instance, we could start from the User Experience on the Web Browser. Then, after performing key actions, we can verify the Back-End state by calling an API or accessing the data store.

In Cerberus Testing, you can combine Web and API actions in the same test case.

Figure 12: Cerberus Testing enables to compose tests with a reusable library

Expanding Your REST API Testing Automation

By now you should have been able to run the example we described or even a test case of yours.

We hope this tutorial has helped you understand the main stages involved to automate your REST API testing.

Scaling your test automation will be supported by the other capabilities offered by Cerberus Testing, such as parallel execution, campaign management and CI/CD execution.

Happy Testing!

Automate REST API Tests with Cerberus Testing Framework
Scroll to top