--- title: MockServer UI description: Real-time dashboard showing logs, active expectations, received requests, proxied traffic, LLM sessions, and a visual expectation composer. layout: page pageOrder: 3 section: 'General' subsection: true sitemap: priority: 0.7 changefreq: 'monthly' lastmod: 2026-05-27T00:00:00+01:00 ---

MockServer has a real-time dashboard that gives you full visibility into what MockServer is doing. Eight views are available from the navigation bar at the top of the page:

- Dashboard — four panels showing log messages, active expectations, received requests, and proxied requests
- Traffic — every captured request in a master list, with a rich detail pane on the right for LLM and MCP traffic
- Sessions — isolated LLM conversation sessions grouped into swim-lanes, plus a Compare tab for diffing two captured runs side-by-side
- Mocks — create or edit expectations of every kind (HTTP, gRPC, DNS, MCP, LLM) and import them (OpenAPI, WSDL, HAR, Postman) without writing any code
- Library — manage cassette files, WASM modules, and export traffic
- Chaos — configure and inject HTTP, gRPC, and TCP faults (added latency, error responses, dropped connections) that apply to all forwarded requests to a given upstream host or service, with a TTL so chaos auto-expires
- Drift — review mock drift records where stubbed responses diverge from the real upstream
- Metrics — JVM, request-latency, chaos, expectations-by-type, and MCP-tool-call charts (shown when metrics are enabled)

The dashboard connects to MockServer via WebSocket and updates in real time — any changes to expectations, new requests, or log events appear automatically without refreshing the page.

The UI is available for all versions of MockServer except the deployable WAR.

## Launch UI

### Browser

Open the dashboard in any browser:

http(s)://<host>:<port>/mockserver/dashboard

For example, if MockServer is running on localhost on port 1080:

http://localhost:1080/mockserver/dashboard

### MockServerClient or ClientAndServer

The UI can be opened programmatically using the openUI() method:

The openUI() method pauses for 1 second after launching the browser to allow the UI to start collecting logs. This ensures logs are visible even if MockServer is shutdown quickly by a test shutdown function (After, AfterClass, AfterAll, etc.). The pause period can be configured using openUI(TimeUnit timeUnit, long pause).

To simplify debugging when multiple MockServer instances are created, if the logLevel is set to DEBUG and the launchUIForLogLevelDebug configuration property is enabled (default: false), the ClientAndServer constructor will automatically launch the UI.

## Dashboard

The Dashboard view shows four panels in a 2×2 grid:

Area | Description
--- | ---
Title Bar | Shows connection status, keyboard shortcuts, and action buttons (auto-scroll, dark/light mode, clear/reset)
Request Filter | Collapsible filter panel — filter all panels by HTTP method, path, headers, query parameters, or cookies
Log Messages (top-left) | All log events, grouped by request correlation ID, with color-coded types
Active Expectations (top-right) | Currently registered expectations in priority order
Received Requests (bottom-left) | All HTTP requests received, most recent first, with their matched responses
Proxied Requests (bottom-right) | Forwarded requests with their actual responses from destination servers

For LLM expectations and requests, a second row of chips shows the LLM provider, model name, turn position (e.g. "turn 2 of 3"), and isolation key. Expanding any row shows the full JSON, aligned with the expectation ID column.

## Features

### Collapsible Items

All items in every panel are collapsed by default, showing a one-line summary (e.g. method and path for requests, timestamp and type for log entries). Click any row to expand it and see the full JSON details. This keeps the dashboard compact and lets you focus on the items you care about.

### Search

Each panel has its own search box that filters items by matching any part of the item's content. For example, searching for `POST` in the Received Requests panel will show only POST requests. The search covers all fields including headers, paths, and response bodies.

### Copy to Clipboard

Hover over any item to reveal a copy button. Clicking it copies the full content of that item to your clipboard as text. For grouped log entries (e.g. FORWARDED_REQUEST), the copy button copies the entire group including all child entries.

### Keyboard Shortcuts

Shortcut | Action
--- | ---
`⌘K` / `Ctrl+K` | Focus the Log Messages search box
`⌘L` / `Ctrl+L` | Reset the server (clear all logs, expectations, and requests)
`Esc` | Toggle the Request Filter panel

### Dark and Light Mode

The dashboard defaults to dark mode. Click the sun/moon icon in the title bar to switch between dark and light themes. Your preference is saved in the browser's local storage.

### Auto-Scroll

By default, panels auto-scroll to show the most recent items as they arrive. Click the pause/play button in the title bar to toggle auto-scroll.

### Clear and Reset

Click the clear icon in the title bar to access three options:

- Clear server logs — removes all log messages while keeping expectations and request history
- Clear server expectations — removes all active expectations while keeping logs and request history
- Reset server (all) — clears everything: logs, expectations, received requests, and proxied requests

