Injected Latency

A stub server answers from a canned definition, so it replies as fast as the process can write bytes — often in single-digit milliseconds. That is faster than any real dependency will ever be, and it quietly hides every branch a client has for waiting: progress indicators, cancellation, deadlines, back-pressure. WireMock's delay methods exist to put the slowness back on purpose, and there are three sampling shapes to choose between. ## Where a WireMock delay is declared Every delay discussed here belongs to WireMock's `ResponseDefinitionBuilder` — the object `aResponse()` returns and `willReturn(` consumes. It is a property of the **reply**, not of the matcher: a WireMock delay changes *when* a stub answers, never *which* stub is selected. Because it is part of the response definition it serialises into the stub mapping alongside the status and body, so a delay written with WireMock's `withFixedDelay(` appears in the committed mapping file as `fixedDelayMilliseconds`, and the two random forms appear as a `delayDistribution` object. ## The three methods, side by side | Product | Method | Parameters | What one call gets | |---|---|---|---| | WireMock | `withFixedDelay(Integer)` | one figure, milliseconds | the same pause every time | | WireMock | `withUniformRandomDelay(int, int)` | lower and upper bound | an even draw between the bounds | | WireMock | `withLogNormalRandomDelay(double, double)` | median and sigma | a skewed draw with a long tail | - WireMock's `withFixedDelay(3000)` is the deterministic instrument: every request that stub answers waits the same three seconds, which is exactly what a test asserting a boundary needs. - WireMock's `withUniformRandomDelay(200, 1200)` samples afresh on every call from a flat distribution, so any value between the bounds is equally likely and nothing outside them ever happens. - WireMock's `withLogNormalRandomDelay(400, 1)` samples from a log-normal curve whose `median` argument is the 50th percentile in milliseconds, while `sigma` is the standard deviation of the underlying normal distribution. - A larger `sigma` in WireMock's `withLogNormalRandomDelay(` produces a longer right-hand tail — most calls land near the median and a few land far above it, which is the shape real service latency actually has. - WireMock's three-argument `withLogNormalRandomDelay(double median, double sigma, Double maxValue)` truncates that tail by resampling anything above `maxValue`, so a long-tailed stub cannot occasionally stall a whole suite. WireMock rejects a `maxValue` below the median outright. - Both random forms are convenience wrappers: WireMock's `withRandomDelay(DelayDistribution)` is the underlying method, and the uniform and log-normal helpers simply construct the distribution for you. ## What all three have in common WireMock applies a response delay *before* it writes anything at all. Under WireMock's `withFixedDelay(3000)` the client does not receive an early status line and then stall; it sees nothing whatsoever on the socket for three seconds, and then the entire reply — status, headers and body — arrives together. That is deliberately different from WireMock's `withChunkedDribbleDelay(`, which is slow *while transferring* rather than slow *before answering*, and it is why that method is a separate property rather than a fourth distribution. The wait itself is not free. By default WireMock spends it as a sleep on the thread handling the request, so a stub server holding many delayed responses at once can exhaust its container threads long before the delay figures themselves look large. Starting WireMock with `--async-response-enabled` (or building the server with `wireMockConfig().asynchronousResponseEnabled(true)`) moves the waiting onto a scheduled executor instead, which is what makes generous delays affordable under concurrency. ## Choosing one for a hearing-aid fitting stub set 1. Reach for WireMock's `withFixedDelay(` when the test asserts something about a specific duration — that the fitting screen still shows its progress indicator, or that the client gives up precisely where you expect it to. 2. Reach for WireMock's `withUniformRandomDelay(` when you want ordinary jitter with a hard ceiling, for instance a `GET /fitting/devices/{deviceSerial}/telemetry` stub that should never answer instantly but should never be pathological either. 3. Reach for WireMock's `withLogNormalRandomDelay(` when the point is that most calls are quick and a few are not — the shape that finds the code path nobody exercised — usually with the third `maxValue` argument set so the tail stays bounded. ## Mistakes worth naming - Treating WireMock's `withUniformRandomDelay(` and `withLogNormalRandomDelay(` as interchangeable. Uniform has hard bounds and no tail; log-normal has a median and an unbounded tail unless you truncate it. - Reading `sigma` in WireMock's `withLogNormalRandomDelay(` as a maximum. It is a spread parameter; the maximum is the optional third argument. - Asserting an exact elapsed time against a WireMock stub that uses a random delay. The sample changes on every call, so only bounds are safely assertable. - Assuming a WireMock delay slows the *request*. It does not: the request is fully received and matched first, and only the reply is held back. - Forgetting that a WireMock delay is serialised into the mapping, which means it travels with the file to every other instance that loads it.