REST testing based on Karate framework

    Introduction

    Karate is an open-source Behavior Driven Development (BDD) framework that allows conducting the following types of tests with no need to write additional code:

    • REST API request testing.
    • UI testing.
    • Mocks writing.
    • Load testing.

    Behavior Driven Development (BDD) is an approach to development and testing, when special attention is paid to product behavior in business terms. BDD based tests check various scenarios that are of direct interest to the client.

    When using this approach, entities, events and results are defined by assigning them names that are understandable to each development participant.

    BDD professionals then use this dictionary to create a domain-specific language that they can use to code system tests. Each test is based on a user story written in a language used by all stakeholders.

    Karate syntax is based on popular Cucumber framework. And thanks to the rich internal functionality, most tests can be written even with no need to know the programming language.

    This article will describe the process of testing REST API queries based on Karate framework. The starting point is the creation of a project based on Karate framework. After that the configuration is set up and test scripts for specific user needs are created.

    Creating a project based on Karate

    To create a new project based on Karate, it is required to do the following in Intellij Idea:

    1. Select in the menu: File -> New -> Project…
    2. Select Maven.
    3. On the right side of the window select “Create from archetype” and click Add archetype…
    4. Add a new archetype in the window that appears:
      • GroupId: com.intuit.karate.
      • ArtifactId: karate-archetype.
      • Version: 0.9.6 (Specify the latest version here).
    Adding an archetype

    Figure. Adding an archetype.

    Dialog box for adding an archetype.

    Figure. Dialog box for adding an archetype.

    1. Click OK.
    2. After that the new archetype, karate-archetype, will appear in the archetype window.
    3. Select this archetype in the window and create a project.

    As a result, a project with the following structure will be created:

    Project structure.

    Figure. Project structure.

    All required dependencies for API testing will be added to pom.xml. Also, an example will be created in the examples.users module, on the basis of which you can see the framework in operation. Files with *.feature extension are test files.

    It is worth noting that files with *.feature extension are stored in the folder with the main code, but not in the resources folder. This is not a bug, but part of Karate framework code-convention. When the project grows large, it will be more convenient to find *.java and *.feature files in one place, because, as mentioned above, *.feature files are files with tests.

    This is why the generated pom.xml file contains the following lines:

    Generated pom.xml file.

    Figure. Generated pom.xml file

    Test case description using DDT

    There is REST service that provides the necessary information about a given country by query /country?name=< country name>. During the test you need to run a query by several countries and make sure that the query works correctly.

    For example: when running the query /country?name=USA, you will receive a response with “country” fields: ”USA”, “code”:”US”, and the rest of the fields will contain numbers, since they cannot be empty.

    Now let’s consider how this test case can be implemented using Karate framework.

    Test framework setup

    The only thing that is required to run Karate is the karate-config.js file in “classpath”. This file should contain the javascript function that will return a json object. All keys and values will be available as variables. As a result, you can configure various profiles and global variables for them.

    Configuration example:

    Example of configuration.

    Figure. Example of configuration.

    karate.env is an environment variable, depending on which you can change the behavior of tests. By default, the env value will be null, but it can be set, for example, using the maven command: mvn test -DargLine=”-Dkarate.env=e2e”.

    You can specify any number of global constants in the configuration. Constants baseUrl and rapidApiKey are specified in this example.

    You can also change the parameters of various preset configurations using the karate.configure() method. For example, the retry configuration was changed in this example. This means that a maximum of 2 attempts will be made at an interval of 2000 ms, when running tests with waiting. A complete set of preset configurations can be found here.

    Scripting

    As mentioned above, Karate syntax uses Cucumber based BDD approach. A test case script contains three sections: Feature, Background and Scenario. A single file can contain several scripts at a time:

    • Feature section contains a short description of what will be tested. Multiple lines can be used. This section is obligatory.
    • Background section is optional and the steps inside it will be performed before each script. Variables declared in this section will be global for all scripts and will be initialized before each script is executed. So, if a variable which value was changed in one of the scripts is set in this section, then its value will be rolled back to its initial value in the next script.
    • There must be at least one Scenario section, but there can be a few of them. A scenario describes test cases.
    • If you need to run a DDT test, you can create Scenario Outline section and Examples section for the test values.

    An example of a test case using DDT:

    Example test case using DDT.

    Figure. Example test case using DDT.

    Url and path in Background section are methods implemented inside Karate framework that set the url and path for API queries execution in tests. In this case url is taken from baseUrl global constant specified in karate-config.js. path is set to country.

    Scenario Outline section:

    • Given header x-rapidapi-key = rapidApiKey. A query with a header and the value of rapidApiKey global constant will be run in the test.
    • And param name = ‘<countryName>’. name parameter with the value <countryName> from Examples section will be used in the query.
    • And retry until responseStatus == 200. The test will repeat the query running until it receives a response with a status of 200. Retry settings are stored in karate-config.js file.
    • When method GET. Run a given query using GET method.
    • As a result, a response with the given json is expected. The list of markers that can be used to validate json can be found here.

    An example of writing a test case using a specific configuration

    You can change configuration settings in certain scenarios. These predefined settings will only work for a particular scenario.

    For example: the user needs to check whether protection against DDOS attacks is triggered and a response with code 429 is received, when sending two identical queries in a short period of time.

    An example of the test case described above:

    An example of a test case implementation.

    Figure. An example of a test case implementation.

    In this case, the retry and waiting configuration is overridden in * configure retry = {count: 2, interval: 0}.The query will continue running until it receives a response with code 429. The maximum number of attempts is 2, the interval between attempts is 0 ms.

    Tests run

    To run tests, you need to create a file named *Test.java. In order to launch all the suites, the following must be written in the file:

    Test.java file

    Figure. Test.java file.

    Now when you run the mvn clean test command, all tests will start. The run report will be saved in target/surefire-reports/karate-summary.html file.

    Conclusion

    In this article we considered REST API testing using Karate framework. Thanks to multiple built-in libraries, a Test Automation engineer can close many tasks without having to write Java code. In general, this framework is perfect for teams consisting of specialists who do not know programming languages (manual QA, business analysts, etc.) and should support and conduct test reviews.

    Useful links

    Karate documentation – https://intuit.github.io/karate/