## Request Filter

The Request Filter panel (toggled with `Esc` or by clicking the filter icon) appears on the Dashboard, Traffic, and Sessions views. It filters all panels by request properties:

- Method — HTTP method (GET, POST, PUT, DELETE, etc.)
- Path — request path (supports exact match)
- Headers — filter by request headers (name/value pairs)
- Query String Parameters — filter by query parameters (name/value pairs)
- Cookies — filter by cookies (name/value pairs)

The filter is sent to the MockServer backend via WebSocket, so filtering happens server-side and only matching data is sent to the browser.

## Log Messages

The Log Messages panel lists all log events recorded by MockServer. Events are displayed in reverse chronological order (most recent first) and are color-coded by type:

Log Type | Meaning
--- | ---
`RECEIVED_REQUEST` | An HTTP request was received by MockServer
`EXPECTATION_MATCHED` | A request matched an active expectation
`EXPECTATION_NOT_MATCHED` | A request did not match an expectation (with a "because" reason)
`EXPECTATION_RESPONSE` | A response was returned from a matched expectation
`NO_MATCH_RESPONSE` | No expectation matched — a default 404 response was returned
`FORWARDED_REQUEST` | A request was forwarded to a destination server (includes the response received)
`CREATED_EXPECTATION` | A new expectation was registered
`REMOVED_EXPECTATION` | An expectation was removed (expired or explicitly deleted)
`VERIFICATION` | A verification request was processed
`VERIFICATION_FAILED` | A verification check failed
`INFO` / `WARN` / `ERROR` | General server log messages

Related log events (e.g. request received → expectation matched → response sent) are grouped together by correlation ID and displayed with an orange left border. Click the expand button to see all related events within a group.

The because section in `EXPECTATION_NOT_MATCHED` entries can be expanded to show which properties matched and which did not, making it easy to debug why a request was not matched.

## Active Expectations

The Active Expectations panel shows all currently active expectations in the order they are applied, taking into account priority, timeToLive, and times. Each expectation is collapsed by default showing its ID, method, and path. Click to expand and see the full expectation definition including request matchers, actions, and timing constraints.

## Received Requests

The Received Requests panel shows all HTTP requests received by MockServer in reverse chronological order (most recent first). This includes requests that matched a mock expectation, requests that were proxied, and requests that received a default 404 response. Each item shows the method and path. Click to expand and see the full request details including headers, query parameters, and body, together with the response that MockServer returned.

## Proxied Requests

The Proxied Requests panel shows requests that were forwarded to a destination server along with the actual response received. Each item shows the method and path. Click to expand and see:

- The full request sent to the destination server
- The actual response received from the destination server (status code, headers, and body)

This is useful when using MockServer as a proxy to debug connectivity issues, inspect request/response pairs, or create expectations based on real traffic.

## Traffic

The Traffic view is purpose-built for inspecting captured request/response pairs. It covers all captured traffic in one place — both requests that matched a mock expectation and requests that were forwarded to a real upstream. Switch to it using the Traffic button in the navigation bar.

The Traffic view has two areas:

- Master list (left) — one row per request, showing the provider kind (Anthropic, OpenAI, Gemini, Ollama, MCP, HTTP), HTTP method and path, status code, and — for LLM calls — the model name and token counts.
- Detail pane (right) — shown when you click a row in the master list.

### LLM Usage Strip

For any LLM request, a thin strip appears above the detail tabs showing the provider, model name, token counts (input and output), estimated cost, and stop reason. This lets you see the key usage metrics at a glance without switching tabs.

### Detail Tabs by Traffic Kind

Traffic kind | Available tabs
--- | ---
Anthropic, OpenAI, OpenAI Responses, Gemini, or Ollama | Messages — the request body: system prompt, messages/contents, and tools definition Conversation — chat-transcript view (see below) Scripted Turns — shown when scripted conversation expectations are active; shows the turn predicate and scripted response for each turn SSE Timeline — decoded Server-Sent Events for streamed responses (shown when stream data is present) Raw JSON — the raw request and response JSON
MCP JSON-RPC | MCP — decoded JSON-RPC: method, id, params, and result or error Raw JSON — the raw request and response JSON
Any other HTTP traffic | Raw JSON only

### Conversation View

The Conversation tab renders LLM exchanges as a chat transcript. It is available for all five supported LLM providers: Anthropic, OpenAI, OpenAI Responses API, Gemini, and Ollama. User messages are left-aligned and assistant messages are right-aligned, styled as WhatsApp-style chat bubbles. System prompts appear as a distinct banner above the conversation. Tool calls and tool results each appear as their own labelled bubbles.

### SSE Timeline

