MQTT

Publish messages to MQTT topics, and check the messages your services publish there, over MQTT 5 (Mosquitto, EMQX, HiveMQ, RabbitMQ’s MQTT plugin).

Register the broker once, usually in the Background; every MQTT step of the scenario uses it:

Given the depots mqtt broker with the following properties:
  | url      | mqtt://localhost:1883    |
  | username | depot-scanners           |
  | password | ${env:MQTT_PASSWORD}     |

Steps name a topic: the depots/LEJ/scans mqtt topic. Messages carry user properties (property <name> rows), and are published at QoS 1, not retained, unless the qos and retain rows say otherwise.

• A check subscribes for the run: for the topics a run checks, Axx subscribes once the services are up, with a connection of its own. A topic in a check can be a filter with + and #: the depots/+/alerts mqtt topic, and a topic row checks the topic a message came on.
• A check only looks at the messages received since its scenario started, so scenarios running in parallel check their own messages, by data unique to them.
• Retained messages from before never count: Axx subscribes without the messages the broker keeps for new subscribers, which earlier runs may have left.
• Secrets stay secret: ${env:..} values in the properties are masked in logs and failures.

Add it to a project with axx pack add mqtt.

Steps

mqtt.broker

Given the {word} mqtt broker with the following properties:
  | property | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Register the MQTT broker the steps talk to.

• The first broker registered is the one the scenario’s MQTT steps use.
• Values expand ${env:..} and ${sys:..}; ${env:..} values are masked.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Property	Takes	Default
url	the broker’s URL: mqtt://host:1883, mqtts:// for TLS, or ws:// and wss:// for MQTT over WebSockets
username	the user Axx connects as
password	its password, like ${env:MQTT_PASSWORD}
client id	the start of the client IDs Axx connects with, one per connection	axx-<run>
asyncapi	an AsyncAPI document, a file of the project or a URL, that the topics follow: every message a scenario sends there, and every message a check finds, is checked against it (with the asyncapi pack)

Example:

Given the depots mqtt broker with the following properties:
  | url | mqtt://localhost:1883 |
Given the depots mqtt broker with the following properties:
  | url      | mqtts://mqtt.parcels.example:8883 |
  | username | depot-scanners                   |
  | password | ${env:MQTT_PASSWORD}             |

Since 0.1.5.

mqtt.send

When a message is published to the {word} mqtt topic:
  """
  ...
  """

Send a message to the mqtt topic; the doc string is its body.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

When a message is published to the depots/LEJ/scans mqtt topic:
  """
  {"scanId": "SC-8201-1", "parcelRef": "PX-8201", "status": "OUT_FOR_DELIVERY", "location": "Leipzig"}
  """

Since 0.1.5.

mqtt.send.file

When the {filepath} message is published to the {word} mqtt topic[[ with the following properties:]]

Send a message whose body is the file to the mqtt topic, with the properties of the table when the step has one.

Parameter	Takes	For example
{filepath}	a file of the project: a path relative to the feature file’s directory, the resources directories or axx.yaml’s directory (looked for in that order), or an absolute path, quoted when it has a space	seeds/parcels.yaml, kafka/scan-delivered.json
{word}	one word, with no spaces	parcels, PX-4101

Name	Takes	Values	Default
qos	the quality of service it is published at	0, 1, 2	1
retain	whether the broker keeps it for new subscribers	true, false	false
property <name>	a user property sent with the message: its name after property , and its value
content type	the body’s media type
response topic	the topic a reply goes to
correlation data	what ties a reply to its request, as text

Variants, the parts in [[...]] said or left out:

• the {filepath} message is published to the {word} mqtt topic
• the {filepath} message is published to the {word} mqtt topic with the following properties:

Example:

When the mqtt/scan-unknown.json message is published to the depots/LEJ/scans mqtt topic
When the mqtt/scan-unknown.json message is published to the depots/LEJ/scans mqtt topic with the following properties:
  | property scanner | LEJ-HANDHELD-7 |
  | qos              | 1              |

Since 0.1.5.

mqtt.received

Then [[within {duration} ]]the {word} mqtt topic has a message where:
  | path | value |

The table may start with the row naming its columns, as above, or go straight to its rows.

Check that the mqtt topic has a message with those values, received since the scenario started.

• The check waits for it: 10 seconds, or within {duration}.
• Axx subscribes to a topic it checks for the run, without the retained messages earlier runs left.

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101

Each row is a path into the message’s JSON body (a field name, a dotted path or a JSONPath) and the value it has, compared as text: null for null and undefined for absent. A row property <name> is instead on the property of that name sent with the message: undefined when there is none. Rows topic, content type, response topic and correlation data are on the message itself, not its body.

Variants, the parts in [[...]] said or left out:

• the {word} mqtt topic has a message where:
• within {duration} the {word} mqtt topic has a message where:

Example:

Then within 30s the depots/+/alerts mqtt topic has a message where:
  | topic            | depots/LEJ/alerts |
  | parcelRef        | PX-8299           |
  | property scanner | LEJ-HANDHELD-7    |

Since 0.1.5.