cerberus-article-tutorial-api-images-featured

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!

Leave a comment

Your email address will not be published. Required fields are marked *

Cerberus-Testing Terms Of Service


Website Terms and Conditions of Use

1. Terms

By accessing this Website, accessible from http://vgeouyk.cluster030.hosting.ovh.net, you are agreeing to be bound by these Website Terms and Conditions of Use and agree that you are responsible for the agreement with any applicable local laws. If you disagree with any of these terms, you are prohibited from accessing this site. The materials contained in this Website are protected by copyright and trade mark law. These Terms of Service has been created with the help of the Terms of Service Generator and the Privacy Policy Template.

2. Use License

Permission is granted to temporarily download one copy of the materials on Cerberus Testing's Website for personal, non-commercial transitory viewing only. This is the grant of a license, not a transfer of title, and under this license you may not:

  • modify or copy the materials;
  • use the materials for any commercial purpose or for any public display;
  • attempt to reverse engineer any software contained on Cerberus Testing's Website;
  • remove any copyright or other proprietary notations from the materials; or
  • transferring the materials to another person or "mirror" the materials on any other server.

This will let Cerberus Testing to terminate upon violations of any of these restrictions. Upon termination, your viewing right will also be terminated and you should destroy any downloaded materials in your possession whether it is printed or electronic format.

3. Disclaimer

All the materials on Cerberus Testing’s Website are provided "as is". Cerberus Testing makes no warranties, may it be expressed or implied, therefore negates all other warranties. Furthermore, Cerberus Testing does not make any representations concerning the accuracy or reliability of the use of the materials on its Website or otherwise relating to such materials or any sites linked to this Website.

4. Limitations

Cerberus Testing or its suppliers will not be hold accountable for any damages that will arise with the use or inability to use the materials on Cerberus Testing’s Website, even if Cerberus Testing or an authorize representative of this Website has been notified, orally or written, of the possibility of such damage. Some jurisdiction does not allow limitations on implied warranties or limitations of liability for incidental damages, these limitations may not apply to you.

5. Revisions and Errata

The materials appearing on Cerberus Testing’s Website may include technical, typographical, or photographic errors. Cerberus Testing will not promise that any of the materials in this Website are accurate, complete, or current. Cerberus Testing may change the materials contained on its Website at any time without notice. Cerberus Testing does not make any commitment to update the materials.

6. Links

Cerberus Testing has not reviewed all of the sites linked to its Website and is not responsible for the contents of any such linked site. The presence of any link does not imply endorsement by Cerberus Testing of the site. The use of any linked website is at the user’s own risk.

7. Site Terms of Use Modifications

Cerberus Testing may revise these Terms of Use for its Website at any time without prior notice. By using this Website, you are agreeing to be bound by the current version of these Terms and Conditions of Use.

8. Your Privacy

Please read our Privacy Policy.

9. Governing Law

Any claim related to Cerberus Testing's Website shall be governed by the laws of fr without regards to its conflict of law provisions.

Thank you for your interest in cerberus,

In order to proceed with your SaaS we need some in order to confirm your instances accesses.

Please provide accurate contacts to secure the process.

You can cancel any time the subscription, please read Terms of Use.