or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

command-line-interface.mdextension-system.mdhttp-stubbing.mdindex.mdjunit-integration.mdrequest-matching.mdrequest-verification.mdresponse-building.mdserver-configuration.md
tile.json

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.wiremock/wiremock@3.13.x

To install, run

npx @tessl/cli install tessl/maven-org-wiremock--wiremock@3.13.0

index.mddocs/

WireMock

WireMock is a comprehensive HTTP service mocking and service virtualization library designed for testing and development environments. It provides a flexible HTTP server that can simulate REST APIs and web services for unit testing, integration testing, and development. WireMock offers advanced request matching capabilities, flexible response generation, and extensive extensibility for complex testing scenarios.

Package Information

  • Package Name: wiremock
  • Package Type: maven
  • Language: Java
  • Installation: org.wiremock:wiremock:3.13.1
  • Main Class: wiremock.Run

Core Imports

Essential Imports

// Core server and client classes
import com.github.tomakehurst.wiremock.WireMockServer;
import com.github.tomakehurst.wiremock.client.WireMock;
import com.github.tomakehurst.wiremock.core.WireMockConfiguration;

// Static imports for fluent API
import static com.github.tomakehurst.wiremock.client.WireMock.*;
import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;

JUnit Testing Imports

// JUnit 4 integration
import com.github.tomakehurst.wiremock.junit.WireMockRule;
import com.github.tomakehurst.wiremock.junit.WireMockClassRule;

// JUnit 5 integration
import com.github.tomakehurst.wiremock.junit5.WireMockExtension;
import com.github.tomakehurst.wiremock.junit5.WireMockTest;

Advanced Pattern Matching

// Request pattern matching
import com.github.tomakehurst.wiremock.matching.RequestPatternBuilder;
import com.github.tomakehurst.wiremock.matching.StringValuePattern;
import com.github.tomakehurst.wiremock.matching.UrlPattern;

// Fault injection
import com.github.tomakehurst.wiremock.http.Fault;

// Request logging and verification
import com.github.tomakehurst.wiremock.verification.LoggedRequest;
import com.github.tomakehurst.wiremock.stubbing.ServeEvent;

Extension Development

// Extension interfaces
import com.github.tomakehurst.wiremock.extension.Extension;
import com.github.tomakehurst.wiremock.extension.ResponseTransformerV2;
import com.github.tomakehurst.wiremock.extension.ServeEventListener;
import com.github.tomakehurst.wiremock.extension.Parameters;

Basic Usage

Programmatic Usage

import com.github.tomakehurst.wiremock.WireMockServer;
import com.github.tomakehurst.wiremock.client.WireMock;
import static com.github.tomakehurst.wiremock.client.WireMock.*;
import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;

// Start WireMock server
WireMockServer wireMockServer = new WireMockServer(wireMockConfig().port(8089));
wireMockServer.start();

// Configure WireMock client
WireMock.configureFor("localhost", 8089);

// Create a simple stub
stubFor(get(urlEqualTo("/api/users/123"))
    .willReturn(aResponse()
        .withStatus(200)
        .withHeader("Content-Type", "application/json")
        .withBody("{\"id\": 123, \"name\": \"John Doe\"}")));

// Verify requests
verify(getRequestedFor(urlEqualTo("/api/users/123")));

// Shutdown server
wireMockServer.stop();

Standalone Command-Line Usage

# Start standalone server
java -jar wiremock-standalone-3.13.1.jar --port 8080

# With HTTPS support
java -jar wiremock-standalone-3.13.1.jar --port 8080 --https-port 8443

# With proxy mode
java -jar wiremock-standalone-3.13.1.jar --port 8080 --proxy-all="https://api.example.com"

# Record mappings
java -jar wiremock-standalone-3.13.1.jar --port 8080 --record-mappings --proxy-all="https://api.example.com"

Architecture

WireMock Standalone is built around several key components:

  • Server Core: WireMockServer class that manages HTTP server lifecycle and configuration
  • Client API: WireMock class providing fluent API for stub creation and request verification
  • Request Matching: Comprehensive pattern matching system for URLs, headers, bodies, and custom matchers
  • Response Generation: Flexible response building with static content, files, templates, and proxying
  • Extension System: Plugin architecture for custom transformers, filters, and event listeners
  • JUnit Integration: Test rules and extensions for seamless testing framework integration
  • Standalone Runner: Command-line interface for running WireMock as a standalone service

Capabilities

Server Configuration and Lifecycle

Core server management functionality for starting, configuring, and controlling WireMock instances with extensive configuration options.

class WireMockServer implements Container, Stubbing, Admin {
    WireMockServer(Options options);
    WireMockServer(int port);
    void start();
    void stop();
    int port();
    boolean isRunning();
}

class WireMockConfiguration implements Options {
    // Factory Method
    static WireMockConfiguration wireMockConfig();
    
    // Basic Configuration
    WireMockConfiguration port(int portNumber);
    WireMockConfiguration httpsPort(Integer httpsPort);
    WireMockConfiguration bindAddress(String bindAddress);
    WireMockConfiguration timeout(long timeout);
    