The SSE Timeline tab shows each Server-Sent Event from a streamed LLM response as a separate row. This makes it easy to spot latency spikes within a single response. The final reassembled message is also shown. If the captured body was truncated (because it exceeded `maxStreamingCaptureBytes`), a banner indicates this.

### Capture as Mock

A Capture as mock button appears in the top-right of the detail pane for any LLM-kind request. Clicking it creates a mock expectation directly from the captured traffic — the next matching request will receive the same response without hitting the real API.

## Sessions

The Sessions view organises captured LLM traffic into swim-lanes grouped by isolated conversation session. Each swim-lane is labelled `<scenarioName> / <isolation-value>` (for example, `weather-agent / agent-A`) and shows chips for each captured turn. Click a chip to open the conversation view for that turn directly below the swim-lane.

The scenario name is the conversation name you supplied (or that MockServer auto-generated) when you registered the LLM conversation mock. The isolation value is the specific header, query parameter, or cookie value that identifies this session within the scenario — for example, the value of the `x-session-id` request header.

An Unscoped requests strip at the bottom holds requests that did not match any isolated scenario — for example, requests made outside a scripted conversation or without an isolation header.

Sessions are most useful when you have set up LLM conversation mocks with per-session isolation. Each unique session identifier (header, query parameter, or cookie value) gets its own swim-lane, so you can trace multiple concurrent test sessions independently.

### Compare

The Sessions view has a second tab, Compare, for comparing two captured conversation runs side-by-side. Pick Run A and Run B from the available sessions and the view shows a structural trajectory diff: the tool-call chain for each run and a per-turn token usage table. This makes it easy to spot regressions in agent behaviour between test runs.

## Composer

The Composer view lets you create or edit mock expectations without writing any code. Open it using the Composer button in the navigation bar.

At the top, choose an Expectation kind:

- Standard HTTP expectation — for any HTTP mock or proxy rule
- LLM Conversation — for multi-turn scripted LLM conversations

### Standard HTTP Expectation

The Edit existing or add new dropdown lists every active non-LLM expectation. Picking one prefills all fields so you can edit it in place; the Reset button clears the selection to start fresh.

The form is split into four steps:

1. Match a request — Expectation ID (optional — used to update an existing expectation), Method, Path, Headers, Query string parameters, Cookies, Path parameters, Body matcher, "Body is binary (base64)" toggle, HTTPS-only toggle, Priority (higher wins when multiple expectations match), Times (how many times the expectation can be used; 0 means unlimited). Prefix any string field or any entry line with `!` to negate it — for example, `!GET` matches any method except GET.
2. Respond with — choose a response action: Static HTTP response, Forward to upstream, Forward with override, Class callback, Response template, or Error / fault injection.
3. Action details — fields specific to the chosen action (status code and body for a static response; host and port for forwarding; template text for a template response; etc.).
4. Review & register — a read-only preview of the generated expectation in Java, JSON, or curl format. Click Register expectation to activate it on the server. If the Expectation ID field is filled, this updates the existing expectation in place.

### LLM Conversation

The Edit existing or add new dropdown lists active scripted LLM conversation scenarios by name (for example, `weather-agent (2 turns)`). Picking one prefills the form with the existing scenario's configuration.

The form is split into three steps:

1. Conversation basics — provider (Anthropic, OpenAI, Gemini, etc.), path to match (e.g. `/v1/messages`), optional model name, and optional per-session isolation (header, query parameter, or cookie name whose value is used to keep concurrent sessions independent).
2. Turns — an ordered list of conversation turns. Each turn has an optional match predicate (turn index, message content substring, message role, or tool result presence) and an optional response (text, tool calls, stop reason, token usage, streaming flag).
3. Review & register — preview in Java, JSON, or MCP format, then click Register on server (or Update N expectations when editing). When editing an existing scenario, the expectation IDs are reused so the update happens in place.

See LLM Conversation Mocking for full details on conversation predicates and isolation options.

## Library

The Library view consolidates fixture file management and traffic export. It has two sub-tabs: Export and Cassettes.

### Cassettes

The Cassettes sub-tab lets you record the current MockServer state into a JSON cassette file and load one back. A recorded cassette file contains all captured LLM/MCP traffic as mock expectations, with sensitive headers (API keys, auth tokens, cookies) automatically redacted. The file can be committed to version control and loaded in tests for deterministic, offline replay.

To record: set the output file path and click Record. To load a cassette for replay: enter the file path and click Load. These operations call the `record_llm_fixtures` and `load_expectations_from_file` MCP tools on your behalf.

### Export

The Export sub-tab lets you download captured content from the running MockServer instance. Pick the export to perform from the dropdown and click Download. Each option crosses one of two scopes — the currently registered expectations or the recorded requests MockServer has handled — with one of eight file formats. A few formats apply to only one scope (the dropdown filters itself to the scope you pick):

