--- title: Clock Control description: Freeze, advance, or reset MockServer's controllable clock for deterministic time-based testing of date-sensitive responses and expectation TimeToLive. layout: page pageOrder: 4.5 section: 'General' subsection: true sitemap: priority: 0.7 changefreq: 'monthly' lastmod: 2026-05-30T08:00:00+00:00 ---

MockServer exposes a controllable clock that lets you freeze time at a specific instant, advance it by a duration, or reset it to real wall-clock time. This is useful for deterministic testing of date-sensitive responses, such as:

Response templates that embed timestamps via now_iso_8601, now_epoch, now_rfc_1123, or the dates helper
Expectation TimeToLive expiry — freezing the clock prevents expectations from expiring during a test

The clock is controlled via two endpoints:

PUT /mockserver/clock — freeze, advance, or reset the clock
GET /mockserver/clock — query the current clock status

Both endpoints are protected by control-plane authentication (JWT or mTLS) when configured.

Limitation: the controllable clock affects response template date/time helpers and expectation TimeToLive expiry. Event-log timestamps and JWT token issuance use a separate time source and are not affected by clock control.

Freeze the server clock at a given ISO-8601 instant. If instant is omitted, the clock freezes at the current real time.

// freeze at a specific instant
new MockServerClient("localhost", 1080)
    .freezeClock(Instant.parse("2025-01-15T09:30:00Z"));

// freeze at the current real time
new MockServerClient("localhost", 1080)
    .freezeClock();

curl -v -X PUT "http://localhost:1080/mockserver/clock" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "freeze",
    "instant": "2025-01-15T09:30:00Z"
}'

Response:

{
  "status" : "freeze",
  "currentInstant" : "2025-01-15T09:30:00Z",
  "currentEpochMillis" : 1736933400000
}

See REST API for full JSON specification

Advance the frozen clock forward by the specified number of milliseconds. If the clock is not already frozen, it is first frozen at the current real time, then advanced.

new MockServerClient("localhost", 1080)
    .advanceClock(Duration.ofHours(1));

curl -v -X PUT "http://localhost:1080/mockserver/clock" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "advance",
    "durationMillis": 3600000
}'

Response:

{
  "status" : "advance",
  "currentInstant" : "2025-01-15T10:30:00Z",
  "currentEpochMillis" : 1736937000000
}

See REST API for full JSON specification

Reset the server clock back to real wall-clock time.

new MockServerClient("localhost", 1080)
    .resetClock();

curl -v -X PUT "http://localhost:1080/mockserver/clock" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reset"
}'

Response:

{
  "status" : "reset",
  "currentInstant" : "2026-05-30T12:00:00Z",
  "currentEpochMillis" : 1780228800000
}

See REST API for full JSON specification

Check whether the clock is frozen and what time it currently reports.

String clockJson = new MockServerClient("localhost", 1080)
    .clockStatus();

curl -v -X GET "http://localhost:1080/mockserver/clock"

Response:

{
  "currentInstant" : "2025-01-15T09:30:00Z",
  "currentEpochMillis" : 1736933400000,
  "frozen" : true
}

See REST API for full JSON specification