WireMock Now Has an Official Spring Boot Integration

Today we're pleased to announce that WireMock has officially adopted the Spring Boot integration originally developed by the super-talented Maciej Walkowiak (who remains involved in maintaining it). Here’s what you need to know ↘️

Why an Official Spring Boot Integration Matters

WireMock has long been a favorite tool for mocking HTTP APIs in development and testing environments. However, integrating it into Spring Boot projects required additional boilerplate code. Developers often found themselves writing repetitive setup logic and dealing with fixed port numbers for mock servers, which could be cumbersome in dynamic and containerized environments.

The official Spring Boot integration resolves these challenges by embedding WireMock directly into Spring. With annotation-driven configuration and automatic management of resources, the integration enables simple, declarative configuration of mocked API. Now, developers can focus on building and testing their applications without worrying about mock server setup and maintenance.

Key Features of the WireMock Spring Boot Integration

1. Supports WireMock’s Jetty 12 Build

An addition to the latest release of the integration is support for WireMock’s Jetty 12 build. This allows developers to depend on WireMock’s thin jetty12 JAR instead of relying on the much larger standalone JAR.

This can significantly benefit teams who want to keep their dependency downloads at a manageable size.

2. Annotation-Driven Provisioning of WireMock Instances

The integration allows developers to create and configure WireMock instances using annotations. This feature enables quick and clean setup of one or more mock servers directly in the application’s test context.

For example, you can define a WireMock instance in your test class like this:

SpringBootTest(classes = MyAppConfiguration.class)
@EnableWireMock
class MyTest {

 @InjectWireMock
 private WireMockServer wm;

 // tests

With just a few lines of code, the integration handles the creation, configuration, and lifecycle management of the mock server.

3. Support for Extension Factories via Configuration Annotation

The latest version of the integration introduces the ability to load extension factories using a configuration annotation. This simplifies the process of incorporating WireMock extensions like gRPC or other custom plugins.

For example, loading WireMock’s gRPC extension now requires only a single parameter in your configuration, e.g.:

@EnableWireMock({
       @ConfigureWireMock(
               extensionFactories = {Jetty12GrpcExtensionFactory.class}
       )
})

4. Dynamic Port Allocation and Property Exposure

One of the most common pain points in mock server testing is managing port conflicts.

WireMock can dynamically assign port numbers to reduce the likelihood of this. However, this then requires injecting the  port number into the base URL of the HTTP client within the Spring Boot app, which isn’t straightforward.

The WireMock Spring Boot integration elegantly addresses this by exposing WireMock’s port numbers (plus some other useful runtime attributes) as properties in the Spring application context.

This means you can easily retrieve the dynamically assigned port and use it to configure API dependencies in your application under test. For example:

api.client.base-url=http://localhost:${wiremock.server.port}

This level of flexibility makes it easier to write robust tests that can be run in parallel and that play nicely in containerized environments.

Getting Started

To start using the official WireMock Spring Boot integration, add the following dependency to your pom.xml or build.gradle file:

Maven:

<dependency>
    <groupId>org.wiremock.integrations</groupId>
    <artifactId>wiremock-spring-boot</artifactId>
    <version>LATEST_VERSION</version>
    <scope>test</scope>
</dependency>

Gradle:

testImplementation org.wiremock.integrations:wiremock-spring-boot:LATEST_VERSION'

Once the dependency is added, you can start using annotations and configuration options to create WireMock instances in your Spring Boot tests, e.g.:

@SpringBootTest(
       webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
       classes = MySpringbootApplication.class
)
@EnableWireMock({
       @ConfigureWireMock(
               name = "greeting-service"
       )
})
class MyApplicationTests { // Do some testing }

For more detailed documentation and examples, check out the documentation page for running WireMock in Spring Boot.