https://github.com/mqtt-tools/pytest-mqtt

pytest-mqtt supports testing systems based on MQTT.
https://github.com/mqtt-tools/pytest-mqtt

mosquitto mqtt mqtt-broker mqtt-client mqtt-test mqtt-testing pytest pytest-plugin python-qa python-testing

Last synced: about 1 month ago
JSON representation

pytest-mqtt supports testing systems based on MQTT.

• Host: GitHub
• URL: https://github.com/mqtt-tools/pytest-mqtt
• Owner: mqtt-tools
• License: mit
• Created: 2022-09-20T10:00:25.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2024-10-28T11:06:22.000Z (about 2 months ago)
• Last Synced: 2024-10-28T14:28:05.853Z (about 2 months ago)
• Topics: mosquitto, mqtt, mqtt-broker, mqtt-client, mqtt-test, mqtt-testing, pytest, pytest-plugin, python-qa, python-testing
• Language: Python
• Homepage:
• Size: 54.7 KB
• Stars: 9
• Watchers: 1
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGES.rst
  • License: LICENSE

Awesome Lists containing this project

README

        
###########

pytest-mqtt

###########

|

.. start-badges

|ci-tests| |ci-coverage| |license| |pypi-downloads|

|python-versions| |status| |pypi-version|

.. |ci-tests| image:: https://github.com/mqtt-tools/pytest-mqtt/actions/workflows/tests.yml/badge.svg

    :target: https://github.com/mqtt-tools/pytest-mqtt/actions/workflows/tests.yml

    :alt: CI outcome

.. |ci-coverage| image:: https://codecov.io/gh/mqtt-tools/pytest-mqtt/branch/main/graph/badge.svg

    :target: https://codecov.io/gh/mqtt-tools/pytest-mqtt

    :alt: Test suite code coverage

.. |pypi-downloads| image:: https://pepy.tech/badge/pytest-mqtt/month

    :target: https://pepy.tech/project/pytest-mqtt

    :alt: PyPI downloads per month

.. |pypi-version| image:: https://img.shields.io/pypi/v/pytest-mqtt.svg

    :target: https://pypi.org/project/pytest-mqtt/

    :alt: Package version on PyPI

.. |status| image:: https://img.shields.io/pypi/status/pytest-mqtt.svg

    :target: https://pypi.org/project/pytest-mqtt/

    :alt: Project status (alpha, beta, stable)

.. |python-versions| image:: https://img.shields.io/pypi/pyversions/pytest-mqtt.svg

    :target: https://pypi.org/project/pytest-mqtt/

    :alt: Supported Python versions

.. |license| image:: https://img.shields.io/pypi/l/pytest-mqtt.svg

    :target: https://github.com/mqtt-tools/pytest-mqtt/blob/main/LICENSE

    :alt: Project license

.. end-badges

*****

About

*****

``pytest-mqtt`` supports testing systems based on MQTT by providing test

fixtures for ``pytest``. It has been conceived for the fine

`terkin-datalogger`_ and `mqttwarn`_ programs.

``capmqtt`` fixture

===================

Capture MQTT messages, using the `Paho MQTT Python Client`_, in the spirit of

``caplog`` and ``capsys``. It can also be used to publish MQTT messages.

MQTT server host and port are configurable via pytest cli arguments:

``--mqtt-host`` and ``--mqtt-port``. Default values are ``localhost``/``1883``.

``mosquitto`` fixture

=====================

Provide the `Mosquitto`_ MQTT broker as a session-scoped fixture to your test

cases.

*****

Usage

*****

::

    import pytest

    from pytest_mqtt.model import MqttMessage

    @pytest.mark.capmqtt_decode_utf8

    def test_mqtt_send_receive(mosquitto, capmqtt):

        """

        Basic send/receive roundtrip, using text payload (`str`).

        By using the `capmqtt_decode_utf8` marker, the message payloads

        will be recorded as `str`, after decoding them from `utf-8`.

        Otherwise, message payloads would be recorded as `bytes`.

        """

        # Submit a basic MQTT message.

        capmqtt.publish(topic="foo", payload="bar")

        # Demonstrate the "messages" property.

        # It returns a list of "MqttMessage" objects.

        assert capmqtt.messages == [

            MqttMessage(topic="foo", payload="bar", userdata=None),

        ]

        # Demonstrate the "records" property.

        # It returns tuples of "(topic, payload, userdata)".

        assert capmqtt.records == [

            ("foo", "bar", None),

        ]

The ``capmqtt_decode_utf8`` setting can be enabled in three ways.

1. Session-wide, per ``pytestconfig`` option, for example within ``conftest.py``::

      @pytest.fixture(scope="session", autouse=True)

      def configure_capmqtt_decode_utf8(pytestconfig):

          pytestconfig.option.capmqtt_decode_utf8 = True

2. On the module level, just say ``capmqtt_decode_utf8 = True`` on top of your file.

3. On individual test cases as a test case marker, using ``@pytest.mark.capmqtt_decode_utf8``.

******

Issues

******

- The ``mosquitto`` fixture currently does not support either authentication or

  encryption.

- ``capmqtt`` should be able to capture messages only from specified topics.

***********

Development

***********

::

    git clone https://github.com/mqtt-tools/pytest-mqtt

    cd pytest-mqtt

    python3 -m venv .venv

    source .venv/bin/activate

    pip install --editable=.[test,develop]

    poe test

*******************

Project information

*******************

Contributions

=============

Every kind of contribution, feedback, or patch, is much welcome. `Create an

issue`_ or submit a patch if you think we should include a new feature, or to

report or fix a bug.

Resources

=========

- `Source code `_

- `Documentation `_

- `Python Package Index (PyPI) `_

License

=======

The project is licensed under the terms of the MIT license, see `LICENSE`_.

.. _Create an issue: https://github.com/mqtt-tools/pytest-mqtt/issues/new

.. _LICENSE: https://github.com/mqtt-tools/pytest-mqtt/blob/main/LICENSE

.. _Mosquitto: https://github.com/eclipse/mosquitto

.. _mqttwarn: https://github.com/jpmens/mqttwarn/

.. _Paho MQTT Python Client: https://github.com/eclipse/paho.mqtt.python

.. _terkin-datalogger: https://github.com/hiveeyes/terkin-datalogger/