gqltest

GraphQL testing tool

Syntax draft

gqltest provides directives which let you specify the expected behaviour of your test queries directly in your graphql test query files. To accommodate for dynamic values there is support for variables and dynamic string generation.

Test Directives

enum Assertion {
  NOT_NULL
}

union DeepValue = String | Int | Float | Boolean | ID
union Expectation = DeepValue | Assertion
union Variable = DeepValue

directive @before on MUTATION
directive @after on MUTATION
directive @test on MUTATION | QUERY

directive @expect(v: Expectation!) on FIELD
directive @set(v: Variable!) on FIELD

Verify field values

query TestUserQuery @test {
    user {
        name @expect(v: "John Doe")
        email @expect(v: "john@doe.de")
    }
}

Above test expects the result of the query to look like this:

{
  "data": {
    "name": "John Doe",
    "email": "john@doe.de"
  },
  "errors": []
}

Hooks & Test isolation

Use the @before and @after directive to mark certain mutations as hooks. Before a test is executed, all @before hooks from the same directory and all parent directories are executed. After a test the @after mutations will be executed to do cleanup work.

Be aware that all tests are executed in parallel which means that your queries must be written to work isolated.

Imagine an API where a signup mutation exists. It creates a new user account, but will respond with an error if the email is already used for another account.

If we were to create the following hook to setup a user account before a test is executed, we would receive an error from our API. It uses the same email ("john@doe.de") for every account it tries to create.

signup.graphql:

mutation CreateUser @before {
    signup(name: "John Doe", email: "john@doe.de", password: "asdf") {
        name @expect(v: "John Doe")
        email @expect(v: "john@doe.de")
    }
}

To solve this problem we would use a generated variable.

The email could be generated using the $i variable, which represents a number that is unique for each test.

variables.json:

{
  "email": "john{{$i}}@doe.de"
}

The email will be "john0@doe.de" for the first test, "john1@doe.de" for the second, "john2@doe.de" for the third,...

signup.graphql:

mutation CreateUser ($email: String!) @before {
    signup(name: "John Doe", email: $email, password: "asdf") {
        name @expect(v: "John Doe")
        email @expect(v: $email)
    }
}

# Use the same variable remove the account after the test.
mutation RemoveUser ($email: String!) @before {
    removeUser(email: $email) {
        success @expect(v: true)
    }
}

Variables

Variables are declared and initialized in a file called variables.json. They then can be accessed from the graphql files in the same directory and all subdirectories.

variables.json:

{
  "email": "john@doe.de",
  "name": "John Doe",
  "password": "asdf",
  "id": ""
}

userTest.graphql:

mutation CreateUser ($email: String!, $name: String!, $password: String!, $id: String!) @test {
    signup(email: $email, name: $name, password: $password) {
        id @set(v: $id)
    }
}

mutation RemoveUser ($id: ID) @test {
    deleteAccount {
        id @expect(v: $id)
    }
}

In the CreateUser mutation definition the user is registered (and is therefore automatically logged in). Because the user ID is generated by the API, we cannot specify it as a fixed value in the variables.json file. We need the ID to make sure that the deleteAccount mutation returns the correct value.

Using the @set directive we store the id field value in the variable $id.

We can then use said variable to validate the result of the deleteAccount mutation.