Testing
MQTT Broker Testing Checklist: Connection, Publish, Subscribe, and Filters
A step-by-step MQTT broker testing checklist for developers validating connectivity, permissions, subscriptions, retained messages, QoS, and mobile behavior.
Who this guide is for
Developers, QA engineers, IoT teams, Home Assistant users, and support engineers validating broker behavior.
Problems this guide helps solve
- Connection failures can come from DNS, ports, TLS, credentials, ACLs, or client IDs.
- Topic names are case sensitive and easy to mistype.
- Overlapping subscriptions and retained messages can produce misleading results.
- Testing only through the final app makes broker problems harder to isolate.
Start by isolating the broker
When MQTT behavior fails, the first question is not whether the application is wrong. The first question is whether a known client can connect to the broker under the same network and authentication conditions. This separates broker, network, and permission problems from firmware or app bugs.
Public broker tools and vendor consoles often demonstrate the same basic flow: connect first, then subscribe, then publish, then confirm messages arrive. AWS IoT and HiveMQ documentation both frame broker validation around viewing subscribed messages and publishing test messages, which matches the practical debugging loop.
- Confirm host, port, and protocol before testing application logic.
- Validate username/password or certificate requirements.
- Check TLS and WebSocket assumptions explicitly.
- Use a unique client ID when testing persistent session behavior.
- Record the exact broker environment: local, cloud, VPN, lab Wi-Fi, or field network.
Subscribe before you publish
A reliable MQTT publish/subscribe test starts with observation. Subscribe to the expected topic or a narrow wildcard filter first. Then publish a controlled message and check whether it arrives with the expected timing and metadata.
If the message does not arrive, widen the filter carefully. A temporary wildcard can reveal whether the device is publishing under a different path, but broad filters should not become permanent debugging habits on sensitive systems.
- Use the exact expected topic first.
- If needed, widen to a parent filter such as a device or product prefix.
- Check case sensitivity and separators.
- Avoid publishing sensitive payloads to public or shared brokers.
- Do not use production secrets in screenshots, logs, or external analytics.
Check retained messages, QoS, and ACL behavior
Retained messages can make a system look alive when the current device is not publishing. QoS settings can also create different delivery expectations than the application assumes. Broker access-control rules may allow subscription but block publishing, or allow one topic branch but not another.
Test each behavior separately. Publish with a known retain setting. Subscribe with a fresh session. Try read-only and write-only paths if your broker supports them. The goal is to remove hidden state from the debugging process.
Repeat from the real device context
A broker test from a desktop does not always prove that the phone, tablet, field network, or installed device can reach the same endpoint. Mobile testing is valuable because it catches VPN, Wi-Fi, captive portal, DNS, and firewall differences earlier.
AirMQTT is useful here because the same MQTT workflow can run on Mac, iPhone, and iPad. That makes it easier to validate broker behavior where the issue actually happens.
FAQ
How do I test if an MQTT broker is working?
Connect with a known MQTT client, subscribe to a test topic, publish a controlled message, and verify that the subscribed client receives it. Then repeat with the same security and network conditions used by the real device.
Why can I connect to MQTT but not receive messages?
Common causes include topic typos, case differences, ACL restrictions, retained-message confusion, session settings, and subscribing to a different topic filter than the device publishes to.