GraphQL in Katalon Studio

This article provides basic information on GraphQL and how to work with GraphQL in Katalon Studio.

Important:

• Katalon Studio version 8.4.0 onwards.

What is GraphQL?

GraphQL is a query language that allows API consumers to write queries to get the exact data they need from a single request to a single endpoint. GraphQL provides a detailed and easy-to-understand description of the data in your API, making it easier to evolve APIs over time. GraphQL queries get many resources in a single request and always return predictable results. Therefore, GraphQL significantly improves the efficiency and performance of API calls.

To learn more about GraphQL, you can refer to GraphQL documentation: Introduction to GraphQL.

GraphQL testing in Katalon Studio

With this GraphQL testing in Katalon Studio, you can:

• Create a GraphQL test request with RESTful by GET and POST methods, using queries or mutations.
• Use query variables in a GraphQL request.
• Validate GraphQL request and response against schemas.

Queries and mutations

The most typical GraphQL operations from the perspective of the client are queries and mutations. In terms of the CRUD model (create, read, update, and delete), a query is identical to read, using the GET method. Mutations handle all of the others, which are create, update, and delete.

Testing mutations are essential as it involves testing data access and additions to databases. Mutations modify data in the database and return us a value. Mutations can edit and manipulate the data from the server side.

There are two ways to execute a GraphQL request with RestFUL in Katalon Studio: GET and POST methods. You can put the GraphQL query into the GET query parameter to create a GraphQL test request. GraphQL mutations only support the POST method.

Validate GraphQL request and response against a schema

Since GraphQL returns a response in JSON format, you can validate a GraphQL response against a JSON schema. This action also helps you troubleshoot the error without the HAR file.

You can also validate a GraphQL request body against a GraphQL schema to make sure the request is valid before sending the request to the server. The validation action happens on the server side. You receive the validation results in the Response section if you use keywords in the Verification tab or the Log Viewer if you use keywords in a test case.

Sending GraphQL queries using Query Parameters

This section shows you an example of how to send GraphQL queries using Query Parameters. To learn more details about Query Parameters, you can refer to this document: Parameterize a Web Service Object.

In this example, we want to get country information from the https://countries.trevorblades.com website. Do as follows:

1. Create a Web Service Request object and choose the Request Type as RESTful.
   
2. In the Web Service Request object editor, choose the GET request method.
3. In the URL field, input this GraphQL URL: https://countries.trevorblades.com/graphql?query=query Query { country(code: "VN") { name native capital emoji currency languages { code name } }}
   Katalon Studio detects the query parameters after the question mark and lists them in the Query Parameters table like below:

   • Name: query
   • Value: query Query { country(code: "VN") { name native capital emoji currency languages { code name } }}
4. Save your request, then click Test Request and Verify.
   Note:

   • In case the Test Request and Verify button is unresponsive, clear and re-paste the URL then click it to send the request again.

In the Response tab, the country information is returned as JSON responses.

Sending GraphQL queries and mutations in the HTTP Body

POST requests usually use the application or JSON content type in the HTTP Body. To send a GraphQL query in the HTTP Body, do as follows:

1. Create a Web Service Request object and choose the Request Type as RESTful.
2. In the Web Service Request object editor, choose the POST request method.
3. In the URL field, input the GraphQL endpoint URL.
   For example: https://katalon-sample-graphql-aut.herokuapp.com/graphql
4. Switch to the HTTP Body tab and choose the GraphQL body type.
5. In the Query textbox, insert your GraphQL query or mutation.
   GraphQL query example:

   query {
   findAllBooks {
       id
       title
       isbn
       pageCount
       author {
           id
           firstName
           lastName
       }
     }
   }

   GraphQL mutation example:

   mutation {
       deleteBook(id:3)
   }
6. Save your request, then click Test Request and Verify.
7. View the result in the Response tab.

Below are some examples of using GraphQL queries and mutations in the test request object:

• Find all books using a GraphQL query

• Create a new book using a GraphQL mutation

• Modify the name of a book using a GraphQL mutation

• Delete a book using a GraphQL mutation

Add a GraphQL request to a test case

