MQTT failures often depend on several clients, a specific message order, and precise timing. Replay saves that flow, runs it again against your broker, and shows whether the expected result still holds.
Loading...
Some MQTT failures only appear when several clients connect, publish, and respond in a precise order. Repeating that flow by hand makes a fix difficult to verify.
This guide uses the bundled demo to show how Replay runs the same flow again and checks the result. You can read it as a visual tour without installing Mqttable, or follow the same steps in Mqttable Desktop.
The dark screenshots preserve an earlier Replay interface labeled Checks; the new light screenshots show the current Expected results interface. The steps below use the current labels.
A Replay Scenario is a saved sequence of MQTT client actions built from Trace, a Mqttable TraceGrid CSV export, PCAP evidence, or the bundled demo. It can coordinate several clients and preserve or reshape their original timing.
Dry Run resolves the target, clients, credentials, steps, timing, and safety rules without sending Replay traffic. Run Trace then records what the replay clients actually sent and received. An Expected result saves one important received message from that trace so the next run can judge it automatically.
The demo used below contains 89 source rows. Mqttable converts them into 39 executable MQTT steps across 7 clients and 8 outbound PUBLISH Topics. Broker responses and received PUBLISH rows remain evidence instead of becoming duplicate send actions.
To follow the actions, you need:
The screenshots use Replay Docs Demo · mqtt://127.0.0.1:3883, an anonymous Broker bound only to loopback. Follow MQTT Quickstart or Brokers and Connections if you still need to create a target.
The bundled Replay demo is a trusted exception to normal plan limits. You can open, configure, Dry Run, and run the complete demo without signing in or buying Pro. Your own Free scenarios can run up to 15 executable Replay Steps.
Replay accepts a Mqttable TraceGrid CSV or opens the bundled demo as a saved Scenario.
Mqttable opens Demo TraceGrid CSV replay as a Scenario tab. No MQTT traffic has been sent yet. If the demo already exists, Try demo opens the saved copy without overwriting your edits.
The Scenario starts with Details expanded. Read the source facts before choosing Run Replay:
The Scenario keeps its source, target, execution settings, saved result conditions, and result views in one workspace.
Select the target chooser. Mqttable lists saved Broker targets and previews the endpoint before selection.
The chooser lists saved Broker names and endpoints; select the isolated loopback listener before sending Replay traffic.
If no targets appear, return to Connections, create the test Broker, then reopen Replay. The target also needs at least one enabled MQTT client; otherwise Dry Run reports Add or enable a target MQTT client.
Select Configure. Options control identity, credentials, timing, and Broker side effects. Changing any of these execution inputs requires a new Dry Run.
General selects the saved Scenario and target; Client sessions decide which identities and credentials will connect.
Option | Demo default | What it changes |
|---|---|---|
Name | Demo TraceGrid CSV replay | Changes the saved Scenario label only. |
Target | The selected target | Changes the Broker that receives Replay traffic. |
Generate safe replay client IDs | On | Rewrites each captured Client ID with an isolated deterministic ID. Keep this on for ordinary testing. |
Reuse captured client IDs | Off | Reuses original identities and may disconnect matching live clients or alter their persistent Sessions. |
Replay client ID template | Product default | Controls generated IDs. The default keeps source mappings distinct without taking over the source identity. |
Credential policy | Fallback to selected target | Uses target credentials when a source client has no saved credential. Strict mode requires a match for every client. |
In the same sheet, review execution guardrails and Topic rewrites. The light screenshot opens one illustrative rule to show its fields; remove that draft before Dry Run.
Guardrails limit side effects and pace; the draft Topic rewrite row shows the available fields but was removed before execution.
Option | Behavior |
|---|---|
Send as non-retained | Clears Retain so the test does not replace Broker retained state. |
Stop on first failure | Stops after the first failed MQTT action instead of continuing a partial flow. |
Keep captured timing | Preserves evidence time offsets. This is the demo default. |
Send immediately | Ignores captured gaps. Max publish rate limits outgoing PUBLISH messages. |
Scale captured timing | Applies Timing scale. 2.0 is twice as fast; 0.5 is half speed. |
Condense idle gaps | Preserves order but shortens pauses longer than Max idle gap. |
Topic rewrite rules | Match and replace Topics for Publish, Subscribe, or Unsubscribe. Rules
support $1, $2, and |
Scaled and condensed timing require Pro for ordinary scenarios. The trusted bundled demo can use them without signing in. The newly opened demo initially says Retain as captured; turn on Send as non-retained for this isolated run. The second screenshot briefly opens an illustrative Topic rewrite rule to show the fields, then removes it before Dry Run. Keep the other settings unchanged and select Dry Run to save and verify them.
Select Dry Run. Mqttable resolves the current source, target, Options, credentials, client identities, and safety rules without connecting replay clients or sending Replay traffic.
When Dry Run finishes, select Details to collapse the Scenario summary. This gives the result panel more vertical space. The collapse preference stays in the current app session, survives LiveView updates, and does not change the Scenario or Dry Run result.
With Details collapsed, the result panel shows readiness, target, plan size, clients, duration, and the start of the review list; scroll to read every warning.
A passed Dry Run unlocks Run Replay. Changing the target, source, client identity, credentials, guardrails, timing, or Topic rules invalidates that approval and requires another Dry Run.
If Dry Run is blocked, read the first blocker before changing anything. Common causes are a missing target, an unreachable Broker, invalid credentials, a Client ID conflict, or an unsafe Scenario option.
Select Run Replay. The demo connects its isolated clients, performs the MQTT actions in order, records Broker responses and received messages, then disconnects.
Keep Details collapsed while reading the result. Run Trace is the evidence for this execution, not a generic application log.
Run Trace shows the complete execution result: lifecycle totals, status, filters, and the MQTT rows captured from this run.
The lifecycle totals answer how much work ran. The rows answer what happened. A sent PUBLISH proves that a replay client dispatched the command; a matching RECV PUBLISH proves that a subscribed replay client received the delivery.
Run Trace is process-memory evidence. Restarting Mqttable or pruning old run sessions can remove it, while the Scenario and saved Expected results remain.
Filter Run Trace to demo/replay/final/commands/gw/restart-pump. Find the sent command and the matching received PUBLISH. Right-click the RECV PUBLISH row and select Set this message as expected.
The saved delivery condition starts from observed receive evidence that Mqttable can tie to a causal Replay PUBLISH step.
Expand Details and select Expected results → View to inspect the saved contract.
The saved delivery condition stores received content, QoS, Retain, causal step, and wait window while keeping technical evidence inspectable.
Protocol responses such as CONNACK, SUBACK, PUBACK, UNSUBACK, and PINGRESP are checked by their Replay Steps. Expected results handle the business delivery. You can also save an exact subscription count from a replay client's SEND SUBSCRIBE row.
Close Expected results and select Run Replay again. Adding or adjusting an Expected result does not change the MQTT execution fingerprint, so the passed Dry Run remains current when no execution input changed.
After the rerun finishes, expand Details so the Expected results summary and Run Trace are visible together. In the Chinese local capture, the initial 293 ms wait was too short: the nearest matching receive arrived after 564 ms. The sheet allowed adjusting only the wait to one second, without changing the expected Topic or Payload; the following rerun matched. The English capture matched at its original 303 ms window. If your own result misses its wait window, inspect the nearest evidence before widening it.
Scenario completion and the saved delivery condition are separate: execution finished, and the expected receive matched.
Replay preserves execution status separately from the Expected results summary:
After learning the workflow with the demo, create your own Scenario from:
Replay is semantic MQTT replay. It reproduces client actions, session lifecycles, timing, protocol expectations, and selected business results. It does not reproduce exact TCP segmentation, network jitter, or Broker internal state.
Keep these boundaries:
The trusted bundled demo can run all 39 steps and use every pace mode without an account. For your own Free scenarios, you can keep up to three Scenario tabs, run up to 15 executable Replay Steps, and use immediate or captured timing. Pro removes those depth limits and adds scaled or condensed timing.
