As well as REST, SOAP and gRPC support, WireMock Cloud has native support for mocking your GraphQL APIs. Out of the box, GraphQL mock APIs will respond with generated mock data for any valid GraphQL queries, and more fine-grained control over response data can be added with ease.

The GraphQL mock API feature is currently in private beta. While this feature is in beta, some WireMock Cloud features are not yet supported by GraphQL. If you would like access to this feature contact us via the Get Support link in the menu bar.

​
Usage

​
Creating a GraphQL mock API

To create a GraphQL mock API, select the GraphQL API template on the mock API creation page and give it a name (and optional custom hostname) of your choosing.

​
Uploading a schema

Once your API is created, the first step to take before you can configure your stubs is to upload a GraphQL schema that describes the operations you want to perform with your mock API. Navigate to your mock API’s GraphQL page and select a schema file from your file system or paste a schema directly into the schema text field.

An example of a very simple GraphQL schema for querying user data is provided below:

type Query {
    user(id: ID): User
    users: [User]
}

type User {
    id: ID
    name: String
    dob: String
    enabled: Boolean
    loginCount: Int
    hobbies: [String]
}

From this page, you can edit your API’s schema at any time.

​
Querying your mock API

Now that your mock API has a schema to work with, it can automatically respond to any valid GraphQL query it receives that matches the schema. The simplest way to start querying your mock API is via the Apollo Sandbox, but any spec compliant GraphQL client will work.

To start querying your mock API using Apollo Sandbox, copy your mock API’s base URL into the sandbox endpoint input.

Once the sandbox is pointing at your mock API, it should pick up the API’s schema and present a helpful interface for constructing queries. Construct a query, either by writing one manually or with the help of the sandbox’s documentation interface, then execute the query. You should see a matching response that contains generated mock data. Executing the query multiple times should return new data each time.

​
Configuring the default GraphQL stub

As we’ve seen, the default behaviour for a GraphQL mock API is to respond to valid queries with automatically generated mock data. This behaviour is defined by a default stub that is added to all GraphQL mock APIs on creation. You can view this stub on the Stubs page of your mock API.

Out-of-the-box, this stub will attempt to serve any HTTP request the API receives, regardless of HTTP method or path. The stub expects a GraphQL query in the request body, in the format outlined by the official GraphQL documentation. If the request query is valid and matches the API’s schema, the stub will respond with a 200 status and a JSON payload with the standard GraphQL response body format.

If you want more control over the format of the data that this default stub generates, there are a few configuration options available for GraphQL’s built-in types.

String and ID values can be configured to always return a fixed value, values with a minimum and/or maximum length, or values that match a given regular expression pattern, such as [A-F0-9]+ (a string of one or more random characters between A and F or 0 and 9) or (enabled|disabled) (either enabled or disabled).

Int and float values can be configured to only return values above a minimum and/or below a maximum. An additional option is available for floats that sets the scale of all float values (i.e. the number of digits to the right of the decimal point). For example, in the number 123.45, the scale is 2. The default scale is 2.

Boolean values can be fixed to always return true or always return false.

Lists can be configured to always return a fixed amount of items. The default is 3.

​
Configuring custom GraphQL stubs

The default GraphQL stub is a great starting point for configuring your mock API, but often we want more control over the data our mock API returns for a given query. That’s where creating and configuring our own stubs comes in. Custom stubs allow your mock API to match on specific GraphQL queries and return static or dynamic responses to those requests.

To match on a specific query, enter a valid GraphQL query into the Match query field of your stub. To return a specific response body, enter this into the Response body field as usual. If you want to return a valid GraphQL response body in JSON format, you’ll need to specify the full JSON, including the root fields (i.e. "data", "errors", "extensions"), as outlined in the GraphQL official documentation. Dynamic response templating is available for GraphQL stubs, like all other API types.

​
Converting request logs to stubs

The simplest way to create a stub with some pre-configured data is to navigate to an existing request in your mock API’s Request Log and click the Convert to stub button at the bottom of the page.

This will create a new stub in your mock API with a query matcher containing the same query that was sent in the original request, as well as a response body that matches the one returned to that request.

From here, you can customize your stub to suit your needs.

​
Current limitations

While GraphQL support is in its beta phase, stubs are limited to a small set of features. Features that will be added to GraphQL stubs soon include:

As well as additional GraphQL specific matchers and template helpers.

If you have feedback or questions on our GraphQL functionality as it evolves, we’d love to hear from you. Please get in touch.