MQTTX Tutorial: Test Brokers with the Desktop and CLI Client

MQTTX is an open-source MQTT client from EMQ that comes in three flavours: a desktop app (Windows, macOS, Linux), a command-line tool called mqttx, and a browser version. It speaks MQTT 3.1, 3.1.1 and 5.0 over TCP, TLS, WebSocket and secure WebSocket, and it works with any compliant broker — not just EMQX.

This tutorial walks through the parts developers actually use when testing a broker: setting up connections, inspecting MQTT 5 properties, transforming payloads with scripts, and driving the CLI for scripted pub/sub, simulated devices and mqttx bench load tests.

Install MQTTX

Check the CLI with mqttx --version. If you only need a quick check from a browser without installing anything, the online MQTT client on this site does the same pub/sub basics over WebSocket.

The desktop app: connections that match production

Click New Connection and fill in the fields exactly as your devices will use them — a test that differs from production proves nothing.

Under Advanced you will find keep-alive, connect timeout, auto-reconnect and, for MQTT 5, the CONNECT properties: session expiry interval, receive maximum, maximum packet size, topic alias maximum and user properties. The Last Will section configures the will topic, payload, QoS, retain flag and will delay interval — useful for testing Last Will delivery.

If a connection fails, the error appears in the connection log. MQTT 5 brokers return a reason code; paste it into the reason code lookup to see what it means.

Subscribing and publishing

Use New Subscription with a topic filter such as testmqtt/mqttx/#. Every subscription gets a colour, and incoming messages are tinted with the colour of the subscription that matched — the fastest way to see overlapping wildcards. Not sure a filter matches? Try it in the topic matcher.

At the bottom of the window is the publish box: topic, QoS, retain flag and payload. The payload type selector (Plaintext, JSON, Base64, Hex, and others depending on the version) controls both how you type the outgoing message and how incoming payloads are decoded. JSON mode validates and pretty-prints, which catches broken telemetry immediately.

For MQTT 5, click the properties icon next to the publish box to set:

• Content type and payload format indicator
• Message expiry interval
• Topic alias
• Response topic and correlation data for request/response
• User properties as key/value pairs

Received messages show their properties in the message bubble, so you can confirm the broker forwarded them. That makes MQTTX a convenient manual companion to MQTT 5 feature testing.

Scripts and timed messages

The Script feature lets you write a small JavaScript function that transforms a payload before it is published or after it is received. The classic example simulates a sensor:

/**
 * Replace temperature and humidity with random values on every publish.
 * @param value the payload typed in the publish box, e.g. {}
 */
function handlePayload(value) {
  let data = value;
  if (typeof value === 'string') {
    data = JSON.parse(value);
  }
  data.temperature = Math.round(Math.random() * 400) / 10;
  data.humidity = Math.floor(Math.random() * 100);
  return JSON.stringify(data, null, 2);
}

execute(handlePayload);

Save the script, apply it to the connection (published messages, received messages, or both) and combine it with Timed Message to publish every few seconds. You now have a fake device without writing a full client. The script API has changed between releases, so check the built-in examples in your installed version if execute is not recognised.

The mqttx CLI

The CLI is where MQTTX shines for repeatable tests. Four subcommands cover most work: conn, sub, pub and bench.

mqttx conn -h broker.connectmq.com -p 1883 \
  -u "$MQTT_USER" -P "$MQTT_PASS" -i testmqtt-cli-check

mqttx sub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/mqttx/#' -q 1 -v

mqttx pub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/mqttx/sensor-1' -q 1 -r \
  -m '{"temperature":21.5}'

-v prints the topic next to each payload, which is essential with wildcards. Other options you will reach for:

Here is the same publish over secure WebSocket, which is what a browser app would use:

mqttx pub -h broker.connectmq.com -p 8084 -l wss --path /mqtt \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/mqttx/ws' -m 'hello over wss'

Run mqttx pub --help for the full list; flags are occasionally added or renamed between releases.

Simulated devices

mqttx simulate publishes realistic data from built-in scenarios or your own script file. List the scenarios available in your version with mqttx ls --scenarios, then run one:

mqttx simulate -sc tesla -c 10 \
  -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/mqttx/sim/%c'

%c expands to the client ID, so each simulated device gets its own topic. Subscribe to testmqtt/mqttx/sim/# in another terminal to watch the stream.

Load testing with mqttx bench

mqttx bench runs connection, publish and subscribe benchmarks from a single process:

mqttx bench conn -c 500 -i 10 \
  -h broker.connectmq.com -p 1883 -u "$MQTT_USER" -P "$MQTT_PASS"

mqttx bench sub -c 50 -t 'testmqtt/bench/%i' -q 1 \
  -h broker.connectmq.com -p 1883

mqttx bench pub -c 50 -im 100 -t 'testmqtt/bench/%i' -q 1 \
  -h broker.connectmq.com -p 1883 -m '{"v":1}'

%i is the client index, so publisher 7 talks to subscriber 7. The output shows connected clients and the message rate per second; when the received rate in terminal 1 stays below the sent rate in terminal 2, something between the clients and the broker is saturated. For how to read those numbers, and for heavier tools, see MQTT broker load testing.

Desktop or CLI?

• Desktop when you explore: comparing payload formats, watching several subscriptions, poking at MQTT 5 properties by hand.
• CLI when you repeat: shell scripts, CI pipelines, servers you reach over SSH, and anything you want to paste into a bug report.
• Neither when you need assertions. MQTTX shows messages; it does not fail a build. For automated checks, wrap mqttx in a script that checks the output, or write tests with a client library — see MQTT testing in GitHub Actions.

If you want to compare MQTTX with MQTT Explorer, the HiveMQ CLI and other tools, see desktop MQTT clients compared.

Watch your MQTTX messages in the browser

MQTTX covers the whole loop from clicking around to scripted benchmarks with one tool and one set of connection settings. Save a connection per environment, keep your CLI commands in the repository next to your firmware, and you will be able to reproduce any broker issue in a minute.

Frequently asked questions