pytest-graphql

The GraphQL test client for Python whose calls are built from the schema and checked against it before they are sent.

A test names an operation, and the client chooses the fields to ask for. A test has no query text, and a schema change does not mean editing query strings by hand.

Documentation: https://skhomenko.github.io/pytest-graphql/

Use it when

• You test a GraphQL API from Python, over HTTP, against a server that is running.
• You want a wrong operation, argument or field name to fail before any request is sent, with a message that names the closest correct one.
• Your schema changes often, and you do not want to edit query strings in tests.
• A coding agent writes or updates your GraphQL tests.
• You want a failed test to show its calls and a curl line that repeats the failed call.

Do not use it when

• Your API is REST. Use an HTTP client or a test tool made for REST.
• You write production client code. Use a general GraphQL client library.
• You need a mock GraphQL server. This package calls a server that you have. Use a mock server tool to fake one.
• You want to fuzz every operation of an API. Use a dedicated property-based API fuzzer.

Quickstart

Install the package with its pytest extra:

pip install "pytest-graphql[pytest]"

Tell pytest where your GraphQL endpoint is:

# pytest.ini
[pytest]
gql_url = http://localhost:8000/graphql

Write a test. The gql fixture is a client that has already read your schema:

def test_user_has_a_name(gql):
    user = gql.query("user", id="u1")
    assert user.name == "Ada Lovelace"

Run pytest. The client chooses the fields to ask for, so the test contains no query text.

A fuller example

def test_a_new_post_has_the_title_that_was_sent(gql):
    payload = gql.fake.CreatePostInput(author_id="u1")

    post = gql.mutation("createPost", input=payload)

    assert post == gql.expect.Post(title=payload["title"])


def test_a_user_with_the_fields_that_the_test_needs(gql):
    user = gql.query("user", id="u1", fields=["id", "name", {"team": ["name"]}])

    assert user == gql.expect.User(name="Ada Lovelace", team={"name": "Core"})


def test_an_update_of_a_missing_user_fails(gql):
    with gql.expect_error(path=["updateUser"]):
        gql.mutation("updateUser", id="missing", name="Ada", fields=["id"])

API at a glance

Compared with other tools

Features

• Fields chosen for you. Auto-selection builds the selection set from the schema, and fields= takes over when you need exact fields. Selections
• Responses that read like Python. Attribute access, snake_case names, lists with helpers, and an error for a field that is not there. Responses
• Assertions with a readable diff. Plain assert, partial matchers such as gql.expect.User(...), and list helpers. Assertions
• Errors that raise. A response with errors raises, and gql.expect_error() is for the test that expects one. Errors
• Seeded fake input. gql.fake.<InputType>() repeats from run to run, and unique() marks a field that must differ. Factory
• Identity. Clone a client as another user, write your own Auth, and refresh a token. Authentication
• Polling. gql.wait_until() repeats a query with a deadline and a backoff. Polling
• Reports with the calls in them. A failed test lists its calls, hides the headers and variables that you list as secrets, and ends with a curl line that repeats the failed call. Diagnostics
• Open to change. Replace the transport, load the schema from a file, register custom scalars, add middleware, or use one of six pytest hooks. Extending
• No pytest needed. The core imports no pytest. build_client() works in unittest, in scripts and in a shell. Using without pytest
• Parallel runs. The plugin works with pytest-xdist. Cookbook

More documentation

• Why pytest-graphql?: what the package changes, and how it compares with other approaches.
• Using with coding agents: rules to paste into AGENTS.md or CLAUDE.md, and a skill file.
• Configuration: every option, flag and environment variable, and which one wins.
• Migrating from a hand-rolled client
• FAQ
• API reference
• Changelog

Install

pip install pytest-graphql

The required dependencies are graphql-core, httpx and certifi. pytest is optional, so the client can be used outside a test suite. Add the extra when you use the plugin:

pip install "pytest-graphql[pytest]"

Supported versions

Python 3.10 through 3.14, graphql-core 3.2 and 3.3, and pytest 7.4 or newer when the pytest extra is installed. CI tests a representative sample of that range rather than the whole cross product.

Status

Version 0.x. The API may change between minor versions, and the changelog records every change. An on-disk schema cache, async clients, subscriptions and file uploads are not part of 0.1.x.

License

MIT. See https://github.com/skhomenko/pytest-graphql/blob/main/LICENSE