Skip to main content

Sample API tests project

This sample demonstrates fundamental API testing with RESTful requests. The sample uses the following base URL: https://sample-web-service-aut.herokuapp.com. To learn more about API testing, you can refer to this document: Introduction to API testing.

Open the sample API test project

To open the API sample project, in Katalon Studio, go to File > New Sample Project > Sample API Tests Project.

Open API sample in Studio

Alternatively, you can download the sample API test project from our GitHub repository: Web Service tests.

Sample API project components

Profiles

To open the execution profile, go to Profiles > default.

Default profile in the API sample

You can create and save all global variables in the execution profile. They can be used across test cases in your project. To learn more about execution profiles and global variables, you can refer to this document: Execution profile and global variables.

Katalon creates three global variables in this sample project as follows:

NameValue
baseURL https://sample-web-service-aut.herokuapp.com
successCode200
globalid0

RESTful requests

We created two sample RESTful requests in this project: a POST request and a GET request. To access the sample RESTful requests, in the Test Explorer panel, go to the Object Repository folder.

Test cases

  1. The POST a new user object

    In this sample POST object, we specify the following information:

    Sample POST request

    • Request method:

      Katalon allows you to choose one of the following methods: GET, POST, PUT, DELETE, PATCH, HEAD, CONNECT, OPTIONS, TRACE. The method needs to match the API endpoint to be a valid request. Here, we create a POST request to send the user information to the server to create an account. The server will return us with a new userID as a response.

    • Request URL:

      Along with the request method, request URL is to tell the web server which API is utilized under test. Any mismatch between method and URL leads to an invalid request exception at runtime or a wrong data response. For the POST request, we specify the API endpoint as follows: ${GlobalVariable.baseUrl}/api/users/json, where the base URL is listed as a global variable. See above: Profiles.

      Request URL in the sample POST request

    • Authorization:

      Authorization is an essential part of an API. It is used to get the correct data under permission (unless the data is public). To learn more about authorization, you can refer to this document: Authorization.

      We don't specify any authorization for this POST request.

    • HTTP Header:

      You can configure the header information needed for sending the RESTful request object. By default, the Content-Type header is automatically generated from the input in the HTTP Body tab. Alternatively, you can select suggested headers from the dropdown list or manually input another header of your interest. To learn more about HTTP headers, you can refer to the Mozilla Developer website here: HTTP headers.

      Here, we want the HTTP header to be automatically generated by the HTTP body.

      HTTP header in the sample POST request

    • HTTP Body:

    Katalon Studio supports the following body data types: text, x-www-form-urlencoded, form-data, and file. To learn more about the types of HTTP body, you can refer to this document: Request body.

    Here, we want to send the user information with dynamic data, including username, password, age, gender, and avatar to the server to create new accounts. To do so, we call variables in the POST object, using the ${<variable_name>} syntax as a placeholder in the HTTP body as follows:

    {
    "age": ${age},
    "avatar": null,
    "gender":"${gender}",
    "password": "${password}",
    "username": "${username}"
    }

    We also check the Auto update Content Type box to automatically generate a HTTP header.

    HTTP body in the sample POST request

    To learn more about setting parameters in a web service object, you can refer to this document: Parameterize a web service object.

    • Verification:

    Katalon Studio allows you to write verification scripts directly in the Verification tab of the web service object. To learn more about the verification snippets, you can refer to this document: Verification snippets.

    Verification in the sample POST request

    • Variables:

    To pass the variables value to the POST request, we specify variables in the Variables tab. Here, we specify the user information, including age, gender, username, and password variables.

    Variables in the sample POST request

    • The Response tab:

    The response is automatically displayed in a neat format: JSON, XML, HTML, and JavaScript. It is helpful for a quick view of the response status.

    Formatter in the sample POST request

  2. The GET user by id object:

    In this sample GET object, we specify the following information:

    Sample GET request

    • Request method:

    For the sample GET request, we are to retrieve the user information by the userID.

    • Request URL:

    To pass the id variable to the GET API, we add the ${<variable_name>} placeholder at the end of the API endpoint. The API endpoint for the GET request is as follows: ${GlobalVariable.baseUrl}/api/users/${id}, with the base URL is listed as a global variable.

    Request URL in the sample GET request

    • Variables:

    We specify the value for the id variable in the Variables tab.

    Variables in the sample GET request

    • Authorization & HTTP Header & HTTP Body:

    We don't specify any authorization, HTTP header, or HTTP body for this sample GET request.

