Testing your API with mock data

Use mock data to test your queries and schemas without requiring access to production-level backends or affecting any real data.

Mock data is fake data that mimics the structure and behavior of your real data. API Connect Essentials provides mock capabilities so you can test your GraphQL API even if the backend data sources are not fully functional or available yet.

The following examples illustrate when mocking can be useful:

  • You're working on a frontend that will "plug in" to a GraphQL backend that is not available yet.
  • You want to learn the structure of a GraphQL API but don't need the actual data yet.
  • You want to test your GraphQL APIs without risking inadvertent changes to the real data.

Setting up a mock query inside a schema

Here's an example of a mock query set up inside a schema:

type Spacex_Info @mock {
  ceo: String
  cto_propulsion: String
  cto: String
  employees: Int
  headquarters: Address
}

type Query {
  spacex_info: Spacex_Info
    @graphql(
      endpoint: "https://api.spacex.land/graphql"
      prefix: { value: "Spacex_", includeRootOperations: true }
    )
}

spacex_info now returns mock data, since the type Spacex_Info is mocked. Note that the mock directive's presence means that @graphql will be ignored. When the GraphQL backend becomes available during the development flow, removing the @mock directive will result in data being fetched from the SpaceX GraphQL API defined by @graphql.

query MyQuery {
  spacex_info {
    ceo
  }
}

returns the following result:

{
  "data": {
    "spacex_info": {
      "ceo": "Nunc feugiat mi a tellus consequat imperdiet"
    }
  }
}

About the @mock directive

The @mock directive is a custom directive provided by API Connect Essentials. Use @mock to mock results type by type, so you can create mock queries in your schema. This can be helpful for creating stubs, because you can be sure that the returned value you test will be the same.

API Connect Essentials also makes use of another directive called @mockfn, which works only when @mock is also enabled.

Its general format is the following:

  field: Type @mockfn(name: "functionName" values: [JSON])

The name is the name of the function filling in the mock type. They are listed following this paragraph. Some functions are configured using values, for example with List, values provides the possible values the function can return.

Here is a list of supported functions. The first four functions use values in @mockfn, the rest do not.

  • FutureDate - select a Date up to N days into the future, where N is the first and only value in the list.
  • List - select from the list of values.
  • NumberRange - select a value between the first (lower) and second (upper) values in the list.
  • PastDate - select a Date up to N days into the past, where N is the first and only value in the list.
  • Email - a mocked email address
  • FirstName - a first name
  • LastName - a last name
  • Phone - a phone number
  • SSN - a mocked US social security number
  • City - a mocked city
  • Country - a mocked country
  • CountryCode - a mocked country code (ISO 3166-1 alpha-2)
  • Latitude - a mocked latitude
  • Longitude - a mocked longitude
  • Zip - a mocked US five digit zip code
  • UUID - a mocked UUID
  • DomainName - a mocked domain name
  • DomainSuffix - a mocked domain suffix; for example:org, com
  • IPv4Address - a mocked IPv4 address as a string; for example: 140.186.32.250
  • IPv6Address - a mocked IPv6 address as a string; for example: 2d84:26ad:91c9:b832:42b7:55e7:bf22:e737
  • URL - a mocked URL
  • Username - a mocked username
  • CreditCard - a mocked credit card number; for example: 2229798696491323.
  • Currency - a mocked currency name; for example: Bahamas Dollar
  • CurrencyCode - a mocked currency code (ISO 4217)

PastDate and FutureDate are based on the current time, so the value returned from querying the field will be variable.

The mocked values are coerced to the type of the GraphQL field. This means that non-coercible values will evaluate to null, causing an error for non-nullable types.

Taking the example from the preceding section, the @mockfn directive is applied to the ceo field in the Spacex_Info type.

type Spacex_Info @mock {
  ceo: String @mockfn(name: "LastName")
  coo: String
  cto_propulsion: String
  cto: String
  employees: Int
  founded: Int
  founder: String
  headquarters: Address
}

Now the response will include a mock value.

{
  "data": {
    "spacex_info": {
      "ceo": "Smith"
    }
  }
}

This enables tests and mocks to be written in a more stable way. Again, each query that returns a type that is mocked will be mocked implicitly. This way, you can mock multiple queries at once.