Skip to main content

Hypothesis strategies for GraphQL queries

Project description


Build Coverage Version Python versions Chat License

Generate queries matching your GraphQL schema, and use them to verify your backend implementation

It is a Python library that provides a set of Hypothesis strategies that let you write tests parametrized by a source of examples. Generated queries have arbitrary depth and may contain any subset of GraphQL types defined in the input schema. They expose edge cases in your code that are unlikely to be found otherwise.

Schemathesis provides a higher-level interface around this library and finds server crashes automatically.


hypothesis-graphql provides the from_schema function, which takes a GraphQL schema and returns a Hypothesis strategy for GraphQL queries matching the schema:

from hypothesis import given
from hypothesis_graphql import from_schema
import requests

# Strings and `graphql.GraphQLSchema` are supported
SCHEMA = """
type Book {
  title: String
  author: Author

type Author {
  name: String
  books: [Book]

type Query {
  getBooks: [Book]
  getAuthors: [Author]

type Mutation {
  addBook(title: String!, author: String!): Book!
  addAuthor(name: String!): Author!

def test_graphql(query):
    # Will generate samples like these:
    # {
    #   getBooks {
    #     title
    #   }
    # }
    # mutation {
    #   addBook(title: "H4Z\u7869", author: "\u00d2"){
    #     title
    #   }
    # }
    response ="", json={"query": query})
    assert response.status_code == 200
    assert response.json().get("errors") is None

It is also possible to generate queries or mutations separately with hypothesis_graphql.queries and hypothesis_graphql.mutations.


To restrict the set of fields in generated operations use the fields argument:

@given(from_schema(SCHEMA, fields=["getAuthors"]))
def test_graphql(query):
    # Only `getAuthors` will be generated

It is also possible to generate custom scalars. For example, Date:

from hypothesis import strategies as st, given
from hypothesis_graphql import from_schema, nodes

SCHEMA = """
scalar Date

type Query {
  getByDate(created: Date!): Int

            # Standard scalars work out of the box, for custom ones you need
            # to pass custom strategies that generate proper AST nodes
            "Date": st.dates().map(nodes.String)
def test_graphql(query):
    # Example:
    #  { getByDate(created: "2000-01-01") }

The hypothesis_graphql.nodes module includes a few helpers to generate various node types:

  • String -> graphql.StringValueNode
  • Float -> graphql.FloatValueNode
  • Int -> graphql.IntValueNode
  • Object -> graphql.ObjectValueNode
  • List -> graphql.ListValueNode
  • Boolean -> graphql.BooleanValueNode
  • Enum -> graphql.EnumValueNode
  • Null -> graphql.NullValueNode (a constant, not a function)

They exist because classes like graphql.StringValueNode can't be directly used in map calls due to kwarg-only arguments.


The code in this project is licensed under MIT license. By contributing to hypothesis-graphql, you agree that your contributions will be licensed under its MIT license.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hypothesis-graphql-0.9.1.tar.gz (13.9 kB view hashes)

Uploaded source

Built Distribution

hypothesis_graphql-0.9.1-py3-none-any.whl (15.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page