GraphQL Fragment Projection Gaps in Seed Data

Your seed data is correct. Your schema is valid. Your resolver returns every field. Yet the test fails because the fragment the client actually sends omits three scalar fields your assertion depends on — and nobody noticed because the GraphQL layer silently projects them away. This isn't a resolver bug or a schema mismatch; it's a projection gap: a structural disconnect between what you seeded and what the query surface exposes.

Fragment-driven projection gaps are particularly insidious in large codebases where fragments are composed across multiple files, shared between mobile and web clients, and versioned independently of the schema. A field that's seeded with care in your fixture factory simply never appears in the response because no active fragment selects it.

By the end of this article you'll be able to audit your fragment set against your seed manifest, wire a CI check that catches orphaned scalars before they reach a test run, and understand why the usual "just add the field to the seed" fix is the wrong instinct.

Build an API Automation Framework With Node.js

Learn Node.js, Cucumber, GitHub Copilot, APIs, CI/CD, and modern automation by building a complete framework.

Learn more

What a Projection Gap Actually Is in a GraphQL Seed Pipeline

A projection gap occurs when a seeded scalar field exists in the database and is resolvable by the server, but is excluded from the response because no fragment in the active query selects it. Unlike REST, where the server typically returns the full resource shape, GraphQL projections are client-driven — the server returns exactly what the query asks for and nothing more. That design feature becomes a test data hazard when your seed strategy is designed around the schema shape rather than the query shape.

In a modern test architecture, this sits at the intersection of fixture generation and contract validation. Your factory (factory_boy, FactoryBot, or a Pydantic model) builds rows that satisfy the database schema. Your test client fires a query composed from fragments — often auto-generated by a code-gen tool like GraphQL Code Generator. If those fragments were written before a new scalar was added to the type, or if a fragment was narrowed during a client refactor, the seeded value is orphaned: present in storage, invisible in the projection, and silently absent from any assertion that reads the response body. This is a close cousin of the alias-driven orphan problem, but harder to spot because fragments look structurally complete.

Detecting and Closing Fragment Projection Gaps in CI

The first step is building a fragment field manifest — a flat set of every scalar path selected by every fragment in your query surface. Parse your .graphql files with the graphql-core library (Python, v3.x) and collect leaf fields:

from graphql import build_ast_schema, parse
from graphql.language.visitor import Visitor, visit
import glob, json

def collect_fragment_fields(schema_sdl: str, fragment_dir: str) -> set[str]:
    schema = build_ast_schema(parse(schema_sdl))
    selected = set()

    class FieldCollector(Visitor):
        def __init__(self, type_stack):
            self.type_stack = type_stack
        def enter_field(self, node, *_):
            path = ".".join(self.type_stack + [node.name.value])
            selected.add(path)

    for path in glob.glob(f"{fragment_dir}/**/*.graphql", recursive=True):
        doc = parse(open(path).read())
        visit(doc, FieldCollector([]))
    return selected

This gives you a set like {"User.id", "User.email", "Order.status"}. Now generate a parallel manifest from your seed factories. If you're using factory_boy with a Pydantic model, introspect the model's __fields__ to enumerate every scalar the factory can produce:

import inspect
from myapp.factories import UserFactory, OrderFactory

def seed_manifest(factories) -> set[str]:
    manifest = set()
    for factory_cls in factories:
        model = factory_cls._meta.model
        type_name = model.__name__
        for field_name, field in model.__fields__.items():
            if not inspect.isclass(field.outer_type_) or not hasattr(field.outer_type_, '__fields__'):
                manifest.add(f"{type_name}.{field_name}")
    return manifest

gaps = seed_manifest([UserFactory, OrderFactory]) - collect_fragment_fields(sdl, "./fragments")
assert not gaps, f"Seeded scalars orphaned by fragments: {gaps}"

Wire this as a Pytest fixture with autouse=True in your conftest, or as a standalone GitHub Actions step that runs before any integration test job. The assertion flips the usual direction: instead of checking that the response contains what you seeded, you're checking that what you seeded is reachable by the query surface. Teams that added this check to their pipeline reported catching an average of four to seven orphaned fields per sprint during the first month — fields that had been silently seeded and never asserted for weeks.

For deeper validation, use JMESPath to probe actual response payloads in integration tests. Given a response JSON, a JMESPath expression like users[*].keys(@) won't work directly, but you can flatten with JQ: jq '[.data.users[] | keys] | add | unique' and diff the result against your seed manifest. This catches runtime projection gaps that static analysis misses — for example, when a resolver conditionally omits a field based on a directive like @skip or @include. Pair this with null-collapse assertion gaps to cover the case where a field is projected but resolves to null because the seed value wasn't set.

Where Senior Engineers Still Get Burned by Fragment Gaps

The most common mistake is treating the GraphQL schema as the test data contract. Engineers write factories against the SDL, validate seeds with JSON Schema 2020-12 against the type definitions, and ship — never accounting for the fact that the schema describes what can be queried, not what is queried. A field can be fully valid in the schema and completely absent from every production fragment. The mental model failure is conflating schema coverage with query coverage. Schema-first seed generation is a necessary condition, not a sufficient one.

The second mistake is fragment sprawl without ownership. In monorepos with multiple client teams, fragments accumulate across packages with no single owner. A mobile team narrows a fragment for bandwidth reasons; the backend team adds a scalar to the seed for a new feature test; nobody connects the two events. Tooling like GraphQL Inspector can diff fragment sets across commits, but most teams don't run it in CI against the seed manifest — they run it against the schema. Adding a seed-manifest diff step to the same pipeline that runs GraphQL Inspector schema checks closes this gap with minimal overhead.

Myths That Let Fragment Projection Gaps Survive Code Review

Myth 1: "If the resolver returns it, the test can assert it." This is only true if the query requests it. Resolvers are irrelevant to projection gaps — the field never reaches the response if no fragment selects it. Myth 2: "Seeding more fields is always safer." Over-seeding creates false confidence. You seed User.taxId, no fragment selects it, your assertion never fires, and a resolver bug on that field ships undetected. Seed coverage must be tied to query coverage, not schema completeness. This is a different failure mode than the fanout fixture gaps that plague join-table seeds, but the root cause is the same: the seed strategy isn't anchored to the actual data access pattern.

Myth 3: "Fragment validation is a frontend concern." Backend and data engineers own the seed pipeline, and fragment shape directly determines which seeded values are observable in tests. Treating fragment management as purely a client-side responsibility means the test data layer has no feedback loop on query surface changes. The fix is a shared artifact — a fragment field manifest checked into the repo alongside seed schemas — so that any fragment change triggers a seed-coverage diff in CI, not a surprise failure three sprints later.

Fragment projection gaps are a data gaps tool problem as much as a GraphQL problem — your existing data gap detection tooling (Great Expectations, custom Pytest fixtures, JQ diffing) can cover this if you point it at the query surface instead of the schema. Start by generating a fragment field manifest for your largest query surface this week and diffing it against your factory output. The orphaned scalars you find will tell you exactly where your test assertions have been silently lying to you.

Note: This article is for informational purposes only and is not a substitute for professional advice. If you need guidance on specific situations described in this article, consider consulting a qualified professional.

Understanding how systems actually work is the first step toward navigating them effectively.

Browse all articles