layout | title | toc_rank | redirect_from | description |
---|---|---|---|---|
docs |
Getting Started |
10 |
/getting-started.html |
Getting started with WireMock. Java, JUnit, standalone, servlet container. |
WireMock is distributed in two flavours - a standard JAR containing just WireMock, and a standalone fat JAR containing WireMock plus all its dependencies.
The standalone JAR's dependencies are shaded i.e. they are hidden in alternative packages. This allows WireMock to be used in projects with conflicting versions of its dependencies. The standalone JAR is also runnable (discussed in more detail below).
Currently it is recommended that you use the standalone JAR as a dependency with Spring Boot projects. This avoids a conflict over the Jetty version
To add the standard WireMock JAR as a project dependency, put the following in the dependencies section of your POM:
<dependency>
<groupId>com.github.tomakehurst</groupId>
<artifactId>wiremock</artifactId>
<version>{{ site.wiremock_version }}</version>
</dependency>
Or to use the standalone JAR:
<dependency>
<groupId>com.github.tomakehurst</groupId>
<artifactId>wiremock-standalone</artifactId>
<version>{{ site.wiremock_version }}</version>
</dependency>
testCompile "com.github.tomakehurst:wiremock:{{ site.wiremock_version }}"
Or
testCompile "com.github.tomakehurst:wiremock-standalone:{{ site.wiremock_version }}"
To use WireMock's fluent API add the following import:
import static com.github.tomakehurst.wiremock.client.WireMock.*;
WireMock ships with some JUnit rules to manage the server's lifecycle and setup/tear-down tasks. To start and stop WireMock per-test case, add the following to your test class (or a superclass of it):
@Rule
public WireMockRule wireMockRule = new WireMockRule(8089); // No-args constructor defaults to port 8080
Now you're ready to write a test case like this:
@Test
public void exampleTest() {
stubFor(get(urlEqualTo("/my/resource"))
.withHeader("Accept", equalTo("text/xml"))
.willReturn(aResponse()
.withStatus(200)
.withHeader("Content-Type", "text/xml")
.withBody("<response>Some content</response>")));
Result result = myHttpServiceCallingObject.doSomething();
assertTrue(result.wasSuccessful());
verify(postRequestedFor(urlMatching("/my/resource/[a-z0-9]+"))
.withRequestBody(matching(".*<message>1234</message>.*"))
.withHeader("Content-Type", notMatching("application/json")));
}
For many more examples of JUnit tests look no further than WireMock's own acceptance tests
For more details on verifying requests and stubbing responses, see Stubbing and Verifying
For more information on the JUnit rule see The JUnit Rule.
For a bit more control over the settings of the WireMock server created by the rule you can pass a fluently built Options object to either (non-deprecated) rule's constructor:
import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
...
@Rule
public WireMockRule wireMockRule = new WireMockRule(wireMockConfig().port(8089).httpsPort(8443));
You can have WireMock (or more accurately the JVM) pick random, free HTTP and HTTPS ports (which is a great idea if you want to run your tests concurrently):
@Rule
public WireMockRule wireMockRule = new WireMockRule(wireMockConfig().dynamicPort().dynamicHttpsPort());
Then find out which ports to use from your tests as follows:
int port = wireMockRule.port();
int httpsPort = wireMockRule.httpsPort();
If you're not using JUnit or neither of the WireMock rules manage its lifecycle in a suitable way you can construct and start the server directly:
WireMockServer wireMockServer = new WireMockServer(wireMockConfig().port(8089)); //No-args constructor will start on port 8080, no HTTPS
wireMockServer.start();
// Do some stuff
WireMock.reset();
// Finish doing stuff
wireMockServer.stop();
If you've changed the port number and/or you're running the server on another host, you'll need to tell the client:
WireMock.configureFor("wiremock.host", 8089);
And if you've deployed it into a servlet container under a path other than root you'll need to set that too:
WireMock.configureFor("tomcat.host", 8080, "/wiremock");
The WireMock server can be run in its own process, and configured via the Java API, JSON over HTTP or JSON files.
This will start the server on port 8080:
You can [download the standalone JAR from here](http://repo1.maven.org/maven2/com/github/tomakehurst/wiremock-standalone/{{ site.wiremock_version }}/wiremock-standalone-{{ site.wiremock_version }}.jar).
See Running as a Standalone Process running-standalone for more details and commandline options.
A GET request to the root admin URL e.g http://localhost:8080/__admin
will return all currently registered stub mappings. This is a useful way
to check whether WireMock is running on the host and port you expect:
WireMock can be packaged up as a WAR and deployed into a servlet container, with some caveats: fault injection and browser proxying won't work, __files won't be treated as a docroot as with standalone, the server cannot be remotely shutdown, and the container must be configured to explode the WAR on deployment. This has only really been tested in Tomcat 6 and Jetty, so YMMV. Running standalone is definitely the preferred option.
The easiest way to create a WireMock WAR project is to clone the sample app
If you want WireMock's servlet to have a non-root path, the additional
init param mappedUnder
must be set with the sub-path web.xml (in
addition to configuring the servlet mapping appropriately).
See the custom mapped WAR example for details.