Skip to main content
MockServer can act as a transparent proxy between your application and any real HTTP or HTTPS service. Every request that passes through the proxy is recorded automatically, giving you a complete traffic log you can inspect and verify.

​
How the proxy works

When you configure your application to route traffic through MockServer, MockServer forwards each request to the real upstream service and returns the response to the caller. At the same time it stores a copy of the request and response internally as a recorded expectation. You can then:
  • Inspect the recorded traffic to understand what your application actually sends.
  • Verify that specific requests were made — or were not made — during a test run.
  • Replay the recorded expectations as mock expectations so your tests no longer depend on the real service.

​
Proxy modes

MockServer supports four proxy modes. Choose the one that fits your client and network setup.

Web proxy (HTTP)

Each request is forwarded dynamically using its Host header. Configure your HTTP client to use MockServer as an HTTP proxy.

Secure web proxy (HTTPS tunneling)

Requests are forwarded using an HTTP CONNECT request that establishes an HTTP tunnel. MockServer auto-generates an SSL certificate so encrypted HTTPS traffic is recorded transparently.

SOCKS proxy

Operates at the socket level using a SOCKS CONNECT command. You can configure a single client, an entire JVM, or the whole OS to route traffic through it. SSL traffic is also recorded transparently.

Port forwarding

All requests arriving on a specific local port are forwarded to a fixed remote host and port. No code changes required — just redirect traffic at the network or configuration level.
Port forwarding and SOCKS proxying are the most transparent modes and typically require no code changes. Web proxy and secure web proxy modes give you more control: only the clients you explicitly configure are proxied, and you can proxy multiple services simultaneously.

​
Configure your application to use the proxy

​
JVM system properties

The simplest way to route all JVM HTTP traffic through MockServer is to set the standard Java proxy system properties at startup: 
-Dhttp.proxyHost=localhost -Dhttp.proxyPort=1080
Most Java HTTP clients respect these properties automatically, including HttpURLConnection, Apache HttpClient, and Spring RestTemplate.

​
Java HTTP clients

private HttpURLConnection sendRequestViaProxy(URL url) throws IOException {
    Proxy proxy = new Proxy(
        Proxy.Type.HTTP,
        new InetSocketAddress(
            System.getProperty("http.proxyHost"),
            Integer.parseInt(System.getProperty("http.proxyPort"))
        )
    );
    return (HttpURLConnection) url.openConnection(proxy);
}

​
SOCKS proxy — JVM-wide configuration

To route all outbound connections from an entire JVM through the SOCKS proxy, override the default ProxySelector: 
ProxySelector.setDefault(new ProxySelector() {
    @Override
    public List<java.net.Proxy> select(URI uri) {
        return Arrays.asList(
            new java.net.Proxy(
                java.net.Proxy.Type.SOCKS,
                new InetSocketAddress(
                    System.getProperty("http.proxyHost"),
                    Integer.parseInt(System.getProperty("http.proxyPort"))
                )
            )
        );
    }

    @Override
    public void connectFailed(URI uri, SocketAddress sa, IOException ioe) {
        logger.error("Connection could not be established to proxy at socket [" + sa + "]", ioe);
    }
});

​
Port forwarding

Port forwarding requires no code changes in your application. Instead, configure MockServer with the remote host and port to forward to:
  • serverPort — the local port MockServer listens on.
  • proxyRemotePort — the port on the remote service to forward requests to.
  • proxyRemoteHost — the hostname or IP of the remote service (defaults to localhost if not set).
Then point your application at localhost:<serverPort> — or add an /etc/hosts entry mapping the real service hostname to localhost — and MockServer forwards all traffic to the configured remote endpoint.
Port forwarding can only proxy a single remote host and port. To forward traffic to multiple services, run separate MockServer instances on different local ports.

​
SSL traffic inspection

For HTTPS traffic, MockServer auto-generates a trusted SSL certificate per connection. This lets it decrypt, record, and re-encrypt traffic transparently — no changes to your application needed. Make sure your client trusts the MockServer CA certificate, or disable SSL verification in your test environment.

​
Recorded traffic and verification

Every request proxied through MockServer is stored internally. After your application runs, you can:
  • Retrieve recorded expectations to review or convert them into mock expectations.
  • Verify that specific requests were received, including proxy-forwarded requests.
See Record & Replay for the full workflow.