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.
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. A Replay Check saves one important result 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, Checks, and result views in one workspace.
Select the target chooser. Mqttable lists saved Broker targets and previews the endpoint before selection.
Target selection is explicit because Run Replay will connect to this Broker and send real MQTT 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. |
Scroll down in the same sheet to review execution guardrails and Topic rewrites.
Guardrails limit side effects and pace; Topic rewrite rules can move the whole MQTT lifecycle into a test namespace.
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. Keep the demo defaults for this first run, then select Close.
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, impact, and attention items together.
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 Checks 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 Add delivery check.
A delivery check starts from observed receive evidence that Mqttable can tie back to a causal Replay PUBLISH step.
Open Checks → Manage to inspect the saved contract.
The Check stores a precise delivery contract while keeping the underlying Run Trace evidence inspectable.
Protocol responses such as CONNACK, SUBACK, PUBACK, UNSUBACK, and PINGRESP are checked by their Replay Steps. Delivery Checks handle the business result. You can also create an exact subscription count check from a replay client's SEND SUBSCRIBE row.
Close the Checks dialog and select Run Replay again. Adding or editing Checks 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 Checks summary and Run Trace result are visible together.
Scenario completion and Check evaluation are separate results: Finished confirms execution; PASS confirms the saved delivery condition.
Replay preserves the execution status separately from the PASS / FAIL result:
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.
