Network-layer mocks vs. local schema-mirroring for integration testing

Answer

In continuous‑integration pipelines, running a local GraphQL server generated from the latest schema snapshot offers stronger protection against breaking schema changes than static network‑layer mocks. It validates query syntax, field nullability, and resolver contracts against an actual schema, surfacing incompatibilities before code reaches production.

Why Schema‑Mirroring Wins

• Queries are parsed against a real schema, so rename or type changes cause compile‑time failures.
• Nullability mismatches surface immediately because the server enforces the SDL’s non‑null constraints.
• Resolver stubs can be exercised, revealing missing or mis‑typed fields that mocks would otherwise hide.

Network‑layer mocks, while fast and deterministic, only validate the shape of the mocked payload. If the production schema evolves—say a field becomes non‑nullable or is renamed—the mock can still return the old shape, causing tests to pass while runtime errors surface in production.

Keeping Mocks In Sync Without Introspection

Because introspection is often disabled in production, mock synchronization must rely on an external, versioned schema artifact. A minimal, repeatable process looks like this:

1. Publish a Schema Artifact
   Every release that changes the GraphQL SDL should push the updated schema.graphql (or JSON introspection result) to a shared artifact store (e.g., Git tag, S3 bucket, or package registry). Include the semantic version in the filename.
2. Enforce Version Pinning in CI
   Add a step that pulls the latest artifact and compares its version against the one used by the test suite. Fail the build if the test suite is using a stale artifact.
3. Generate Mocks from the Artifact
   Use a tool that can produce mock responses directly from the SDL—such as graphql-codegen --config mocks or a custom script. This guarantees that the mock data model matches the current schema.
4. Run Contract Tests
   In addition to schema validation, execute a small set of contract tests that send real queries to the mocked server and assert that the response shape matches the SDL. This catches cases where the mock generator missed a non‑null field or a renamed type.
5. Periodic Drift Checks
   Schedule a nightly job that pulls the current production schema (via a secure gateway or a snapshot stored by the deployment team) and diffs it against the published artifact. If differences are found, alert the team and block the next release until the artifact is updated.

When to Prefer Network Mocks

Network mocks are still useful when you need to emulate production‑specific behaviors that a mirrored server cannot reproduce, such as rate‑limiting, authentication errors, or data‑dependent resolver logic. In those cases, combine the two approaches: use a schema‑mirrored server for structural validation and layer a mock adapter that injects the runtime behaviors you want to test.

Missing Diagnostic Detail

Do you currently publish a versioned schema artifact with each release, or is the schema only available in the source repository? The presence or absence of an artifact will influence how tightly you can enforce the synchronization steps above.