MQTTLibrary for Robot Framework

MQTTLibrary is a Robot Framework library that provides keywords for testing on MQTT brokers. MQTT is a lightweight protocol for machine-to-machine communication, typically used for IoT messaging. This library uses the paho client library published by eclipse project.

Installation

MQTTLibrary can be installed using pip:

pip install robotframework-mqttlibrary

To try the 1.0 release candidate, ask for it by version, so that pip does not also pick pre-releases of the dependencies:

pip install robotframework-mqttlibrary==1.0.0rc1

Supported versions:

MQTTLibrary	Python	Robot Framework	paho-mqtt
1.0	3.9 - 3.14	4.1 and later	2.1 - 2.x
0.7.2	3	not pinned	1.3 - 1.x

1.0 is tested with Robot Framework 4.1.3 and the latest 7.x.

1.0 changes some keyword behaviour. See "Migrating from 0.7" in the changelog before upgrading.

To install from a clone of this repository, run this in its root directory:

pip install .

Usage

Import the library:

*** Settings ***
Library          MQTTLibrary

Connect to the broker, publish and disconnect:

*** Test Cases ***
Publish
    Connect     127.0.0.1
    Publish     topic=test/mqtt_test    message=test message
    [Teardown]  Disconnect

Connect to the broker, subscribe and validate that a message is received:

*** Test Cases ***
Subscribe and Validate
    Connect                 127.0.0.1
    Subscribe and Validate  topic=test/mqtt_test    qos=1   payload=test
    [Teardown]              Disconnect

Use named connections to subscribe and publish in one test. Messages are queued from the moment of Subscribe, and Listen returns the oldest first:

*** Test Cases ***
Publish and Listen
    Connect         127.0.0.1    alias=sub
    Subscribe       test/mqtt_test    qos=1    timeout=0    alias=sub
    Connect         127.0.0.1    alias=pub
    Publish         test/mqtt_test    hello    qos=1    alias=pub
    @{messages}=    Listen    test/mqtt_test    timeout=5s    alias=sub
    Should Be Equal    ${messages}[0]    hello
    [Teardown]      Disconnect All

Keyword documentation is available at https://randomsync.github.io/robotframework-mqttlibrary/. For 0.7.2, the last release for paho-mqtt 1, see https://randomsync.github.io/robotframework-mqttlibrary/0.7/.

Also look at the tests/acceptance folder for examples.

For general information about using test libraries with Robot Framework, see Robot Framework User Guide.

Contributing

The keywords in this library are based on some of the methods available in eclipse paho client library. If you'd like to add keywords, see instructions on creating/updating libraries for Robot Framework.

You need Python 3.9 or later and Docker Engine 25 or later. The Makefile runs the same steps as CI; the first target that needs Python creates venv with the package installed in editable mode:

make brokers    # start the test brokers from docker-compose.yml
make test       # unit and acceptance tests under coverage
make clean      # stop the brokers and remove test output

Other targets:

• make test-unit runs the unit tests in tests/unit. They use pytest and a fake paho client, so they need no broker.
• make test-acc runs the Robot Framework acceptance tests in tests/acceptance against the brokers: one without authentication, used by most tests, and one that requires a username and password.
• make lint runs ruff, builds the keyword documentation and dry-runs the acceptance suites.
• make docs regenerates docs/index.html.

CI requires at least 90% combined coverage (see [tool.coverage] in pyproject.toml).

The acceptance tests read the broker addresses from environment variables, so they can run against other brokers: MQTT_HOST (default 127.0.0.1), MQTT_PORT (1883) and MQTT_AUTH_PORT (11883). For example:

MQTT_HOST=192.168.1.10 make test-acc

The test credentials live in mosquitto/passwd_file. To regenerate it, run scripts/gen-passwd.sh.

License

MQTTLibrary is open source software provided under the Apache License 2.0.