Quarkus WireMock

Quarkus WireMock extension for tests and local development. This extension starts WireMock as a Dev Service, thus it is designed to run in dev and test mode only!

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.3.1</version>
    <scope>provided</scope>
</dependency>

Usage

The extension comes with most reasonable defaults.

quarkus.wiremock.devservices.enabled=true
quarkus.wiremock.devservices.reload=true
quarkus.wiremock.devservices.files-mapping=src/test/resources
quarkus.wiremock.devservices.global-response-templating=false
Due to its build time nature is totally fine that Quarkus prints unrecognized configuration key warnings when executing integration tests.

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.3.1</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:

@QuarkusIntegrationTest
@ConnectWireMock
class WireMockDevServiceResourceTest {

    DevServicesContext devServicesContext;

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

        // or via the Dev Service Context
        int portDevSerCtx = Integer.parseInt(devServicesContext.devServicesProperties().get(WireMockConfigKey.PORT));
        ...
    }

}
Please be aware that Dependency Injection (DI) works for specific types (DevServicesContext and WireMock) only. The latter in particular is only available if the class has been annotated with @ConnectWireMock.

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 variable interpolation.

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 Dev Services for WireMock has been explicitly enabled or disabled.

Environment variable: QUARKUS_WIREMOCK_DEVSERVICES_ENABLED

boolean

true

quarkus.wiremock.devservices.reload

Restart WireMock Dev Service whenever Quarkus is reloaded. Otherwise, whenever files are changed in the files-mapping location you would need to restart the Dev Service (WireMock server) manually.

Environment variable: QUARKUS_WIREMOCK_DEVSERVICES_RELOAD

boolean

true

quarkus.wiremock.devservices.port

Optional fixed port the WireMock 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.files-mapping

Path to the WireMock configuration files (root dir which contains the mappings and __files folders). If this starts with classpath: then files will be looked up on the classpath instead of the filesystem.

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

quarkus.wiremock.devservices.extension-scanning-enabled

Control whether WireMock Extension service loading, is enabled.

Environment variable: QUARKUS_WIREMOCK_DEVSERVICES_EXTENSION_SCANNING_ENABLED

boolean

false