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.

Example № 4query GetBusinessInfo {
  business(id: "123") {
    name @mock(value: "The Great British Bakery")
    rating @mock(value: "4.5")
    isOpen @mock(value: "true")
    hours @mock(variant: "morning-only") {
      open
      close
    }
  }
}

1.2Returning Mock Data

If @mock is applied to the operation’s root field (e.g. "query"), the entire response must be resolved from a mock file. The "value" argument must not be used on operation roots.

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 its executable target.

Mock files should be stored in a __graphql_mocks__ directory adjacent to the source file containing the operation target.

.
├── __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 № 5{
  "5-star-business: {
    "data": {
      "business": {
        "name": "The Great British Bakery",
        "rating": 5.0
      }
    },
    "__appliesTo__": "Query",
    "__description__": "A delicious bakery with a rating of 5.0"
  },
}

Example № 6fragment FooFields on Foo {
  # location resolves to "Foo.bar"
  bar @mock(variant: "basic-bar")

  # location resolves to "Foo.baz"
  baz @mock(variant: "basic-baz") {
    qux
  }
}

Example № 7{
  "basic-bar": {
    "data": "...",
    "__appliesTo": "Foo.bar"
  },
  "basic-baz": {
    "data": { "qux": "..." },
    "__appliesTo": "Foo.baz"
  },
}

2.3Mock Entry Validation

4.1Dynamic Mock Variant IDs

In theory, mock variant IDs may be derived from operation variables. This is neither explicitly disallowed or encouraged.

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 № 9GET /my_page?gql_mock_variants=barMock=some-variant-id;bazMock=some-other-variant-id

Could be used as inputs to the following operation:

Example № 10query 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.

4.2Reading Mock Files

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

This mechanism is implementation defined.

The reference implementation for web serializes the contents of all mock files into a single JSON object, and is embedded on the webpage in a <script> HTML tag.

4.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.