1.1Arguments

@mock accepts two mutually exclusive arguments: "variant" and "value". Exactly one of these arguments must be provided. Providing both "variant" and "value" in the same @mock directive is a validation error.

1.2Transforming Operations

Operations must be transformed to remove any selections which have @mock applied before sending the request to the server. The client must insert a mock value in each corresponding position before yielding a response to the application.

If every selection in a SelectionSet uses @mock, the parent that contains that SelectionSet must be removed:

• If the parent is a field or inline fragment, remove it from the operation.
• If the parent is a fragment definition, remove the definition and all of its corresponding fragment spreads.

After removing mocked selections, if an operation variable is no longer referenced by any remaining selection, the variable definition must also be removed from the operation. An unreferenced variable would produce an invalid document per the All Variables Used rule.

When @mock is applied to a field, the mock value must always be included in the response, regardless of other directives present on the same field. In particular, @mock takes precedence over @skip and @include — the mock data is always returned, irrespective of whether the field would otherwise be skipped or included based on those directives’ conditions.

If @mock is applied to an operation definition (e.g. "query"), the entire response must be resolved from a mock file. No request should be sent to the server.

Example № 4fragment FooFields on Foo {
  foo @mock(value: "foo!")
  bar
}

fragment MoreFooFields on Foo {
  baz @mock(value: "baz!")
}

query GetFoo($id: ID!, $planet: String!) {
  foo(id: $id) {
    id
    ...FooFields
    ...MoreFooFields
    ... on Foo { baz @mock(value: "baz!") }
    sayHello(planet: $planet) @mock(value: "hello world")
  }
}

Example № 5fragment FooFields on Foo {
  bar
}

query GetFoo($id: ID!) {
  foo(id: $id) {
    id
    ...FooFields
  }
}

2.1Mock File Location

The mock file must be named {Name}.json, where {Name} is the name of the operation or fragment within which the mock values may be used.

To avoid mock file naming collisions, this specification requires that all operation and fragment names within a project are unique.

The mock file must be stored in a directory named "__graphql_mocks__" adjacent to the source file containing the operation or fragment.

.
├── __graphql_mocks__
│   └── GetBusinessInfo.json
└── BusinessDetails.graphql

2.2Mock File Structure

The mock file contains a JSON object which maps mock variant id keys to a mock variant.

A mock variant id is any key in the object that does not start with two underscores (__).

A mock variant is the object associated with each mock variant id.

Example № 6{
  "mock-id": {
    "data": {
      "business": {
        "name": "The Great British Bakery",
        "rating": 5.0
      }
    },
    "__path__": "Query"
  }
}

Counter Example № 7{
  "mock-id": {
    "data": {
      "data": {
        "business": {
          "name": "The Great British Bakery",
          "rating": 5.0
        }
      }
    },
    "__path__": "Query"
  }
}

Example № 8{
  "5-star-business": {
    "data": {
      "business": {
        "name": "The Great British Bakery",
        "rating": 5.0
      }
    },
    "__path__": "Query",
    "__description__": "A delicious bakery with a rating of 5.0"
  }
}

Example № 9fragment FooFields on Foo {
  # field path is "bar"
  bar @mock(variant: "basic-bar")

  # field path is "aliasedBar"
  aliasedBar: bar @mock(variant: "aliased-bar")

  baz {
    # field path is "baz.qux"
    qux @mock(variant: "basic-qux")
  }

  # field path is "greeting"
  greeting @mock(variant: "basic-greeting") {
    salutation
    planet
  }
}

Example № 10{
  "basic-bar": {
    "data": "...",
    "__path__": "bar"
  },
  "aliased-bar": {
    "data": "...",
    "__path__": "aliasedBar"
  },
  "basic-qux": {
    "data": "...",
    "__path__": "baz.qux"
  },
  "basic-greeting": {
    "data": {
      "salutation": "...",
      "planet": "..."
    },
    "__path__": "greeting"
  }
}

3.1Mock File Validation

If a mock variant id referenced by a "variant" argument does not exist in the mock file, this is a validation error.

Each mock variant id within a mock file must be unique; duplicate keys trigger a validation error.

The "__path__" of each mock variant must correspond to a valid field path within the operation or fragment associated with the mock file.

GraphQL clients must raise an error for an invalid mock value defined inside a mock file.

A mock value is valid when its shape is compatible with the operation’s selections at the field path where @mock is applied. For each selected field, the mock value must satisfy CompleteValue() for the field’s schema type. Fields present in the operation but not defined in the schema are skipped during validation.

3.2Inline Mock Value Validation

The "value" argument may only be used on leaf fields (scalars and enums). When the field exists in the schema, the coerced value must match the field’s return type.

3.3No Nested @mock Validation

@mock must not be used on a field that is a child of another field which also uses @mock:

Counter Example № 11query Foo {
  bar @mock(variant: "bar-fields") {
    # ❌ Validation error: @mock on baz is nested inside @mock on bar
    baz @mock(value: "hi from baz")
  }
}

This rule extends across fragment boundaries. FragmentSpread nodes must be recursively expanded:

Counter Example № 12fragment FooFields on Foo {
  # ❌ Validation error: @mock on bar would be nested inside MockedFoo
  bar @mock(value: "baz")
}

query UnmockedFoo {
  foo {
    ...FooFields
  }
}

query MockedFoo {
  foo @mock(variant: "foo-fields") {
    ...FooFields
  }
}

3.4No Empty Operation Root Validation

An operation’s root SelectionSet must contain at least one selection that does not use @mock. If every selection in the operation’s root SelectionSet is mocked, the transformed operation would contain an empty SelectionSet, which is not valid GraphQL.

Counter Example № 13# ❌ Validation error: all top-level fields are mocked
query GetBusiness {
  business(id: "123") @mock(variant: "bakery") {
    name
    rating
  }
}

5.1Dynamic Mock Variant IDs

The "variant" argument could be passed in from operation variables.

A use case would be to build an interface to let viewers control which mock value is used. For example, the following GET parameters:

Example № 15GET /my_page?gql_mock_variants=barMock=some-variant-id;bazMock=some-other-variant-id

This could be mapped to operation variables for the following operation:

Example № 16query Foo($barMock: String, $bazMock: String) {
  bar @mock(variant: $barMock)
  baz @mock(variant: $bazMock)
}

GraphQL servers resolve variable references in arguments during execution via CoerceArgumentValues(), but this does not happen on the client. Clients that support variable references in @mock arguments must implement their own coercion of directive argument variables.

5.2Reading Mock Files

GraphQL clients that implement this specification must have access to the data contained in mock files when requests are executed. Since web browsers and mobile applications cannot read remote file systems, a mechanism is required to make the data contained in mock files available to the client.

This mechanism is implementation-defined.

5.3Schema-Aware Clients

Schema-aware clients face additional complexity: operations using the @mock directive may reference types and fields not yet present in the server schema. Such clients must patch their local schema to include these definitions, or disable validation for mocked operations. The mechanism for schema patching is outside the scope of this specification, however contributions addressing this are welcome for inclusion in a future version of this document.

5.4Trusted Documents

Clients that use trusted documents register a hash of each operation at build time and send only that hash at runtime.

The document that is hashed must be the result of TransformOperation. The same transformation must be applied at both build time (when computing the hash) and at runtime (when preparing the request).