Quarkus WireMock

Quarkus WireMock extension for tests and local development.

Installation

If you want to use this extension, you need to add the io.quarkiverse.wiremock:quarkus-wiremock dependency to your build file first.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.wiremock</groupId>
    <artifactId>quarkus-wiremock</artifactId>
    <version>1.0.0</version>
    <scope>test</scope>
</dependency>

Usage

This extension starts WireMock as a Dev Service, thus it is designed to run in dev and test mode only! Please don’t specify any attributes applicable for other profiles (like prod), otherwise unknown property warnings could appear when executing the production build.

The extension comes with most reasonable defaults. However, it’s recommended to use the Multiple Profiles syntax with the dev and test profile prefix when overriding configuration values:

# Use multiple profiles syntax when overriding configuration values
%dev,test.quarkus.wiremock.devservices.reload=false
%dev,test.quarkus.wiremock.devservices.global-response-templating=true

Testing

Stubbing & Verifying

A core feature of WireMock is the ability to return HTTP responses for request matching criteria. You can configure stubs using JSON configuration files placed in the mappings and __files folders. The root location of these folders can be defined via quarkus.wiremock.devservices.files-mapping. By default the root location points to src/test/resources.

In addition, you might want to configure WireMock’s stubbing and request matching behavior programmatically. To do so, please add the following dependency to your target project:

<dependency>
    <groupId>io.quarkiverse.wiremock</groupId>
    <artifactId>quarkus-wiremock-test</artifactId>
    <version>1.0.0</version>
    <scope>test</scope>
</dependency>

After that, a WireMock client reference can be injected along with your test execution lifecycle as shown below:

@QuarkusTest
@ConnectWireMock
class WireMockDevServiceResourceTest {

    private static final String MOCK_MSG = "Hello from WireMock!";

    WireMock wiremock; // will be injected automatically when the test class is annotated with @ConnectWireMock

    @Test
    void testHelloEndpoint() {
        Assertions.assertNotNull(wiremock);
        wiremock.register(get(urlEqualTo("/mock-me"))
            .willReturn(aResponse().withStatus(200).withBody(MOCK_MSG)));
        ...
    }

}
For more details please refer to the WireMock Stubbing & Verifying docs.

Configuration retrieval

This Quarkus extension exposes configuration keys via Java constants (WireMockConfigKey). By doing so, the config values can be accessed more easily:

@QuarkusTest
class WireMockDevServiceResourceTest {

    // WireMockConfigKey is provided by the core module and does not require the `test` module dependency
    @ConfigProperty(name = WireMockConfigKey.PORT)
    Integer port; // the port WireMock server is listening on

}

You can even access the WireMock Dev Service configuration values from within a Quarkus Integration Test:

Please be aware that Dependency Injection (DI) is not supported for ITs! 
@QuarkusIntegrationTest
class WireMockDevServiceResourceTest {

    @Test
    void testWireMockDevServiceConfigPropagation() {
        // Dev Service config gets propagated and is accessible via the ConfigProvider API
        int port = ConfigProvider.getConfig().getValue(WireMockConfigKey.PORT, Integer.class);
        ...
    }

}

You can also reuse a @QuarkusTest as a @QuarkusIntegrationTest where applicable:

@QuarkusIntegrationTest
public class WireMockDevServiceResourceIT extends WireMockDevServiceResourceTest {
    // re-use Quarkus tests as integration tests
}

Further more this extension supports the configuration capabilities of Quarkus. This means you can reference WireMock configuration keys within your custom properties via property expressions expansion.

%test.custom.config.wiremock.url=http://localhost:${quarkus.wiremock.devservices.port}/mock-me

Please refer to Property Expressions for further details.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.wiremock.devservices.enabled

If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present.

Environment variable: QUARKUS_WIREMOCK_DEVSERVICES_ENABLED

boolean

true

quarkus.wiremock.devservices.port

Optional fixed port the Dev Service will listen to. If not defined, the port will be chosen randomly.

WARNING: Only ports between 1025 and 65535 are permitted.

Environment variable: QUARKUS_WIREMOCK_DEVSERVICES_PORT

int

quarkus.wiremock.devservices.reload

Restart WireMock whenever Quarkus is reloaded. Otherwise, whenever files are changed in the files-mapping location you would need to manually reload Quarkus.

Environment variable: QUARKUS_WIREMOCK_DEVSERVICES_RELOAD

boolean

true

quarkus.wiremock.devservices.files-mapping

Path to root dir with mappings and __files folders.

Environment variable: QUARKUS_WIREMOCK_DEVSERVICES_FILES_MAPPING

string

src/test/resources

quarkus.wiremock.devservices.global-response-templating

Response templating is enabled by default in WireMock 3, with this setting response templating can be enabled globally.

Please refer to Response Templating for more details.

Environment variable: QUARKUS_WIREMOCK_DEVSERVICES_GLOBAL_RESPONSE_TEMPLATING

boolean

false