Tutorial do MQTTX: teste brokers com o cliente desktop e a CLI

O MQTTX é um cliente MQTT open source da EMQ que vem em três variantes: um app desktop (Windows, macOS, Linux), uma ferramenta de linha de comando chamada mqttx e uma versão para navegador. Ele fala MQTT 3.1, 3.1.1 e 5.0 sobre TCP, TLS, WebSocket e WebSocket seguro, e funciona com qualquer broker compatível — não só com o EMQX.

Este tutorial percorre as partes que os desenvolvedores realmente usam ao testar um broker: configurar conexões, inspecionar propriedades do MQTT 5, transformar payloads com scripts e usar a CLI para pub/sub automatizado, dispositivos simulados e testes de carga com mqttx bench.

Instalar o MQTTX

Verifique a CLI com mqttx --version. Se você só precisa de uma checagem rápida pelo navegador sem instalar nada, o cliente MQTT online deste site faz o mesmo básico de pub/sub sobre WebSocket.

O app desktop: conexões iguais às de produção

Clique em New Connection e preencha os campos exatamente como seus dispositivos vão usá-los — um teste diferente da produção não prova nada.

Em Advanced você encontra keep-alive, timeout de conexão, reconexão automática e, para MQTT 5, as propriedades do CONNECT: session expiry interval, receive maximum, maximum packet size, topic alias maximum e user properties. A seção Last Will configura topic, payload, QoS, flag retain e will delay interval — útil para testar a entrega do Last Will.

Se uma conexão falhar, o erro aparece no log da conexão. Brokers MQTT 5 retornam um reason code; cole-o na consulta de reason codes para ver o que ele significa.

Assinar e publicar

Use New Subscription com um filtro de topic como testmqtt/mqttx/#. Cada assinatura recebe uma cor, e as mensagens recebidas ganham a cor da assinatura que deu match — o jeito mais rápido de enxergar wildcards sobrepostos. Não tem certeza se um filtro dá match? Teste no topic matcher.

Na parte de baixo da janela fica a caixa de publicação: topic, QoS, flag retain e payload. O seletor de tipo de payload (Plaintext, JSON, Base64, Hex e outros, dependendo da versão) controla tanto como você digita a mensagem enviada quanto como os payloads recebidos são decodificados. O modo JSON valida e formata, o que pega telemetria quebrada na hora.

Para MQTT 5, clique no ícone de propriedades ao lado da caixa de publicação para definir:

• Content type e payload format indicator
• Message expiry interval
• Topic alias
• Response topic e correlation data para request/response
• User properties como pares chave/valor

As mensagens recebidas mostram suas propriedades no balão da mensagem, então você consegue confirmar que o broker as repassou. Isso torna o MQTTX um ótimo complemento manual para os testes de recursos do MQTT 5.

Scripts e mensagens agendadas

O recurso Script permite escrever uma pequena função JavaScript que transforma um payload antes de ser publicado ou depois de ser recebido. O exemplo clássico simula um sensor:

/**
 * Substitui temperatura e umidade por valores aleatórios a cada publicação.
 * @param value o payload digitado na caixa de publicação, 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);

Salve o script, aplique-o à conexão (mensagens publicadas, recebidas ou ambas) e combine com Timed Message para publicar a cada poucos segundos. Pronto: você tem um dispositivo falso sem escrever um cliente completo. A API de scripts mudou entre versões, então confira os exemplos embutidos da sua versão se execute não for reconhecido.

A CLI mqttx

É na CLI que o MQTTX brilha para testes repetíveis. Quatro subcomandos cobrem quase tudo: conn, sub, pub e 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 imprime o topic ao lado de cada payload, essencial com wildcards. Outras opções que você vai usar:

Esta é a mesma publicação sobre WebSocket seguro, que é o que um app de navegador usaria:

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'

Rode mqttx pub --help para ver a lista completa; de vez em quando flags são adicionadas ou renomeadas entre versões.

Dispositivos simulados

mqttx simulate publica dados realistas a partir de cenários embutidos ou de um arquivo de script seu. Liste os cenários disponíveis na sua versão com mqttx ls --scenarios e rode um:

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

%c é expandido para o client ID, então cada dispositivo simulado ganha seu próprio topic. Assine testmqtt/mqttx/sim/# em outro terminal para acompanhar o fluxo.

Teste de carga com mqttx bench

mqttx bench executa benchmarks de conexão, publicação e assinatura a partir de um único processo:

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 é o índice do cliente, então o publisher 7 conversa com o assinante 7. A saída mostra os clientes conectados e a taxa de mensagens por segundo; quando a taxa recebida no terminal 1 fica abaixo da taxa enviada no terminal 2, algo entre os clientes e o broker está saturado. Para interpretar esses números, e para ferramentas mais pesadas, veja teste de carga de brokers MQTT.

Desktop ou CLI?

• Desktop quando você explora: comparar formatos de payload, acompanhar várias assinaturas, mexer em propriedades do MQTT 5 manualmente.
• CLI quando você repete: scripts de shell, pipelines de CI, servidores acessados via SSH e tudo o que você quer colar num relatório de bug.
• Nenhum dos dois quando você precisa de asserções. O MQTTX mostra mensagens; ele não quebra um build. Para checagens automáticas, envolva o mqttx em um script que verifica a saída, ou escreva testes com uma biblioteca cliente — veja testes MQTT no GitHub Actions.

Se quiser comparar o MQTTX com o MQTT Explorer, a CLI da HiveMQ e outras ferramentas, veja a comparação de clientes MQTT desktop.

Veja suas mensagens do MQTTX no navegador

O MQTTX cobre o ciclo inteiro, de clicar pela interface até benchmarks automatizados, com uma só ferramenta e um só conjunto de configurações de conexão. Salve uma conexão por ambiente, mantenha seus comandos da CLI no repositório ao lado do firmware e você vai conseguir reproduzir qualquer problema do broker em um minuto.

Perguntas frequentes