In order to solve some of the limitations of the REST paradigm, Facebook developed GraphQL, a query and manipulation language specifically designed for being used for interfacing with web services. In this article, we will provide a quick overview of GraphQL and explain how it differs from the more traditional REST model.
Moreover, we will provide an overview on how to test GraphQL by exploiting the features provided by Karate, an open source tool for API test automation. To this end, we will summarise the useful suggestions by Luca Pelosi and Angela Distratis (both employed at Hotels.com), during their talk delivered at Codemotion Rome 2019.
What is GraphQL?
As stated before, GraphQL is a query language for APIs, which also includes a server-side runtime for executing queries. Many different programming languages can be used to implement GraphQL services, which works over HTTP like any other REST service or web API. However, there are some fundamental differences between GraphQL and REST.
First, GraphQL allows us to access resources with a single request. This is crucial to avoid overheads due to multiple requests needed to get the full information required, a common issue usually referred as over-fetching.
This problem, and how it is solved by GraphQL, is easily explained by the following example. Imagine that you need to get information about a user, her posts and her followers. With a typical REST API, you will probably need three different requests, according to the following schema:
An alternative choice based on GraphQL would have translated in a single request, as depicted by the following picture:
The previous image also shows the main difference between REST and GraphQL, which is in the syntax. While REST is totally based on HTTP methods, any GraphQL request can be based on a HTTP POST request that includes a plain text query, written according to the query language rules. The GraphQL service then replies with a JSON response, which includes all the required information.
Testing GraphQL services with Karate
While the previous overview is very concise, it helps in understanding how GraphQL services work. However, it is also important to test them and possibly automatise such tests. To this end, Pelosi and Distratis described the main features of Karate, a very interesting open source tool for test automation, which can be easily adapted to GraphQL.
Karate uses the same syntax used for cucumber specification, which is Gherkin. It represents an extremely simplified way to describe tests, without going into many implementation details.
The following example shows how to create a simple test for a REST API.
Here we can see some interesting features of Gherkin syntax and thus Karate. First, it natively supports JSON, as shown when specify the request parameters. Second, it is possible to perform payload assertions with a single line, basically thanks to the == operator.
Using Karate for automating GraphQL tests is thus an interesting option. In the following, we will analyse some of the examples proposed by Pelosi and Distratis during their talk.
Manage the plain text query
Manage the JSON response
In order to verify the JSON response, we can rely on the match statement.
It is important to highlight that white spaces are automatically stripped and also the order of the elements is automatically managed, being not relevant for the matching.
Karate also allows us to use regular expressions in order to verify the response content. The following shows us how to check if a property inside a JSON object (which for the sake of simplicity is defined and stored within a variable) is properly formatted (i.e. contains only 3 uppercase characters):
Karate is an interesting tool to try if you are planning to build and maintain GraphQL services. What we have discussed in this article is just an appetizer of the whole potential provided by Karate. For instance, it also allows us to produce automatic reports, provides mock support and includes a graphical user interface to ease its usage.
As already mentioned, Karate is open source. You can get this tool from GitHub, where you will find a proper documentation, including tutorials and additional examples.