tessl/maven-org-wiremock--wiremock
WireMock is a comprehensive API mocking and service virtualization library for testing and development environments with HTTP server simulation capabilities.
http-stubbing.mddocs/
HTTP Stubbing
Request-response mapping system with fluent API for creating sophisticated HTTP service simulations. Supports all HTTP methods, advanced request matching, and flexible response generation for comprehensive API mocking scenarios.
Capabilities
WireMock Client Class
Primary client API for configuring stubs and managing WireMock server interactions.
/**
* Main client API class for WireMock server interaction
*/
class WireMock {
// Static Configuration Methods
/** Create new WireMock builder instance */
static WireMockBuilder create();
/** Configure default instance for localhost with specified port */
static void configureFor(int port);
/** Configure default instance with host and port */
static void configureFor(String host, int port);
/** Configure default instance with host, port, and URL prefix */
static void configureFor(String host, int port, String urlPathPrefix);
/** Configure default instance with full connection details */
static void configureFor(String scheme, String host, int port, String urlPathPrefix);
/** Set specific client as default */
static void configureFor(WireMock client);
// HTTP Method Builders
/** Create GET request matcher */
static MappingBuilder get(UrlPattern urlPattern);
/** Create POST request matcher */
static MappingBuilder post(UrlPattern urlPattern);
/** Create PUT request matcher */
static MappingBuilder put(UrlPattern urlPattern);
/** Create DELETE request matcher */
static MappingBuilder delete(UrlPattern urlPattern);
/** Create PATCH request matcher */
static MappingBuilder patch(UrlPattern urlPattern);
/** Create HEAD request matcher */
static MappingBuilder head(UrlPattern urlPattern);
/** Create OPTIONS request matcher */
static MappingBuilder options(UrlPattern urlPattern);
/** Create TRACE request matcher */
static MappingBuilder trace(UrlPattern urlPattern);
/** Match any HTTP method */
static MappingBuilder any(UrlPattern urlPattern);
/** Match both GET and HEAD methods */
static MappingBuilder getOrHead(UrlPattern urlPattern);
// Stub Management
/** Create stub mapping (primary method) */
static void givenThat(MappingBuilder mappingBuilder);
/** Create stub mapping (alias for givenThat) */
static void stubFor(MappingBuilder mappingBuilder);
/** Edit existing stub mapping */
static void editStub(MappingBuilder mappingBuilder);
/** Remove stub by mapping builder */
static void removeStub(MappingBuilder mappingBuilder);
/** Remove stub by stub mapping object */
static void removeStub(StubMapping stubMapping);
/** Remove stub by UUID */
static void removeStub(UUID id);
/** List all configured stub mappings */
static ListStubMappingsResult listAllStubMappings();
/** Get specific stub mapping by ID */
static SingleStubMappingResult getSingleStubMapping(UUID id);
}Usage Examples:
import static com.github.tomakehurst.wiremock.client.WireMock.*;
// Configure WireMock client
configureFor("localhost", 8089);
// Simple GET stub
stubFor(get(urlEqualTo("/api/users"))
.willReturn(aResponse()
.withStatus(200)
.withHeader("Content-Type", "application/json")
.withBody("[{\"id\": 1, \"name\": \"John\"}]")));
// POST stub with request body matching
stubFor(post(urlEqualTo("/api/users"))
.withHeader("Content-Type", equalTo("application/json"))
.withRequestBody(matchingJsonPath("$.name"))
.willReturn(aResponse()
.withStatus(201)
.withHeader("Location", "/api/users/123")
.withBody("{\"id\": 123, \"name\": \"John\"}")));
// Dynamic response with delays
stubFor(get(urlMatching("/api/users/[0-9]+"))
.willReturn(aResponse()
.withStatus(200)
.withFixedDelay(500)
.withBodyFile("user-template.json")));MappingBuilder Interface
Main interface for building request-response mappings with comprehensive matching options.
/**
* Interface for building request-response mappings
*/
interface MappingBuilder {
// Request Matching
/** Match request scheme (http/https) */
MappingBuilder withScheme(String scheme);
/** Match host header */
MappingBuilder withHost(StringValuePattern hostPattern);
/** Match port number */
MappingBuilder withPort(int port);
/** Match client IP address */
MappingBuilder withClientIp(StringValuePattern hostPattern);
/** Match single header value */
MappingBuilder withHeader(String key, StringValuePattern pattern);
/** Match multiple header values */
MappingBuilder withHeader(String key, MultiValuePattern pattern);
/** Match path parameter by name */
MappingBuilder withPathParam(String name, StringValuePattern pattern);
/** Match single query parameter */
MappingBuilder withQueryParam(String key, StringValuePattern pattern);
/** Match multiple query parameter values */
MappingBuilder withQueryParam(String key, MultiValuePattern pattern);
/** Match single form parameter */
MappingBuilder withFormParam(String key, StringValuePattern pattern);
/** Match multiple form parameter values */
MappingBuilder withFormParam(String key, MultiValuePattern pattern);
/** Match request body content */
MappingBuilder withRequestBody(ContentPattern<?> bodyPattern);
/** Match multipart request body */
MappingBuilder withMultipartRequestBody(MultipartValuePatternBuilder builder);
/** Match HTTP Basic authentication */
MappingBuilder withBasicAuth(String username, String password);
/** Match cookie value */
MappingBuilder withCookie(String name, StringValuePattern pattern);
// Configuration Methods
/** Set mapping priority (lower numbers = higher priority) */
MappingBuilder atPriority(Integer priority);
/** Set mapping UUID */
MappingBuilder withId(UUID id);
/** Set mapping name for identification */
MappingBuilder withName(String name);
/** Make mapping persistent across resets */
MappingBuilder persistent();
/** Add metadata to mapping */
MappingBuilder withMetadata(Map<String, ?> metadata);
/** Add metadata to mapping */
MappingBuilder withMetadata(Metadata metadata);
/** Add custom request matcher */
MappingBuilder andMatching(ValueMatcher<Request> requestMatcher);
/** Add named custom request matcher */
MappingBuilder andMatching(String matcherName);
// Response Configuration
/** Set response definition */
MappingBuilder willReturn(ResponseDefinitionBuilder responseDefBuilder);
// Scenario Configuration
/** Associate mapping with scenario */
MappingBuilder inScenario(String scenarioName);
// Extension Points
/** Add post-serve action */
MappingBuilder withPostServeAction(String extensionName, Parameters parameters);
/** Add serve event listener */
MappingBuilder withServeEventListener(String extensionName, Parameters parameters);
}ScenarioMappingBuilder Interface
Extended mapping builder with scenario state management capabilities.
/**
* Extended mapping builder with scenario support
*/
interface ScenarioMappingBuilder extends MappingBuilder {
/** Require specific scenario state to match */
ScenarioMappingBuilder whenScenarioStateIs(String stateName);
/** Set new scenario state after successful match */
ScenarioMappingBuilder willSetStateTo(String stateName);
}Usage Examples:
// Stateful behavior with scenarios
stubFor(get(urlEqualTo("/api/start"))
.inScenario("User Journey")
.whenScenarioStateIs(Scenario.STARTED)
.willReturn(aResponse().withStatus(200))
.willSetStateTo("AUTHENTICATED"));
stubFor(get(urlEqualTo("/api/profile"))
.inScenario("User Journey")
.whenScenarioStateIs("AUTHENTICATED")
.willReturn(aResponse()
.withStatus(200)
.withBodyFile("user-profile.json")));WireMockBuilder Class
Builder for creating configured WireMock client instances.
/**
* Builder for configuring WireMock client instances
*/
class WireMockBuilder {
/** Set port number */
WireMockBuilder port(int port);
/** Set hostname */
WireMockBuilder host(String host);
/** Set URL scheme */
WireMockBuilder scheme(String scheme);
/** Set HTTP scheme */
WireMockBuilder http();
/** Set HTTPS scheme */
WireMockBuilder https();
/** Set URL path prefix */
WireMockBuilder urlPathPrefix(String urlPathPrefix);
/** Set custom host header */
WireMockBuilder hostHeader(String hostHeader);
/** Set proxy host */
WireMockBuilder proxyHost(String proxyHost);
/** Set proxy port */
WireMockBuilder proxyPort(int proxyPort);
/** Set client authenticator */
WireMockBuilder authenticator(ClientAuthenticator authenticator);
/** Set basic authentication */
WireMockBuilder basicAuthenticator(String username, String password);
/** Create configured WireMock instance */
WireMock build();
}Usage Examples:
// Custom WireMock client
WireMock customClient = WireMock.create()
.scheme("https")
.host("wiremock.example.com")
.port(443)
.urlPathPrefix("/mock")
.basicAuthenticator("admin", "password")
.build();
// Use custom client
customClient.register(get(urlEqualTo("/test"))
.willReturn(aResponse().withStatus(200)));BasicMappingBuilder Implementation
Concrete implementation providing all mapping builder functionality.
/**
* Concrete implementation of MappingBuilder and ScenarioMappingBuilder
*/
class BasicMappingBuilder implements MappingBuilder, ScenarioMappingBuilder {
/** Create mapping builder for specific HTTP method and URL pattern */
BasicMappingBuilder(RequestMethod method, UrlPattern urlPattern);
/** Build final StubMapping from configured builder */
StubMapping build();
}Stub Management Types
class StubMapping {
UUID getId();
String getName();
RequestPattern getRequest();
ResponseDefinition getResponse();
Integer getPriority();
boolean isPersistent();
String getScenarioName();
String getRequiredScenarioState();
String getNewScenarioState();
Metadata getMetadata();
List<PostServeActionDefinition> getPostServeActions();
List<ServeEventListenerDefinition> getServeEventListeners();
long getInsertionIndex();
boolean isDirty();
}
class ListStubMappingsResult {
List<StubMapping> getMappings();
Meta getMeta();
}
class SingleStubMappingResult {
StubMapping getItem();
Meta getMeta();
}
class Metadata {
static Metadata metadata();
Metadata attr(String key, Object value);
Object getAttribute(String key);
Map<String, Object> getAttributes();
}
enum RequestMethod {
GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE, ANY
}Install with Tessl CLI
npx tessl i tessl/maven-org-wiremock--wiremock