You can add a GraphQL request into a test case. Katalon Studio generates a script that has send request method with a map of variables. Below is a sample test script generated:

res = WS.sendRequest(findTestObject('Country/CountryQueryVarsInVars', [('id') : 'US']))

println CustomKeywords.'util.JSON.jsonBeautify'( res.getResponseBodyContent());

Save and run your test case. You can view the result of sending the request in the Log Viewer tab.

Use GraphQL variables

Attention:

• At the moment, the GraphQL variables feature is not working on Katalon Studio.

You can refer to two (2) workarounds as an alternative as below:

• Use Global Variable as a temporary value.

• Define the value and then use it directly in the body.

Use Global Variable

Follow these steps to use Global Variable as a temporary value.

1. Create a Web Service Request object and choose the Request Type as RESTful.
2. In the Web Service Request object editor, choose the POST request method.
3. In the URL field, input this GraphQL URL: https://countries.trevorblades.com.
4. Add or create a Global Variable with your defined value.

   For more detailed steps, refer to the following topic: Validate GraphQL request and response against schemas.

   Here is an example after adding Global Variables:

   
5. In the Query textbox, insert your GraphQL query.

   In your GraphQL query, input ${id} syntax, which is used to reference the value of a variable in the variable tab.

   
6. Navigate to the Variables tab and specify details for the variable.
   1. Click Add, a new row is added to the variable list.
   2. Define the variable name: id, the type: Global Variable, the default value: GlobalVariable.id in our case.
   

Below is the result of our example using the Global Variable. You use GlobalVariable.id, which is equal to AU according to your Global Variables profile, hence, Australia's information is returned as JSON responses.

Define and use the value directly

You can input values directly into the query body for a single query.

Validate GraphQL request and response against schemas

To validate a GraphQL request body and the response returns against schemas, do as follows:

1. Create a GraphQL web service request object.
2. In the web service request object editor, switch to the Verification tab.
3. In the Verification snippets, use the WS.validateGraphQLBodyAgainstSchema with the request body and a schema. See [WS] Validate GraphQL request body against a GraphQL schema.
   The response returns as the JSON format, so you can also add the WS.validateJsonAgainstSchema to validate the response. See [WS] Validate the response against a JSON schema.
   For example:

   import static org.assertj.core.api.Assertions.*
   
   import com.kms.katalon.core.model.FailureHandling
   import com.kms.katalon.core.testobject.RequestObject
   import com.kms.katalon.core.testobject.ResponseObject
   import com.kms.katalon.core.webservice.keyword.WSBuiltInKeywords as WS
   import com.kms.katalon.core.webservice.verification.WSResponseManager
   
   import groovy.json.JsonSlurper
   import internal.GlobalVariable as GlobalVariable
   
   RequestObject request = WSResponseManager.getInstance().getCurrentRequest()
   
   ResponseObject response = WSResponseManager.getInstance().getCurrentResponse()
   
   WS.validateGraphQLBodyAgainstSchema(request, "Schema/Country.qls", FailureHandling.CONTINUE_ON_FAILURE)
   
   WS.validateJsonAgainstSchema(response, "Schema/JSON/CountrySchema.json", FailureHandling.STOP_ON_FAILURE)
4. Save and click Test Request and Verify.

You can view the validation result in the Response section.

You can also validate the GraphQL request/ response against schemas in a test case and view the validation result in the Log Viewer. For example:

Sample script:

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 static com.kms.katalon.core.testobject.ObjectRepository.findWindowsObject
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.testng.keyword.TestNGBuiltinKeywords as TestNGKW
import com.kms.katalon.core.testobject.RequestObject
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 com.kms.katalon.core.windows.keyword.WindowsBuiltinKeywords as Windows
import internal.GlobalVariable as GlobalVariable
import org.openqa.selenium.Keys as Keys

RequestObject req = findTestObject('Country/CountryQuerySchema');
if (WS.validateGraphQLBodyAgainstSchema(req, "Schema/Country.qls")) {
	res = WS.sendRequest(findTestObject('Country/CountryQuerySchema'))
	WS.validateAgainstJsonSchema(res, "Schema/JSON/CountrySchema.json")
}