An MQTT automation can look finished before it has processed a single message from a broker. The YAML saves, a manual action produces a notification, and the dashboard looks right. That's useful to know. But none of it proves that the topic, payload filter, template, and action work together when a publisher sends an event.
A small fictional event makes a better first test. Use a topic reserved for testing, data that identifies no real person or device, and a harmless action you can see. The question is narrow: did this automation process this message at this time? A passing test does not prove that a device is present, that a scanner will always find it, or that MQTT will deliver every future message.
These examples use Home Assistant, but the distinction between checking the editor, running an action manually, and testing the event path applies to any MQTT consumer. Use only a broker and automation you administer.
A clear claim before editing
Write down the result you need in one sentence. For example: a JSON message on lab/automation-test/2026-10-31/event whose event type is new_device creates one persistent notification. That statement names a topic, a payload field, a matching value, and an action you can observe. It's much easier to test than a vague claim that MQTT works.
Keep the related claims separate. A successful fictional message proves a path from a known publisher through a broker to one automation. It does not identify a real device, establish an intrusion, or guarantee exactly-once delivery. If you're trying to decide whether a device needs investigation, record independent observations first. How to See Every Device on Your Network and Find Its IP Address explains how to compare an inventory with router information without treating a name as an identity.
Choose a safe first action. Use a persistent notification, logbook entry, or dedicated helper rather than changing a switch, lock, alarm, or network setting. A notification also gives you a timestamp to compare with the automation trace.
A distinct test topic
Create a topic under a prefix you control and include a date or test identifier. For example, use lab/automation-test/2026-10-31/event. It's easy to spot in a broker log and unlikely to collide with a live integration. You can remove it easily later.
Avoid any topic associated with an action that has real consequences. Keep real credentials, private addresses, customer names, and live device identifiers out of the sample. Clearly fictional data makes the test easier to repeat and review.
MQTT matching is exact unless you've explicitly configured wildcards. That final s matters: lab/automation-test/2026-10-31/event and lab/automation-test/2026-10-31/events are different topics. Uppercase and lowercase letters differ too. If a trigger doesn't fire, compare the publisher's topic with the trigger's topic character by character before changing anything else.
An automation with a narrow match
This is a single Home Assistant automation for the YAML editor, not a full configuration.yaml file. It listens to the test-only topic and accepts only a JSON event whose event_type is new_device.
~~~yaml alias: MQTT fictional-event check description: Confirm that one test-only MQTT message reaches this automation. triggers:
- trigger: mqtt topic: lab/automation-test/2026-10-31/event value_template: "{{ (value_json.event_type | default('')) if value_json is defined and value_json is mapping else '' }}" payload: new_device conditions: [] actions:
- action: persistent_notification.create data: notification_id: mqtt_fictional_event_check title: MQTT test received message: >- Received the fictional event for {{ trigger.payload_json.name | default('unnamed example', true) }}. mode: single ~~~
The value template extracts event_type, and the payload condition compares it with new_device. Invalid JSON or a missing field becomes an empty value and does not match. That's intentional: the test should fail clearly, without letting an unrelated message look like a success.
Save the automation and check that it's enabled. To check whether the notification service itself works, call persistent_notification.create separately with a literal message such as "MQTT notification test". Home Assistant's Run actions control supplies no trigger data, so the supplied automation's message template can fail when run manually. Test this automation by publishing MQTT; a successful separate service call is not evidence that a broker message reached the automation.
Publication of one fictional message
Use Home Assistant's MQTT Publish a packet tool or another publisher connected to the same broker. Leave retain off. Publish once to the exact test topic with this payload:
~~~json { "event_type": "new_device", "name": "Tutorial printer", "ip": "192.0.2.42", "note": "fictional test data" } ~~~
The address 192.0.2.42 is documentation space, not a host to contact. Tutorial printer is fictional too. This payload tests the structure the trigger expects; it does not claim to report a live network change.
After publishing, check for the persistent notification, then look for a new automation trace matching the publication time. Record the publication time and topic along with the trace run and action result. A new trace showing the trigger data and notification action result tells you more than an editor screenshot.
If no notification appears, check in this order:
- Confirm that the automation is saved and enabled.
- Compare the publisher and trigger topics exactly.
- Confirm that Home Assistant and the publisher use the intended broker.
- Check that the payload is valid JSON and event_type is exactly new_device.
- Look for a new trace matching the publication time before editing. If none exists, check MQTT reception and filtering; a message that does not trigger the automation produces no new run trace. If one exists, inspect its trigger data and action result.
Change one variable at a time. If you replace the broker, topic, trigger, and payload together, you've created a new test whose result you can't interpret.
A negative check
Publish a second fictional message to the same topic, this time with an event type that should not match:
~~~json {"event_type":"device_offline","name":"Tutorial printer","note":"fictional negative test"} ~~~
The automation should not run. Without this check, the first notification might only tell you that the subscription is broad. That first result alone doesn't establish that the filter rejects unrelated events.
Avoid retained messages for this event test. A broker may send a retained message to a subscriber that connects later. That's useful for current state, but misleading if you're checking whether an event happened after the receiver was ready. If the test topic already has retained state, isolate or clear it using the broker's documented procedure before interpreting the next run.
Restarts as a separate test
Once the positive and negative checks work, a restart can answer a different question: what happens when the receiver is unavailable? Restart the automation or Home Assistant during a safe maintenance window, then inspect the trace timestamps. An old notification may still be visible. That should not turn an earlier non-retained event into a fresh event.
Availability topics need their own test. A configured online or offline value tells you how Home Assistant interpreted a message on that topic, but not why a publisher, service, or device became unavailable. Test availability transitions separately from event handling. Keep a note of whether the message was retained.
The move to a real integration
Wait until the isolated topic works before adapting the automation to a real publisher. Keep the first production action observational. A notification asking someone to compare an inventory is safer than automatic labeling or a network change.
DeviceShelf Server is one possible publisher of local network observations through MQTT discovery. You should still compare its output with router records and known-device information. A message is not proof of device identity, availability, delivery, or an intrusion.
Keep a short test record with the reserved topic, fictional payload, publication time, trace result, and any change you made because of the trace. This gives you a repeatable baseline for later troubleshooting. Remove the test-only automation, helper, and retained test state once they're no longer useful.
A passing test establishes one limited but useful fact: a known broker accepted one fictional message, and this automation processed it as configured. It doesn't measure reliability over time or replace incident review. Keeping that limit clear is the point of the exercise. A calm, repeatable test is much more useful than guessing during a real outage or an unexpected device event.