Format | Contents | Re-importable into
--- | --- | ---
MockServer JSON | Round-trippable JSON in MockServer's own expectation format. | MockServer (`PUT /mockserver/expectation` or `load_expectations_from_file`).
MockServer Java DSL (expectations only) | Java code using the MockServer DSL that recreates each expectation. | A JUnit test or MockServer Java client — paste the code in directly.
HAR (HTTP Archive) | Each item as a request/response pair, in the standard HAR format. | Browser DevTools, HAR analysis tools, performance analysers.
OpenAPI 3 spec | One operation per (method, path) with the response body as an example. | Swagger UI, Redoc, code generators, API gateways.
Postman collection v2.1 | Each item as a Postman request with its example response. | Postman, Newman, Insomnia (via import).
Bruno collection (.zip) | One `.bru` file per request, plus a `bruno.json` manifest, packaged as a zip. | Bruno — unzip and open the folder as a collection.
Log entries (JSON) (requests only) | Raw MockServer log events for the captured request/response pairs (verbose JSON, mainly for debugging). | MockServer log tooling or manual inspection.
cURL commands (requests only) | One cURL command per captured request. | Any shell — paste in to replay the captured traffic.

OpenAPI, Postman, and Bruno exports are best-effort: positive-string matchers round-trip cleanly, but MockServer's NottableString negation, regex bodies, and dynamic actions (forward / template / callback / error / LLM) appear as placeholder text since those formats describe client requests + example responses rather than full mock-server expectation graphs. Use MockServer JSON when you need a lossless round-trip.

## Chaos

The Chaos view groups service-scoped chaos into three collapsible sections — HTTP Service Chaos, gRPC Chaos (health status + fault injection), and TCP-Layer Chaos — each with its own Clear button (Clear HTTP / Clear gRPC / Clear TCP) in its header.

It lets you inject service-scoped chaos — faults that MockServer applies to every request it forwards to a given upstream host or service, rather than to a single expectation. This is useful for resilience and SRE testing, where you want all proxied traffic to a dependency to fail or slow down for a while without editing individual mocks.

Under Register chaos for a host, enter the upstream Host and any combination of the following faults, then click Register:

- Error status — an HTTP error status code (e.g. `503`) returned instead of forwarding, optionally with an Error prob (0–1) so only a fraction of requests fail.
- Drop prob — a probability (0–1) that MockServer drops the connection instead of responding.
- Latency ms — milliseconds of delay added to every matched forward.
- TTL ms — how long the chaos stays active, in milliseconds. When the TTL elapses MockServer automatically reverts the fault (a dead-man's switch), so a forgotten chaos run cannot break later tests.

The Active registrations panel lists each host with chaos in force and its remaining auto-revert countdown (or shows No service-scoped chaos registered when none is set). Remove a single host's chaos with its remove icon (trash), or use the section's Clear HTTP / Clear gRPC / Clear TCP button to remove everything in that section at once. Injected faults are also counted in the Metrics view under HTTP Chaos Faults.

## Drift

The Drift view surfaces mock drift — where a stubbed response no longer matches what the real upstream returns. When MockServer proxies a request that also has a matching response expectation, it compares the two and records any differences. Each row shows the affected expectation, the drift type (status, schema field added/removed, schema type changed, or header added/removed/changed), the field, the expected vs actual values, a confidence score, and the time. Filter by expectation, or use Clear to reset the recorded drift. This makes it easy to spot stubs that have silently fallen out of sync with the services they stand in for.

## Metrics

The Metrics view charts MockServer's own runtime metrics. It is only populated when metrics collection is enabled (configuration property `metricsEnabled` / `MOCKSERVER_METRICS_ENABLED`); otherwise the view shows Metrics are disabled with the flag and environment variable needed to turn them on.

When enabled, the view shows:

- Throughput — a derived requests-per-second figure with a trend chart.
- Request latency — p50, p95, and p99 response-time percentiles, derived from MockServer's request-duration histogram.
- HTTP Chaos Faults — injected faults broken down by type, plus the currently active service-scoped chaos (see the Chaos view).
- Request activity and Actions executed — cumulative request and action counters over time.
- Expectations by type — the number of active expectations broken down by action type (one line per type), and MCP tool calls per tool.
- JVM heap memory and Threads & GC — heap used/committed, thread counts, garbage-collection totals, and related JVM runtime figures.

## Real-Time Updates

The dashboard connects to MockServer via WebSocket and receives updates automatically. The connection status is shown in the title bar as a coloured chip:

- Connected — actively receiving updates
- Connecting — attempting to establish a connection
- Error — connection failed (will auto-retry with exponential backoff)
- Disconnected — not connected to MockServer

Updates are throttled to at most one per second to prevent UI flooding during high-traffic scenarios.