GraphQL API mocking with the new WireMock extension

Eiki Hayashi

Creator and maintainer of the GraphQL extension for WireMock

September 19, 2023

Table of Contents

This is some text inside of a div block.

NOTE: This is a guest post by Eiki Hayashi (@nilwurtz on GitHub and @nilwurtz_ on X), the original creator and maintainer of the GraphQL extension for WireMock. See the original version of this blogpost in Japanese here. You can also copy all source codes from the original post

WireMock is a tool for mocking APIs in E2E and other applications. WireMock has a rich matching of URL, query parameters, request body, etc. It can be used for mocking ordinary REST APIs and for protocols based on it (like GraphQL).

However, when creating a GraphQL Mock, there is a problem that it is difficult to match GraphQL queries using WireMock's Matching function alone. This time, in order to solve that problem, I created the WireMock GraphQL Extension, and in this post I will introduce it as it has joined the WireMock organization on GitHub.

GraphQL query matching is difficult

In my work, I ended up using an external GraphQL API, which I also mocked with WireMock and wrote tests. GraphQL queries are sent using HTTP POST, so matching can be done using WireMock's RequestBody Matching, so at first it didn't seem to be much of a problem, but I gradually started to run into problems.

Suppose you want to create a mock API provider for the following GraphQL query: query { hero { name } }. If you write this using WireMock's RequestBody Matching, it will look like the following (you can also use jsonPath matching, etc.):

Sample stub definition for a GraphQL request

In this way, in order to match GraphQL queries, it is necessary to match the query strings as they are. Therefore, if even a single space or line break is wrong, matching will fail, and I have been suffering from this problem for a long time.

New GraphQL extension for WireMock

WireMock has an extension capability that allows you to extend the functionality of request matching. In addition, various functions such as response transforming or request filtering can be extended. This time, I wrote an extension that semantically validates and matches GraphQL queries. Request Matching Extension inherits RequestMatcherExtension and implements it as follows. See the Custom Matching page for more information.

Sample for GraphQL matcher definition (in Kotlin)

If you are interested in the details or the implementation of query normalization, please take a look at the source code. It's a thin extension so you can read it quickly.

Semantic request matching example

The following queries are matched as the same query, regardless of the order. To do that we perform semantic verification after normalizing spaces, etc.

Examples of semantically similar requests

At the same time, the following requests are NOT semantically equivalent, because the “age” field is missing:

Examples of semantically different requests

Using the GraphQL extension from code

It is best to have a look at the README, but I will briefly introduce it here. It should be noted that WireMock Extensions are loaded when WireMock starts, so you need to load the Extension jar. Once you add dependencies on the extension and WireMock, you can do the following:

Using the GraphQL extension in WireMock standalone instances

When using WireMock in Docker, you need to add the Extension JAR file to the WireMock Docker image. It can be done during the build time by extending the existing image, or by mounting the JAR file as a volume:

In the case of standalone WireMock instances, the interface of the extension changes slightly. This is confusing, so we consider unifying it.

Configuring the API stub in a remote WireMock Server

The extension joins the WireMock organization!

I created this extension because GraphQL API mocking was too difficult for work, but WireMock was also strengthening its support for various protocols such as GraphQL. This extension got noticed by the users and maintainers, and recently I received an email with an invitation to post it as a repository in the official WireMock organization on GitHub. I decided to move it. I'm happy to be involved as an engineer in the software that I use in my daily work. I've joined the WireMock organization on GitHub.

We consider general availability of an official GraphQL extension is scheduled to be released beforein the next major release, WireMock 4. Hence, we would appreciate it if GraphQL users could check it out and share feedback. See this GitHub Issue for more information and references.

Please feel free to repost and share your feedback on social media, GitHub issues, etc!