    // SSL/TLS Configuration
    WireMockConfiguration keystorePath(String keystorePath);
    WireMockConfiguration keystorePassword(String keystorePassword);
    WireMockConfiguration trustStorePath(String trustStorePath);
    WireMockConfiguration needClientAuth(boolean needClientAuth);
    
    // Proxy Configuration
    WireMockConfiguration enableBrowserProxying(boolean enabled);
    WireMockConfiguration proxyVia(String host, int port);
    WireMockConfiguration trustAllProxyTargets(boolean trustAll);
    
    // Performance Configuration
    WireMockConfiguration containerThreads(Integer containerThreads);
    WireMockConfiguration jettyAcceptors(Integer jettyAcceptors);
    WireMockConfiguration asynchronousResponseEnabled(boolean enabled);
    
    // Extension Configuration
    WireMockConfiguration extensions(Extension... extensions);
    WireMockConfiguration extensionScanningEnabled(boolean enabled);
    
    // File and Logging
    WireMockConfiguration usingFilesUnderDirectory(String directory);
    WireMockConfiguration usingFilesUnderClasspath(String classpathDirectoryName);
    WireMockConfiguration notifier(Notifier notifier);
}

Server Configuration

HTTP Request Stubbing

Request-response mapping system with fluent API for creating sophisticated HTTP service simulations.

class WireMock {
    // Configuration
    static void configureFor(String host, int port);
    static void configureFor(String scheme, String host, int port, String urlPathPrefix);
    
    // HTTP Method Builders
    static MappingBuilder get(UrlPattern urlPattern);
    static MappingBuilder post(UrlPattern urlPattern);
    static MappingBuilder put(UrlPattern urlPattern);
    static MappingBuilder delete(UrlPattern urlPattern);
    static MappingBuilder patch(UrlPattern urlPattern);
    static MappingBuilder head(UrlPattern urlPattern);
    static MappingBuilder options(UrlPattern urlPattern);
    static MappingBuilder trace(UrlPattern urlPattern);
    static MappingBuilder any(UrlPattern urlPattern);
    
    // Stub Management
    static void givenThat(MappingBuilder mappingBuilder);
    static void stubFor(MappingBuilder mappingBuilder);
    static void editStub(MappingBuilder mappingBuilder);
    static void removeStub(MappingBuilder mappingBuilder);
    
    // Response Shortcuts
    static ResponseDefinitionBuilder aResponse();
    static ResponseDefinitionBuilder ok();
    static ResponseDefinitionBuilder created();
    static ResponseDefinitionBuilder notFound();
    static ResponseDefinitionBuilder serverError();
    
    // Recording
    static void startRecording(String targetBaseUrl);
    static void startRecording(RecordSpec recordSpec);
    static SnapshotRecordResult stopRecording();
    static SnapshotRecordResult snapshotRecord();
    
    // Request Inspection
    static List<ServeEvent> getAllServeEvents();
    static List<LoggedRequest> findAll(RequestPatternBuilder requestPatternBuilder);
    static List<LoggedRequest> findAllUnmatchedRequests();
}

interface MappingBuilder {
    MappingBuilder withHeader(String key, StringValuePattern pattern);
    MappingBuilder withRequestBody(ContentPattern<?> bodyPattern);
    MappingBuilder willReturn(ResponseDefinitionBuilder responseDefBuilder);
}

HTTP Stubbing

Request and Response Matching

Advanced pattern matching capabilities for precise request identification and response generation.

// URL Pattern Methods
static UrlPattern urlEqualTo(String testUrl);
static UrlPattern urlMatching(String urlRegex);
static UrlPattern urlPathEqualTo(String testUrl);
static UrlPattern urlPathMatching(String urlRegex);
static UrlPattern urlPathTemplate(String pathTemplate);
static UrlPattern anyUrl();

// String Value Patterns
static StringValuePattern equalTo(String value);
static StringValuePattern equalToIgnoreCase(String value);
static StringValuePattern containing(String value);
static StringValuePattern notContaining(String value);
static StringValuePattern matching(String regex);
static StringValuePattern notMatching(String regex);
static StringValuePattern absent();

// JSON/XML Patterns
static StringValuePattern equalToJson(String value);
static StringValuePattern matchingJsonPath(String jsonPath);
static StringValuePattern equalToXml(String value);
static StringValuePattern matchingXPath(String xpath);

// Date/Time Patterns
static StringValuePattern before(String dateTime);
static StringValuePattern after(String dateTime);
static StringValuePattern equalToDateTime(String dateTime);
static StringValuePattern beforeNow();
static StringValuePattern afterNow();

// Logical Patterns
static LogicalAnd and(StringValuePattern... matchers);
static LogicalOr or(StringValuePattern... matchers);
static NotPattern not(StringValuePattern unexpectedPattern);

Request Matching

Response Building and Configuration

Comprehensive response generation with support for static content, delays, transformations, and fault injection.

