Metadata-Version: 2.5
Name: robotframework-mqttlibrary
Version: 1.1.0
Summary: MQTT keyword library for Robot Framework
Project-URL: Homepage, https://github.com/randomsync/robotframework-mqttlibrary
Project-URL: Documentation, https://randomsync.github.io/robotframework-mqttlibrary/
Project-URL: Issues, https://github.com/randomsync/robotframework-mqttlibrary/issues
Project-URL: Changelog, https://github.com/randomsync/robotframework-mqttlibrary/blob/master/CHANGELOG.md
Author-email: Gaurav Gupta <gaurav@randomsync.net>
License-Expression: Apache-2.0
License-File: LICENSE.txt
Keywords: mqtt,robotframework,testautomation,testing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Library
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Requires-Dist: paho-mqtt<3,>=2.1
Requires-Dist: robotframework>=4.1
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff==0.16.9; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: robotframework==7.5; extra == 'docs'
Description-Content-Type: text/x-rst

MQTTLibrary for Robot Framework
===============================

.. image:: https://github.com/randomsync/robotframework-mqttlibrary/actions/workflows/ci.yml/badge.svg?branch=master&event=push
    :target: https://github.com/randomsync/robotframework-mqttlibrary/actions/workflows/ci.yml
    :alt: CI

.. image:: https://badge.fury.io/py/robotframework-mqttlibrary.svg
    :target: https://badge.fury.io/py/robotframework-mqttlibrary

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.

.. _Robot Framework: http://robotframework.org
.. _MQTT: http://mqtt.org/
.. _paho: https://eclipse.org/paho/

Features
--------

==================  ===========================================================  =====
Feature             Keywords and arguments                                       Since
==================  ===========================================================  =====
Publish, subscribe  ``Publish``, ``Subscribe``, ``Listen``, ``Unsubscribe``,     0.x
                    ``Publish Single``, ``Publish Multiple``
Named connections   ``alias=``, ``Switch Connection``, ``Disconnect All``        1.0
Message queues      messages kept from ``Connect`` until read, ``limit=``        1.0
TLS                 ``Connect`` with ``ca_certs=``, ``certfile=``, ``keyfile=``  1.1
                    and more; mutual TLS
Websockets          ``Connect`` with ``transport=websockets``                    1.1
MQTT 5              ``Connect`` with ``protocol=MQTTv5``, ``clean_start=``,      1.1
                    ``session_expiry=``
Credentials, will   ``Connect`` with ``username=``, ``password=``;               1.1
                    ``Set Last Will``
Reconnecting        ``Connect`` with ``reconnect_on_failure=``                   1.1
Message objects     ``Get Messages`` (topic, payload, qos, retain, properties,   1.1
                    timestamp), ``Clear Messages``
Binary payloads     ``decode=${False}`` on ``Subscribe``, ``Listen``,            1.1
                    ``Get Messages``
Assertions          ``Wait Until Message Received``,                             1.1
                    ``Message Count Should Be``, ``Payload Should Match``,
                    ``Should Be Connected``, ``Should Not Be Connected``
==================  ===========================================================  =====

Installation
------------

MQTTLibrary can be installed using `pip <https://pip.pypa.io>`__::

    pip install robotframework-mqttlibrary

To stay on 0.7.2, the last release for paho-mqtt 1, pin it::

    pip install "robotframework-mqttlibrary~=0.7"

Supported versions:

=============  ==========  ===============  ============
MQTTLibrary    Python      Robot Framework  paho-mqtt
=============  ==========  ===============  ============
1.1            3.9 - 3.14  4.1 and later    2.1 - 2.x
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.1 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 <https://github.com/randomsync/robotframework-mqttlibrary/blob/master/CHANGELOG.md>`__ before upgrading.

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

    pip install .

Usage
-------

Import the library:

.. code-block:: robotframework

    *** Settings ***
    Library          MQTTLibrary

Connect to the broker, publish and disconnect:

.. code-block:: robotframework

    *** 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:

.. code-block:: robotframework

    *** 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:

.. code-block:: robotframework

    *** 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

Connect with TLS and wait for a message on a wildcard subscription. ``Wait Until Message Received`` returns the message, with its topic:

.. code-block:: robotframework

    *** Test Cases ***
    Wait For A Status
        Connect         broker.example.com    8883    ca_certs=${CURDIR}/ca.crt
        ...             username=robot    password=secret
        Subscribe       devices/+/status    qos=1    timeout=0
        ${message}=     Wait Until Message Received    devices/+/status    ^online$
        Should Be Equal    ${message.topic}    devices/robot/status
        [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`__.

__ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#using-test-libraries

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, one that requires a username and password (over TCP and websockets), and one with server and mutual TLS.
- ``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``), ``MQTT_AUTH_PORT`` (``11883``), ``MQTT_WS_PORT`` (``9001``), ``MQTT_TLS_PORT`` (``8883``), ``MQTT_MTLS_PORT`` (``8884``) and ``MQTT_CERTS`` (``mosquitto/certs``). 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``. ``make brokers`` creates the TLS test certificates in ``mosquitto/certs`` with ``scripts/gen-certs.sh`` (it needs ``openssl``); run ``scripts/gen-certs.sh --force`` to recreate them.

.. _instructions: http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#creating-test-libraries

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

__ http://apache.org/licenses/LICENSE-2.0