Custom keywords

You can use custom keywords in the test case. To learn more about custom keywords, you can refer to this document: Introduction to custom keywords.

Katalon creates two custom keywords in this sample project. To see the custom keywords, in the Test Explorer panel, go to Keywords > sample > Common.groovy.

Custom keywords in the API project

  • sample.Common.createNewUser

    Description

    This keyword is to:

    • Send the POST request to the server to create an account, then return a userID as the response.
    • Execute verification snippets in the Verification tab of the POST request.
    • Extract the new user ID from the response.

    Parameters

    ParameterTypeMandatoryDescription
    ageintYesThe age of the user
    usernameStringYesThe username for the user account
    passwordStringYesThe password for the user account
    genderStringYesThe gender of the user
    expectedStatusintYesThe expected status code of the request
  • sample.Common.findUserById

    Description

    This keyword is to:

    • Send the GET request to retrieve user information by the userID.
    • Execute verification snippets in the Verification tab of the GET request.

    Parameters

    ParameterTypeMandatoryDescription
    idintYesThe id of the new user
    ageintYesThe age of the user
    usernameStringYesThe username for the user account
    passwordStringYesThe password for the user account
    genderStringYesThe gender of the user
    expectedStatusintYesThe expected status code of the request

Test cases

To access the sample test cases in this project, in the Test Explorer panel, go to the Test Cases folder.

Test cases

