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 application is a validation error.

1.2Returning Mock Data

If @mock is applied to an operation definition (e.g. "Query"), the entire response must be resolved from a mock file.

If @mock is applied to non-root fields only, the client must transform the document to remove any selections which have @mock applied before sending the request to the server. For fields using "variant", mock values are resolved from a mock file. For fields using "value", the mock value is the coerced inline string. When the server’s response is received, the client merges each mock value into the response before yielding to the application.

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.

Mock values must not be generated dynamically at runtime. Mock values must be resolved from the mock file or from the inline "value" argument.

The mechanism for GraphQL clients running in a web browser or mobile client to read the mock file is implementation defined. See: Appendix: Reading Mock Files.

2.1Mock File Location

The mock file must be named {Name}.json, where {Name} is the name of the operation or fragment for 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 № 4{
  "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 № 5fragment 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")
  }
}

Example № 6{
  "basic-bar": {
    "data": "...",
    "__path__": "bar"
  },
  "aliased-bar": {
    "data": "...",
    "__path__": "aliasedBar"
  },
  "basic-qux": {
    "data": "...",
    "__path__": "baz.qux"
  }
}

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.

All mock variant ids within a mock file must be unique; duplicate keys are a validation error.

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 scalar fields. When the field exists in the schema, the coerced value must match the field’s return type.

3.3Nested @mock Validation

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

Counter Example № 7query 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 № 8fragment 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
  }
}

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 № 10GET /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 № 11query Foo($barMock: String, $bazMock: String) {
  bar @mock(variant: $barMock)
  baz @mock(variant: $bazMock)
}

Clients must manually coerce the directive argument variables (similar to CoerceArgumentValues).

This is currently outside the scope of this specification.

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.