GraphQL Testing

This topic provides basic information on GraphQL and how to work with it in SoapUI Open Source.

Important: GraphQL testing is available in SoapUI 5.7.0.

About GraphQL

Queries

GraphQL is a query language for getting data from APIs. This language provides a flexible way of getting all the needed data in one request.

How does it work? A request to a GraphQL service contains a query of the needed data. The service gathers all the requested data and forms it in a JSON object. The structure of the object is relevant to the request query, so the client application understands where to get the exact piece of data to work with.

For example, if you need to get customer names, your GraphQL request may look like this:

{
  customers {
    name
  }
}

In this case, the response may look like this:

{
  "data": {
    "customers": [
      {
        "name": "Eddie Griffith"
      },
      {
        "name": "Mea Cousins"
      }
    ]
  }
}

Mutations

A client can also add or modify data on the server. Such a request is called mutation. In this case, the request calls the needed mutation on the server and provides the server with the required fields. The service responses with the modified data. As for a usual query, the mutation request specifies which fields should be returned in the response. For example, the following mutation adds a customer to the service and requests the id of the added customer:

mutation {
  addCustomer(name: "Beulah Glass", email: "[email protected]") {
    id
  }
}

The response may look like the following JSON object. Pay attention to the fact that the response does not contain the name and email of the added customer because is has not been requested.

{ "data": {
  addCustomer: {
    "id": 3
    }
  }
}

Working with GraphQL in SoapUI

Starting from 5.7, SoapUI Open Source supports sending requests to GraphQL services. You can send queries and mutation requests to simulate client interaction and check that your service works as expected.

When you add the requests to a functional test, you use GraphQL Request test step:

You specify a GraphQL query or mutation at the top panel of the Request tab.

In the Query Variables panel, you specify variables. To learn how to use variables in GraphQL, see the GraphQL documentation.

Use property expansions

You can use property expansions for both variables and query or mutation. To insert a property expansion:

1. Right-click within the editor where you want to add a property expansion and use the Get Data context item to select the needed property:

   

2. SoapUI Open Source inserts the required property expansion:

   

Change the method

GraphQL queries support the POST and GET methods. To change the method, select it from the drop-down list at the top:

Note: GraphQL mutations support only the POST method.

Property list

Name	Description
Name	The test step’s name.
Description	Text that describes the test step.
Encoding	The encoding of the request data in the charset header. You can select one of the predefined values or specify a custom value. If it is empty, the utf-8 encoding is used.
Timeout	The number of milliseconds to wait for a server response. If there is no response during this period, the test step fails. 0 (zero) or no value means an infinite waiting time.
Bind Address	The network interface (IP address) through which &product-name; will send the request.
Follow Redirects	Enables handling of redirects. Specify true to allow sending the request to a new address. When it is set to false, the request receives the actual response from the server without going to a new address.
SSL Keystore	The file that stores the private keys used to authorize SoapUI when connecting to the server. This works for HTTPS requests only.
Dump File	Specifies the fully qualified name of the file to which you want to save the server response. Leave this property empty if you don't want to save the response to a file.
Max Size	Specifies the maximum number of response bytes SoapUI Open Source shows in the editor to save memory. To show the entire response, specify 0. Important: The specified assertions may fail if there is not enough data for verification.
Discard Response	When this option in set to true, SoapUI Open Source deletes the response data from memory after the assertion run is over. Works only if the test step editor is closed.

Examples

Use query variables

To specify a query with variables:

1. Declare a variable the query will accept:

   query getCustomer($myId: String) {
     customer (id: $myId) {
       id
       name
       email
     }
   }
   

2. In the Query Variables panel, specify the values of the variables in the JSON format:

   {
     "myId": "1"
   }
   

When you send a request, SoapUI will send the variables along with the query, and a GraphQL service will use the variable values in the query:

Specify a mutation

Mutation is a query that modifies data on the server. In SoapUI Open Source you specify mutations using the regular GraphQL syntax. For example:

mutation {
  editCustomer (name: "John Smith", email: "[email protected]") {
    name
    email
  }
}