GraphQL Inspector

GraphQL Inspector is a suite of tools for maintaining and enhancing GraphQL APIs and their consumers. Key capabilities include:

• Schema Comparison: Compare two GraphQL schemas to detect changes, with modifications labeled as breaking, non-breaking, or dangerous along with explanations.
• Document Validation: Validate Operations and Fragments against a schema to identify deprecated usage.
• Schema Analysis: Find duplicated types within a schema and generate schema coverage reports based on Operations and Fragments.
• API Utilities: Introspect a GraphQL API and save the result to a file, or serve a GraphQL server with faked data and GraphiQL.

You can integrate these features using the Command Line Tool (CLI), the Programmatic API, or via GitHub (GitHub Application or GitHub Action).

Coverage statistics provide insight into how much of your schema is exercised by your documents:

• Types covered: The percentage of types in your schema that have been covered by your documents.
• Types covered fully: The percentage of types where all fields have been tested.
• Fields covered: The percentage of fields in your schema that have been covered by your documents.
• Total Queries: The total number of queries in your schema that have been tested.
• Total Mutations: The total number of mutations in your schema that have been tested.
• Total Subscriptions: The total number of subscriptions in your schema that have been tested.

To avoid duplicating settings like notifications across every environment, you can define a global configuration at the top level of your YAML file. GraphQL Inspector merges these global settings into each environment.

Conflict Resolution: If a setting is defined both globally and within a specific environment, the environment-specific setting takes precedence (the environment setting wins).

schema: schema.graphql

# Global settings applied to all environments
diff:
  annotations: true
notifications:
  webhook: '<webhook-url>'
  slack: '<global-slack-url>'

env:
  production:
    branch: master
    notifications:
      # Overrides the global slack URL for production
      slack: '<production-slack-url>'
  preview:
    branch: develop
    diff:
      # Overrides the global annotations setting for preview
      annotations: false

GraphQL Inspector attempts to introspect the provided GraphQL endpoint and compares the result with the GraphQL schema from the Pull Request. The behavior depends on the target branch of the Pull Request:

1. Targeting a defined environment branch: If the Pull Request targets a branch defined in your env configuration (e.g., master), GraphQL Inspector introspects the configured endpoint and compares it with the PR schema.
2. Targeting an undefined branch: If the Pull Request targets a branch that is not defined in any of your env settings, GraphQL Inspector falls back to using the local schema file as the source of truth.

Important: When running as a GitHub Action, the endpoint is always treated as the source of truth regardless of the branch.

GraphQL Inspector supports tracking modifications to custom directives across various schema elements, including SCHEMA, SCALAR, OBJECT, FIELD_DEFINITION, ARGUMENT_DEFINITION, INTERFACE, UNION, ENUM, ENUM_VALUE, INPUT_OBJECT, and INPUT_FIELD_DEFINITION.

To use this, ensure both the OLD_SCHEMA and NEW_SCHEMA contain the directive definitions and their usage. The diff command will then categorize changes related to these directives.

# OLD_SCHEMA
input Foo {
  a: String
  b: String
}

# NEW_SCHEMA
directive @foo on INPUT_FIELD_DEFINITION
input Foo {
  a: String @foo
  b: String
}

Version 6.0.0 introduced a major upgrade to the diff command. This update includes changes to:

• Paths
• Severity levels
• Support for directives

Users upgrading from version 5.x to 6.x should review the diff-command package documentation for specific details on how these changes affect their workflows.

You can use GraphQL Inspector in GitHub Actions to get annotations in your Pull Requests. This requires installing the @graphql-inspector/actions package.

Installation:

pnpm add --global @graphql-inspector/actions

Usage: Run the command:

graphql-inspector-github

Configuration Example: Add a graphql-inspector section to your package.json:

{
  "name": "app",
  "scripts": {
    "precommit": "graphql-inspector introspect schema.js --write schema.graphql && git add schema.graphql"
  },
  "graphql-inspector": {
    "diff": true,
    "schema": {
      "ref": "master",
      "path": "schema.graphql"
    }
  }
}

The serve command takes a GraphQL schema and starts a local server that responds to queries using faked data based on that schema. By default, the server runs on http://localhost:4000/graphql.

graphql-inspector serve SCHEMA

You can configure GraphQL Inspector by creating a .github/graphql-inspector.yaml file in your repository or by adding a graphql-inspector key to your package.json (located in the root directory).

YAML Configuration

Create .github/graphql-inspector.yaml:

branch: master
schema: schema.graphql # an output of `$ graphql-inspector introspect ...`

package.json Configuration

Add the following to your package.json:

{
  "graphql-inspector": {
    "branch": "master",
    "schema": "schema.graphql"
  }
}