Install & Compatibility
Where this runs
tested against v0.13.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.978s · 26.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.850s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
from_schema
✓ from hypothesis_graphql import from_schema
Main function to create a strategy from a GraphQL schema.
queries
✓ from hypothesis_graphql import queries
Strategy for generating GraphQL queries specifically.
mutations
✓ from hypothesis_graphql import mutations
Strategy for generating GraphQL mutations specifically.
nodes
✓ from hypothesis_graphql import nodes
Contains helpers for generating various GraphQL AST node types, useful for custom scalar strategies.
This quickstart demonstrates how to use `hypothesis-graphql` to generate GraphQL queries based on a schema and then use `requests` to send these queries to a GraphQL endpoint. The `@given(from_schema(SCHEMA))` decorator tells Hypothesis to generate various valid queries for the provided schema, which are then passed to the `test_graphql_api` function. Remember to adapt `GRAPHQL_TEST_ENDPOINT` to your actual server.
from hypothesis import given
from hypothesis_graphql import from_schema
import requests
import os
# Define a simple GraphQL schema
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!
}
"""
# Replace with your actual GraphQL endpoint
GRAPHQL_ENDPOINT = os.environ.get('GRAPHQL_TEST_ENDPOINT', 'http://127.0.0.1:8000/graphql')
@given(from_schema(SCHEMA))
def test_graphql_api(query):
"""Tests a GraphQL endpoint with generated queries."""
print(f"\nGenerated query:\n{query}")
try:
response = requests.post(GRAPHQL_ENDPOINT, json={"query": query})
response.raise_for_status() # Raise an exception for HTTP errors
json_response = response.json()
# Assert no GraphQL errors, unless specifically testing negative cases
if json_response.get("errors"):
print(f"GraphQL Errors: {json_response['errors']}")
# Further assertions can go here based on expected data or error types
assert response.status_code == 200
except requests.exceptions.ConnectionError:
print(f"Warning: Could not connect to GraphQL endpoint at {GRAPHQL_ENDPOINT}. "
"Please ensure your GraphQL server is running.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
raise
# To run the test (e.g., if not using pytest):
# if __name__ == '__main__':
# # Note: Directly calling @given decorated functions runs a single example.
# # For property-based testing, run with pytest.
# print("Running a single generated example. For full property testing, use pytest.")
# test_graphql_api()
Debug
Known issues
gotchaWhen using custom scalar types in your GraphQL schema (e.g., `Date`, `UUID`), `hypothesis-graphql`'s `from_schema` function requires you to provide explicit Hypothesis strategies for generating the corresponding GraphQL AST nodes. Failing to do so will result in errors when trying to generate data for these custom types.fixPass a `custom_scalars` dictionary to `from_schema`, mapping custom scalar names to `hypothesis.strategies` that generate `hypothesis_graphql.nodes` for those types. Example: `custom_scalars={'Date': st.dates().map(nodes.String)}`. affects: All versions
gotchaGraphQL fields are nullable by default. This can hide underlying server errors, as a field might simply return `null` instead of indicating a problem with the data fetching. Explicitly defining fields as non-nullable (`!`) in your schema is crucial for fields that should always return a value, forcing an error if data is missing or invalid. `hypothesis-graphql` will respect these non-null constraints.fixUse non-null types (`Type!`) in your GraphQL schema definition for any fields that must always have a value. This provides stronger guarantees to clients and better error signaling.
affects: All versions (GraphQL specification behavior)
gotchaGraphQL servers typically return an HTTP 200 OK status code even if the GraphQL query itself contains errors (which are then listed in the `errors` field of the JSON response body). Clients consuming your API cannot rely solely on HTTP status codes for error detection, which can be a common footgun in client-side error handling.fixAlways check the `errors` array in the GraphQL response body for any issues, regardless of the HTTP status code. Implement robust error parsing on the client side.
affects: All versions (GraphQL specification behavior)
gotchaWhile GraphQL aims to prevent over-fetching, poorly designed schemas or client queries (especially deeply nested ones or those requesting many fields on large collections) can lead to 'N+1' query problems, excessive database joins, or high query complexity, resulting in performance bottlenecks. `hypothesis-graphql` can generate such complex queries, which may expose these performance issues in your backend.fixImplement query complexity analysis, depth limiting, and proper data loader patterns (e.g., `dataloader-py`) in your GraphQL server to mitigate performance risks. Use `hypothesis-graphql` to stress-test these limits.
affects: All versions (GraphQL schema design issue)
breakingMaking seemingly minor changes to your GraphQL schema's type system can constitute a breaking change for clients, even if data values are compatible. Examples include changing a scalar type (e.g., from a custom `Metadata` scalar to `JSON` scalar, or `String` to `ID`) or removing a value from an enum. GraphQL's nominal typing means clients expecting one type will break on another, regardless of data compatibility.fixCarefully manage schema evolution. For potentially breaking changes, consider deprecating fields/types before removal, or use schema migration tools/strategies (e.g., query rewriting) to maintain backward compatibility. `hypothesis-graphql` can help validate that new schema changes don't inadvertently break existing queries.
affects: All versions (GraphQL schema evolution)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hypothesis_graphql'
The 'hypothesis-graphql' library is not installed in the current Python environment or there is a typo in the import statement.
fixEnsure the library is installed using pip: `pip install hypothesis-graphql`
graphql.error.build_schema.SchemaValidationError: Schema cannot be empty.
The `from_schema` function was called with an empty or invalid GraphQL schema string, which the underlying `graphql-core` library cannot parse.
fixProvide a valid, non-empty GraphQL schema string to `from_schema`, for example: `SCHEMA = """ type Query { hello: String } """ @given(from_schema(SCHEMA))` Expected a Schema, but got <class 'str'>.
The `from_schema` function, or another function expecting a `GraphQLSchema` object, received a plain string instead of a parsed `GraphQLSchema` object. This might happen if you pass a raw schema string directly where an `graphql.build_schema` result is expected by some parts of `hypothesis-graphql` or related libraries.
fixEnsure you are passing a `graphql.GraphQLSchema` object, typically created by `graphql.build_schema(SCHEMA_STRING)`, if the function specifically requires the parsed object: `from graphql import build_schema; SCHEMA_OBJ = build_schema(SCHEMA_STRING); @given(from_schema(SCHEMA_OBJ))`
from hypothesis_graphql import queries
Prior to version 0.12.0, `queries` and `mutations` were top-level imports. In version 0.12.0 and later, they are accessed as attributes of the `hypothesis_graphql` module or via `from_schema` with a `mode` parameter.
fixFor generating specific queries or mutations, use the `from_schema` function with the `mode` argument, or access `hypothesis_graphql.queries` directly: `@given(from_schema(SCHEMA, mode='query'))` or `@given(hypothesis_graphql.queries(SCHEMA))`.
Upgrade
Version history
0.13.1latest on PyPI · released Jul 14, 2026
Audit
Dependencies
hypothesisrequiredCore property-based testing framework that this library extends.
graphql-corerequiredRequired for parsing and working with GraphQL schema objects (e.g., `graphql.GraphQLSchema`).
PythonrequiredMinimum Python version required.