How to Test GraphQL

A few months ago I joined a project where suddenly I found myself working with a GraphQL API in addition to a more familiar set of REST endpoints. This was my first acquaintance with GraphQL and I had no idea what it is, what its features are, and, most importantly, how to test it. Let's see where you can start and how I did it on my project.

Before you start testing, you need to understand the basics:

• What is it all about: GraphQL is a query language for APIs and a runtime for these server-side queries.
• What is the workflow: We request data from the client to the server using declarative syntax -> GraphQL generates a payload with a JSON response -> the server sends the payload back to the client.
• Concept and basic terms: Schema, types, query, mutation, resolvers, subscriptions - it would be good to understand all these things.
• GraphQL vs REST: There are several fundamental differences, but most of all we, as testers, will be interested in data fetching and how it works. So, GraphQL allows the client to specify exactly what data he needs in one request, and no additional information is retrieved. Well, the REST API, as a rule, needs to call several endpoints to get what you need. In addition to data fetching, it is worth paying attention to such GraphQL features as types of operations, data types, versioning, and performance.

All this can be found and studied in detail in the official documentation. This will be enough to get you started. So, having sorted out the basics, you can move on to testing.

Get acquainted with the GraphQL Schema and API documentation of our project

A GraphQL schema is a description of data that a client can request from the GraphQL API. It also defines queries and mutations that the client can use to read and write data from the GraphQL server.

Typically, APIs are documented using tools provided by the GraphQL server itself. It describes the schema, queries, and their types, and fields. We are using the GraphQL Playground on the project. With its help, you can study the API documentation, it has a visual document tree, where you can search for information on the required query or mutation.

Learn to use basic tools for invoking queries

To do this, take the same GraphQL Playground or similar IDEs (GraphiQL, Insomnia, etc). The interface of these tools is simple and straightforward. They allow you to work with the API: compose requests, call them and watch the response.

The GraphQL Playground has the same handy features as other IDEs, such as autocomplete and tooltips. This helps a lot when composing a request. If you need to check the response of a request once, then this tool will be enough. The main thing is not to forget to specify the required Headers when requesting and the values of all required fields.

Learn to compose requests

An understanding of the anatomy of a typical GraphQL query will be helpful here.

Understand the following features and take them into account when testing

1. One endpoint with different fillings.
2. The status is always 200 Ok, so we look at the error messages, not the status.
3. The request type is always POST.
4. If we draw an analogy with CRUD (Create, Read, Update, Delete), then the query is R, and mutations are CUD.
5. There are many possible query combinations. Depending on the specifics and business needs of the application, you can check only those requests that the user will perform.

Choose a tool for manual testing

Now you can move on to the selection of tools that will help us in testing, and make it faster and easier.

In addition to the GraphQL IDE to execute the queries that I already mentioned, I liked using the old friend Postman. The new versions have everything you need to test not only REST, but also GraphQL.

Here are the features that Postman has:

• Sending GraphQL queries in the request body as POST
• Support for GraphQL variables
• Import GraphQL schema and simply generate all requests via it
• Autocompletion within the GraphQL query editor

For more details on these features, see the Postman docs.

Choose a tool for test automation

Above, we figured out that GraphQL APIs are called in the same way as REST, but you need to pass query or mutation as the body of the POST request. So there are many suitable tools and you can choose to your taste. In our project, we chose tools for Java. Tried options like Karate and Rest Assured. Both options can be used to test the GraphQL API.

Karate is an easy-to-learn and easy-to-use framework that uses BDD syntax. Great for testing GraphQL APIs as it has features like built-in text manipulation and JsonPath.

Rest Assured is a popular Java API automation framework with a wide community of automators. And while it is geared toward testing REST APIs, it can also be used for GraphQL. But it should be borne in mind that the payload of the request, although very similar to JSON, is still not JSON. Below is a simple implementation where the GraphQL query has been converted to a JSON string format.

Great! There is a working code for a simple test. Everything turned out to be not as complicated as it looked at first glance. 
So how do you test the GraphQL API? Almost the same as REST, using the same tools and basic approaches. The main thing is to know the features and take them into account.