graphql-sonar

GraphQL Sonar

An API testing tool for GraphQL, leveraging code generation based on your schema and operations

The Motivation

When you want to make sure your services are working in production as intended, beyond the scope of your testing infrastructure based on unit and integration tests, you may want to send real queries and mutations against your production deployments, as this is the only way to assert that everything is really working for your users and customers.

While uptime testing tools are great for static queries, with GraphQL, we can leverage the queries we already use for our frontend applications, or write them ourselves to generate everything we need to create robust end-to-end tests that run wherever we need them, whether that is after every deployment or scheduled every day or night, your team is complete in charge of that.

GraphQL Sonar aims to be the connection between your operations and end-to-end tests running against real deployments. As this involves the network layer and all external services you may be using, GraphQL Sonar should only be used for the most important parts, for example sign up and onboarding, auth in general, billing and checkout, and other critical or hot paths.

Focusing on these will give you certainty that your systems are really working, while running as fast as possible, making them suitable to run whenever you wish. For every other case, check out the talk on Testing GraphQL APIs, which goes through different ways you can test your backend services exposing GraphQL APIs.

Getting started

Installing graphql-sonar

yarn install graphql-sonar

Creating or locating your operations

You might already have operations defined when you query your GraphQL API in a frontend application. Usually all queries or mutations are placed in separate .graphql files, which graphql-sonar supports right out of the box. If you're not using the same operations, or if there are none to begin with, you can create some queries right now.

Generating testing code

After creating your operations, graphql-sonar will use the latest schema of your API to validate the operations and generate both type definitions and helper functions for testing in TypeScript.

graphql-sonar \
    --endpoint [URL to your API endpoint] \
    --operations [path or glob to your operation file(s)] \
    --output [optional path where to store the generated output]

Writing tests with the built-in reporter

Now that you generated some types, let's get to writing and running tests!

TBA

Automating test runs

TBA

Examples

TBA

Contributing

TBA