GraphQL Schema Smoke Tests

The GraphQL docs quality problem

GraphQL schemas evolve constantly. Fields get deprecated, types change, arguments are renamed. Documentation query examples break in three silent ways:

# Schema: user.email is deprecated, use user.emailAddress
query GetUser {
  user(id: "123") {
    name
    email       # ← deprecated, docs example still uses it
  }
}

# Schema: createPost(authorId: ID!) — not String
mutation CreatePost($title: String!, $authorId: String!) {
  createPost(title: $title, authorId: $authorId) { id }
}
# ↑ authorId should be ID!, not String!

# Schema: post(id: ID!, locale: String!) — locale is required
query GetPost($id: ID!) {
  post(id: $id) {        # ← missing required locale argument
    title
    content
  }
}

How GraphQL smoke tests will work

Planned configuration

# docsci.yml (planned GraphQL config)
graphql:
  # Schema source (one of):
  schema_url: "https://staging-api.example.com/graphql"  # introspection
  # schema_file: "schema.graphql"                         # SDL file in repo

  # Introspection auth (if needed)
  schema_auth:
    type: bearer
    token_env: GRAPHQL_SCHEMA_TOKEN

  # Validation rules
  check_deprecated: true          # fail on deprecated field usage
  check_types: true               # validate variable types
  check_required_args: true       # flag missing required arguments
  fail_on_deprecated: false       # warn only, don't fail CI
  fail_on_type_error: true        # type errors block merge

  # Optional: live smoke test
  smoke_test: false               # set true to execute queries against staging
  smoke_test_url: "https://staging-api.example.com/graphql"
  smoke_test_auth:
    type: bearer
    token_env: GRAPHQL_API_TOKEN

Sample PR comment output

## ⚠️ DocsCI — GraphQL — docs/reference/users.md:34

**Finding:** Deprecated field `user.email` — use `user.emailAddress` instead.
**Rule:** check_deprecated
**Impact:** warning

```diff
  query GetUser($id: ID!) {
    user(id: $id) {
      name
-     email
+     emailAddress
    }
  }
```

---

## ❌ DocsCI — GraphQL — docs/guides/create-post.md:89

**Finding:** Variable `$authorId` has type `String!` but schema expects `ID!`
**Rule:** check_types
**Impact:** critical — blocks merge

```diff
- mutation CreatePost($title: String!, $authorId: String!) {
+ mutation CreatePost($title: String!, $authorId: ID!) {
```

Timeline