hypothesis-graphql
![License](https://img.shields.io/pypi/l/hypothesis-graphql.svg)
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.
Usage
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
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!
}
"""
@given(from_schema(SCHEMA))
def test_graphql(query):
response = requests.post("http://127.0.0.1/graphql", 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
.
Customization
To restrict the set of fields in generated operations use the fields
argument:
@given(from_schema(SCHEMA, fields=["getAuthors"]))
def test_graphql(query):
...
You can customize the string generation with these arguments to from_schema
:
allow_x00
(default True
): Determines whether to allow the generation of \x00
bytes within strings. It is useful to avoid rejecting tests as invalid by some web servers.codec
(default utf-8
): Specifies the codec used for generating strings. It helps if you need to restrict the inputs to, for example, the ASCII range.
@given(from_schema(SCHEMA, allow_x00=False, codec="ascii"))
def test_graphql(query):
assert "\0" not in query
query.encode("ascii")
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
}
"""
@given(
from_schema(
SCHEMA,
custom_scalars={
"Date": st.dates().map(nodes.String)
},
)
)
def test_graphql(query):
...
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.
License
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.