class ResponseDefinitionBuilder {
    static ResponseDefinitionBuilder aResponse();
    ResponseDefinitionBuilder withStatus(int status);
    ResponseDefinitionBuilder withHeader(String key, String... values);
    ResponseDefinitionBuilder withBody(String body);
    ResponseDefinitionBuilder withFixedDelay(Integer milliseconds);
    ResponseDefinitionBuilder withFault(Fault fault);
    ResponseDefinitionBuilder proxiedFrom(String proxyBaseUrl);
}

Response Building

Request Verification and Testing

Request verification system with count matching, pattern matching, and detailed error reporting for test assertions.

// Verification Methods
static void verify(RequestPatternBuilder requestPatternBuilder);
static void verify(int count, RequestPatternBuilder requestPatternBuilder);
static void verify(CountMatchingStrategy strategy, RequestPatternBuilder pattern);

// Count Matching Strategies
static CountMatchingStrategy lessThan(int expected);
static CountMatchingStrategy exactly(int expected);
static CountMatchingStrategy moreThan(int expected);

// Request Inspection
static List<LoggedRequest> findAll(RequestPatternBuilder requestPatternBuilder);
static List<LoggedRequest> findUnmatchedRequests();

Request Verification

JUnit Integration

Seamless integration with JUnit 4 and JUnit 5 testing frameworks with lifecycle management and parameter injection.

// JUnit 4 Integration
class WireMockRule extends WireMockServer implements TestRule {
    WireMockRule();
    WireMockRule(int port);
    WireMockRule(Options options);
}

// JUnit 5 Integration
class WireMockExtension extends DslWrapper {
    static Builder newInstance();
    
    static class Builder {
        Builder options(Options options);
        Builder failOnUnmatchedRequests(boolean fail);
        WireMockExtension build();
    }
}

@WireMockTest
public @interface WireMockTest {
    int httpPort() default 0;
    boolean httpsEnabled() default false;
    int httpsPort() default 0;
}

JUnit Integration

Extension System

Plugin architecture for extending WireMock functionality with custom transformers, filters, and event listeners.

interface Extension {
    String getName();
    void start();
    void stop();
}

interface ResponseTransformerV2 extends Extension {
    Response transform(Response response, ServeEvent serveEvent);
}

interface ServeEventListener extends Extension {
    void beforeMatch(ServeEvent serveEvent, Parameters parameters);
    void afterMatch(ServeEvent serveEvent, Parameters parameters);
    void beforeResponseSent(ServeEvent serveEvent, Parameters parameters);
    void afterComplete(ServeEvent serveEvent, Parameters parameters);
}

Extension System

Standalone Command-Line Interface

Command-line interface for running WireMock as a standalone service with comprehensive configuration options.

class WireMockServerRunner {
    void run(String... args);
    void stop();
    boolean isRunning();
    int port();
}

class CommandLineOptions implements Options {
    CommandLineOptions(String... args);
    boolean help();
    boolean version();
    String helpText();
    boolean verboseLoggingEnabled();
    boolean recordMappingsEnabled();
}

Command-Line Interface

Common Types

// Core Interfaces
interface Options {
    int portNumber();
    String bindAddress();
    boolean getHttpDisabled();
    HttpsSettings httpsSettings();
    boolean browserProxyingEnabled();
    ProxySettings proxyVia();
    long timeout();
    int containerThreads();
    FileSource filesRoot();
    Notifier notifier();
}

interface Admin {
    void addStubMapping(StubMapping stubMapping);
    void removeStubMapping(StubMapping stubMapping);
    ListStubMappingsResult listAllStubMappings();
    void resetAll();
    void resetRequests();
    VerificationResult countRequestsMatching(RequestPattern pattern);
    FindRequestsResult findRequestsMatching(RequestPattern pattern);
}

interface Container {
    int port();
    void shutdown();
}

// Pattern Types
abstract class StringValuePattern {
    boolean isPresent();
    Boolean isAbsent();
    LogicalAnd and(StringValuePattern other);
    LogicalOr or(StringValuePattern other);
}

abstract class ContentPattern<T> implements NamedValueMatcher<T> {
    T getValue();
}

// Request/Response Types
class RequestPattern {
    static RequestPattern ANYTHING;
    static RequestPattern everything();
    MatchResult match(Request request, Map<String, RequestMatcherExtension> customMatchers);
}

class StubMapping {
    UUID getId();
    String getName();
    RequestPattern getRequest();
    ResponseDefinition getResponse();
    Integer getPriority();
    String getScenarioName();
    String getRequiredScenarioState();
    String getNewScenarioState();
}

// Fault Types
enum Fault {
    CONNECTION_RESET_BY_PEER,
    EMPTY_RESPONSE,
    MALFORMED_RESPONSE_CHUNK,
    RANDOM_DATA_THEN_CLOSE
}

// Result Types
class VerificationResult {
    int getCount();
}

class ListStubMappingsResult {
    List<StubMapping> getMappings();
}

class FindRequestsResult {
    List<LoggedRequest> getRequests();
}

class LoggedRequest {
    String getUrl();
    String getMethod();
    HttpHeaders getHeaders();
    String getBodyAsString();
    Date getLoggedDate();
}