WireMock v4 Beta

v4 Beta

Version 4 of WireMock is currently in beta. It is under active development and we recommend you try it out. We would love to hear your feedback over on the community slack - https://slack.wiremock.org/

We have given these releases a beta label due to the fact that as we move forwards with the 4.x release there will be breaking changes. These are the current updates to the 4.x release:

• Java 17 is now the baseline java version
• Jetty 12.1 is shipped by default, so there is no longer a specific jetty 12 release of 4.x and Jetty 11 is no longer supported
  • Jetty now normalises the Content-Type header so that e.g. application/json; charset=UTF-8 becomes application/json;charset=utf-8.
  • We have upgraded to EE11 support in Jetty 12.1 - EE11 is the highest version of the standard Jetty 12.1 supports and is backwards compatible with EE10
• The version 4 codebase has been refactored to break out the core of WireMock from the various dependencies on external libraries. This means that you can now choose which dependencies you want to include in your project. See the Download and Installation page for details.

Breaking changes and how to migrate

Multiple Content-Type headers

In v3 using Jetty 11, if you configured a stub with multiple Content-Type headers, Jetty 11 stripped out all but the last.

In v4.x WireMock will return all the Content-Type headers. This may break some clients which do not know what to do if an HTTP response has multiple Content-Type headers.

Solution: only configure a single Content-Type header on a stub.

Removed transitive dependencies

v4 no longer has transitive dependencies on the following libraries:

• org.eclipse.jetty:jetty-webapp (package org.eclipse.jetty.webapp) - Jetty 12 equivalent is org.eclipse.jetty.ee10:jetty-ee10-webapp
• org.eclipse.jetty.ee10:jetty-ee10-webapp (package org.eclipse.jetty.ee10.webapp)
• org.eclipse.jetty:jetty-alpn-client (package org.eclipse.jetty.alpn.client)
• org.eclipse.jetty:jetty-alpn-java-client (package org.eclipse.jetty.alpn.java.client)
• org.eclipse.jetty:jetty-client (package org.eclipse.jetty.client)
• org.eclipse.jetty:jetty-ee (package org.eclipse.jetty.ee)
• org.eclipse.jetty:jetty-proxy (package org.eclipse.jetty.proxy)
• org.eclipse.jetty:jetty-xml (package org.eclipse.jetty.xml)

If your code depends on classes in these packages you will need to bring the dependencies in directly.

The following transitive dependencies have been replaced and may require changes to package names:

• org.eclipse.jetty:jetty-servlet -> org.eclipse.jetty.ee10:jetty-ee10-servlet
• org.eclipse.jetty:jetty-servlets -> org.eclipse.jetty.ee10:jetty-ee10-servlets
• org.eclipse.jetty.http2:http2-common -> org.eclipse.jetty.http2:jetty-http2-common
• org.eclipse.jetty.http2:http2-hpack -> org.eclipse.jetty.http2:jetty-http2-hpack
• org.eclipse.jetty.http2:http2-server -> org.eclipse.jetty.http2:jetty-http2-server

Immutable data classes

Several of the core data classes in WireMock are now immutable, and can only be transformed via their respective builder classes. This decision was made to reduce the likelihood of bugs due to reliance on in-place mutation of objects, especially objects within in-memory stores, and to increase code clarity.

Usage

Previously, a StubMapping instance’s request pattern could be mutated via the setRequest method on the StubMapping class, like so:

stubMapping.setRequest(newRequestPattern);

Now, the transform method on the StubMapping class can be used to copy the existing instance and return a new instance with an updated request pattern, like so:

StubMapping newStubMapping =
    oldStubMapping.transform(builder -> builder.setRequest(newRequestPattern));

The following data classes have all been updated to be immutable and use the builder pattern:

• com.github.tomakehurst.wiremock.stubbing.StubMapping
• com.github.tomakehurst.wiremock.common.Metadata
• com.github.tomakehurst.wiremock.extension.Parameters
• com.github.tomakehurst.wiremock.global.GlobalSettings
• com.github.tomakehurst.wiremock.http.ResponseDefinition
• com.github.tomakehurst.wiremock.matching.RequestPattern

Request and message journal store changes

The com.github.tomakehurst.wiremock.store.RequestJournalStore and com.github.tomakehurst.wiremock.store.MessageJournalStore interfaces have had the same changes. This only affects you if you have written your own implementation of either interface or call the stores directly.

removeLast() has been removed

The removeLast() method has been removed from both interfaces. Previously, WireMock called getAllKeys().count() and removeLast() after every add to trim the journal down to the configured maximum number of entries. This took several calls across the journal-to-store boundary for every request, which is expensive for externalised stores.

Stores are now responsible for enforcing the maximum number of entries

The request and message journals no longer trim their stores. If a RequestJournalStore or MessageJournalStore implementation should enforce a maximum number of entries, it must now evict the oldest entries itself, by whatever means suits the implementation. See the InMemoryRequestJournalStore and InMemoryMessageJournalStore implementations for an example.

For the built-in in-memory stores this is configured as before via WireMockConfiguration.maxRequestJournalEntries(int) or the --max-request-journal-entries command line option, which applies to both journals. The following constructors have changed accordingly:

• InMemoryRequestJournalStore and InMemoryMessageJournalStore now have a constructor taking a @Nullable Integer maxEntries, where null means unbounded.
• DefaultStores has a new DefaultStores(FileSource, @Nullable Integer maxRequestJournalEntries) constructor.

Migration

If you have a custom RequestJournalStore or MessageJournalStore:

1. Remove your removeLast() implementation.
2. If you want your store to enforce a maximum number of entries, evict the oldest entries yourself and pass the maxRequestJournalEntries value to the store when creating it, for example by constructing it in a custom Stores implementation.

If you construct InMemoryRequestJournalStore or InMemoryMessageJournalStore directly, pass a max-entries value (or null) to the constructor.