---
id: hypothesis-graphql
version: "0.13.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# hypothesis-graphql — Hypothesis strategies for GraphQL queries

License: permissive · Maintenance: active · Downloads: 2.9M/mo

## What it is and what it does

hypothesis-graphql is a Hypothesis strategy library that generates valid (and optionally invalid) GraphQL queries matching your schema. It integrates with Hypothesis's property-based testing framework to create parametrized test cases with arbitrary query depth and field combinations, helping you find edge cases and error-handling gaps in your GraphQL backend that manual test cases might miss.

The library works by taking a GraphQL schema as input and returning a Hypothesis strategy that produces random but schema-compliant queries. You can customize generation via field restrictions, string encoding options, and custom scalar mappings. It also supports negative testing mode to generate intentionally invalid queries for validating your server's error handling.

Use it for:

- Test a GraphQL API for crashes or unexpected behavior by generating thousands of random valid queries automatically.
- Validate error handling in your GraphQL server by generating invalid queries (wrong types, missing required args, null for non-null fields).
- Restrict query generation to specific fields to focus testing on a particular part of your schema.
- Generate custom scalar values (e.g., dates, UUIDs) that match your schema's domain constraints.
- Discover edge cases in nested query resolution that are unlikely to be covered by hand-written test cases.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Generates arbitrary GraphQL queries matching your schema to use as property-based test cases via Hypothesis, exposing edge cases in your GraphQL backend.

Yes. The package is actively maintained, has no known vulnerabilities, low install friction, and solves a real testing problem—finding edge cases in GraphQL backends through property-based testing. It integrates cleanly with Hypothesis and supports both positive and negative test generation. Recommended for any project with a GraphQL API that needs robust backend validation.

## Install

pip install hypothesis-graphql
uv add hypothesis-graphql
poetry add hypothesis-graphql

## Installing hypothesis-graphql

Before you install: Low friction: pure Python wheel with only two runtime dependencies (graphql-core and hypothesis). Actively maintained with a release 31 days ago and no known vulnerabilities.

License in practice: MIT license (permissive) — you can use this freely in commercial and open-source projects with minimal restrictions.

Quickstart:

from hypothesis import given
from hypothesis_graphql import from_schema

SCHEMA = "type Query { getBooks: [String] }"

@given(from_schema(SCHEMA))
def test_graphql(query):
    # query is a generated GraphQL string
    response = requests.post("http://localhost/graphql", json={"query": query})
    assert response.status_code == 200

Requires Python 3.10 or later.

Verify before relying:

- Whether the library supports all GraphQL spec features (subscriptions, directives, interfaces, unions) or has known limitations.
- Performance characteristics when generating queries against very large schemas.
- Whether custom scalar strategies can handle complex nested types beyond the documented examples.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

graphql query generation testing, hypothesis graphql strategies, property-based testing graphql, graphql schema test data, graphql fuzz testing, graphql negative testing, graphql backend validation, property-based-testing, graphql, fuzz-testing

[View on SkillFed](https://skillfed.io/packages/hypothesis-graphql) · [View on PyPI](https://pypi.org/project/hypothesis-graphql/)