Tutoriel MQTTX : tester un broker avec le client desktop et la CLI

MQTTX est un client MQTT open source d'EMQ disponible en trois versions : une application desktop (Windows, macOS, Linux), un outil en ligne de commande appelé mqttx et une version navigateur. Il parle MQTT 3.1, 3.1.1 et 5.0 sur TCP, TLS, WebSocket et WebSocket sécurisé, et fonctionne avec n'importe quel broker conforme — pas seulement EMQX.

Ce tutoriel couvre ce que les développeurs utilisent vraiment pour tester un broker : configurer des connexions, inspecter les propriétés MQTT 5, transformer les payloads avec des scripts, et piloter la CLI pour du pub/sub scripté, des appareils simulés et des tests de charge avec mqttx bench.

Installer MQTTX

Vérifiez la CLI avec mqttx --version. Si vous avez seulement besoin d'un test rapide depuis le navigateur sans rien installer, le client MQTT en ligne de ce site couvre les bases du pub/sub sur WebSocket.

L'application desktop : des connexions identiques à la production

Cliquez sur New Connection et remplissez les champs exactement comme vos appareils les utiliseront — un test qui diffère de la production ne prouve rien.

Sous Advanced, vous trouverez le keep-alive, le délai de connexion, la reconnexion automatique et, pour MQTT 5, les propriétés du CONNECT : session expiry interval, receive maximum, maximum packet size, topic alias maximum et user properties. La section Last Will configure le topic, le payload, la QoS, le flag retain et le will delay interval — pratique pour tester l'envoi du Last Will.

Si une connexion échoue, l'erreur apparaît dans le journal de la connexion. Les brokers MQTT 5 renvoient un reason code ; collez-le dans l'outil de recherche de reason codes pour savoir ce qu'il signifie.

S'abonner et publier

Utilisez New Subscription avec un filtre de topic comme testmqtt/mqttx/#. Chaque abonnement reçoit une couleur, et les messages entrants prennent la couleur de l'abonnement qui a correspondu — le moyen le plus rapide de repérer des wildcards qui se chevauchent. Un doute sur un filtre ? Essayez-le dans le topic matcher.

En bas de la fenêtre se trouve la zone de publication : topic, QoS, flag retain et payload. Le sélecteur de type de payload (Plaintext, JSON, Base64, Hex et d'autres selon la version) détermine à la fois la saisie du message sortant et le décodage des payloads entrants. Le mode JSON valide et met en forme, ce qui révèle immédiatement une télémétrie cassée.

Pour MQTT 5, cliquez sur l'icône des propriétés à côté de la zone de publication pour définir :

• Content type et payload format indicator
• Message expiry interval
• Topic alias
• Response topic et correlation data pour le request/response
• User properties sous forme de paires clé/valeur

Les messages reçus affichent leurs propriétés dans la bulle du message : vous pouvez ainsi vérifier que le broker les a bien transmises. MQTTX devient alors un bon complément manuel aux tests des fonctionnalités MQTT 5.

Scripts et messages planifiés

La fonction Script vous permet d'écrire une petite fonction JavaScript qui transforme un payload avant sa publication ou après sa réception. L'exemple classique simule un capteur :

/**
 * Remplace la température et l'humidité par des valeurs aléatoires à chaque publication.
 * @param value le payload saisi dans la zone de publication, p. ex. {}
 */
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);

Enregistrez le script, appliquez-le à la connexion (messages publiés, reçus ou les deux) et combinez-le avec Timed Message pour publier toutes les quelques secondes. Vous avez un faux appareil sans écrire de client complet. L'API de script a évolué entre les versions : consultez les exemples intégrés de votre version si execute n'est pas reconnu.

La CLI mqttx

C'est dans la CLI que MQTTX excelle pour les tests reproductibles. Quatre sous-commandes couvrent l'essentiel : conn, sub, pub et 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 affiche le topic à côté de chaque payload, indispensable avec des wildcards. D'autres options utiles :

Voici la même publication en WebSocket sécurisé, comme le ferait une application navigateur :

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'

Lancez mqttx pub --help pour la liste complète ; des flags sont parfois ajoutés ou renommés d'une version à l'autre.

Appareils simulés

mqttx simulate publie des données réalistes à partir de scénarios intégrés ou de votre propre fichier de script. Listez les scénarios disponibles dans votre version avec mqttx ls --scenarios, puis lancez-en un :

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

%c est remplacé par le client ID : chaque appareil simulé a donc son propre topic. Abonnez-vous à testmqtt/mqttx/sim/# dans un autre terminal pour suivre le flux.

Tests de charge avec mqttx bench

mqttx bench exécute des benchmarks de connexion, de publication et d'abonnement depuis un seul processus :

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 est l'index du client : le publisher 7 parle donc à l'abonné 7. La sortie indique les clients connectés et le débit de messages par seconde ; si le débit reçu dans le terminal 1 reste inférieur au débit envoyé dans le terminal 2, quelque chose sature entre les clients et le broker. Pour interpréter ces chiffres et découvrir des outils plus lourds, voir tests de charge d'un broker MQTT.

Desktop ou CLI ?

• Desktop pour explorer : comparer des formats de payload, surveiller plusieurs abonnements, manipuler à la main les propriétés MQTT 5.
• CLI pour répéter : scripts shell, pipelines CI, serveurs accessibles en SSH, et tout ce que vous voulez coller dans un rapport de bug.
• Aucun des deux quand vous avez besoin d'assertions. MQTTX affiche les messages, il ne fait pas échouer un build. Pour des vérifications automatisées, encapsulez mqttx dans un script qui contrôle la sortie, ou écrivez des tests avec une bibliothèque cliente — voir tests MQTT dans GitHub Actions.

Pour comparer MQTTX avec MQTT Explorer, la CLI HiveMQ et d'autres outils, consultez le comparatif des clients MQTT desktop.

Suivre vos messages MQTTX dans le navigateur

MQTTX couvre tout le cycle, des clics dans l'interface aux benchmarks scriptés, avec un seul outil et un seul jeu de paramètres de connexion. Enregistrez une connexion par environnement, gardez vos commandes CLI dans le dépôt à côté de votre firmware, et vous reproduirez n'importe quel problème de broker en une minute.

Questions fréquentes