There are two test cases for different purposes:

  1. The Create a new user test case is to create a new user. In the test case, we use the sample.Common.createNewUser keyword to:
    • Send the user information, including username, password, age, gender to the server to create an account. Here, we set the value type of username, password, age, gender as Variable. You can change the username, password, age, gender value in the Variable tab. To learn more about test case variables, you can refer to this document: Test Case Variables.

      User information in the variables tab

    • The POST will return a userID as the response.

    • Execute verification snippets in the Verification tab of the POST request.
    • Extract the new user ID from the response.
    Note:
    • If you change the user information in the Variables tab of the test case, make sure to change the verification snippets in the Verification tab of the POST request accordingly for successful verification. For example, if you change the user's age to 10, then make sure to change the verification of the age element to 10.

      A successful verification

    You can see the test script as follows:
    import static com.kms.katalon.core.checkpoint.CheckpointFactory.findCheckpoint
    import static com.kms.katalon.core.testcase.TestCaseFactory.findTestCase
    import static com.kms.katalon.core.testdata.TestDataFactory.findTestData
    import static com.kms.katalon.core.testobject.ObjectRepository.findTestObject
    import com.kms.katalon.core.checkpoint.Checkpoint as Checkpoint
    import com.kms.katalon.core.cucumber.keyword.CucumberBuiltinKeywords as CucumberKW
    import com.kms.katalon.core.mobile.keyword.MobileBuiltInKeywords as Mobile
    import com.kms.katalon.core.model.FailureHandling as FailureHandling
    import com.kms.katalon.core.testcase.TestCase as TestCase
    import com.kms.katalon.core.testdata.TestData as TestData
    import com.kms.katalon.core.testobject.TestObject as TestObject
    import com.kms.katalon.core.webservice.keyword.WSBuiltInKeywords as WS
    import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
    import internal.GlobalVariable as GlobalVariable

    CustomKeywords.'sample.Common.createNewUser'(age as Integer, username, password, gender, 200)
  2. The Find user by ID test case retrieves user information via an userID. The flow is as follows:
    • First, we use the sample.Common.createNewUser keyword to:

      • Send the user information, including username, password, age, gender to the server to create a new account. Here, we set the value type of username, password, age, gender as Variable. You can change the username, password, age, gender value in the Variable tab.
      • The POST request returns a userID as the response.
      • Execute verification snippets in the Verification tab of the POST request.
      • Extract the new userID from the response.
    • Then, we use the sample.Common.findUserById keyword to:
      • Send the GET request to retrieve the user information via the newly created userID.
      • Execute verification snippets in the Verification tab of the GET request.
      Note:
      • If you change the user information in the Variables tab of the test case, make sure to change the verification snippets in the Verification tab of the POST and GET requests accordingly for successful verification. For example, if you change the user's age to 10, then make sure to change the verification of the age element to 10.

        A successful verification

      You can see the test script as follows:
      import static com.kms.katalon.core.checkpoint.CheckpointFactory.findCheckpoint
      import static com.kms.katalon.core.testcase.TestCaseFactory.findTestCase
      import static com.kms.katalon.core.testdata.TestDataFactory.findTestData
      import static com.kms.katalon.core.testobject.ObjectRepository.findTestObject
      import com.kms.katalon.core.checkpoint.Checkpoint as Checkpoint
      import com.kms.katalon.core.cucumber.keyword.CucumberBuiltinKeywords as CucumberKW
      import com.kms.katalon.core.mobile.keyword.MobileBuiltInKeywords as Mobile
      import com.kms.katalon.core.model.FailureHandling as FailureHandling
      import com.kms.katalon.core.testcase.TestCase as TestCase
      import com.kms.katalon.core.testdata.TestData as TestData
      import com.kms.katalon.core.testobject.TestObject as TestObject
      import com.kms.katalon.core.webservice.keyword.WSBuiltInKeywords as WS
      import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
      import internal.GlobalVariable as GlobalVariable
      import groovy.json.JsonSlurper as JsonSlurper
      import com.kms.katalon.core.testobject.RequestObject as RequestObject
      import static org.assertj.core.api.Assertions.*

      int id = CustomKeywords.'sample.Common.createNewUser'(age as Integer, username, password, gender, 200)

      CustomKeywords.'sample.Common.findUserById'(id, age as Integer, username, password, gender, 200)

Data Files

To view the data files in this sample project, in the Test Explorer panel, go to Data Files > ListUser.

Data files in the API sample

Alternatively, you can go to <your-project-folder>\Data Files and choose the file you want to open:

  • ListUser.dat is the .dat file of the ListUser.xlsx file.
  • ListUser.xlsx is an excel file that contains the user information.

Test suites

The sample test suite demonstrates the web service testing with data-driven testing. To view sample test suite, in the Test Explorer panel, go to Test Suite > web-service-tests - All Test Cases.

This test suite includes the Create a new user and Find user by ID test case. We bind the Create a new user test case with the ListUser data file. To view the data binding section, select the Create a new user test case, then click Show Data Binding. To learn more about binding data, you can refer to the following document: Data Binding.

Sample test suites

Execute selected test cases or test suites

To execute a test case or a test suite in the sample project:

  1. Select the test case/test suite you want to execute.
  2. Click Run or press Ctrl + Shift + A (macOS: Cmd+Shift+A).

    You can choose different browsers to execute your test in the dropdown list next to Run.

    Run the test case

  3. Observe the test result in the Log Viewer tab.

    Oservice results in the log Viewer

    Note:
    • You can view test results of the test suite in the Result tab. The test results can be Passed, Failed, Error, or Incomplete.
    • After executing test suites or test suite collections, you can view your reports and details in <your-project-folder>/Reports. Katalon Studio also supports exporting test reports into different formats, such as HTML, CSV, PDF, and JUnit.
    • For real-time monitoring and better reporting capabilities, consider integrating your project with Katalon TestOps. Learn more about test result reports here: Upload Test Results to Katalon TestOps from Katalon Studio. See also
    See also: