Metadata-Version: 2.1
Name: pytest-mqtt
Version: 0.4.2
Summary: pytest-mqtt supports testing systems based on MQTT
Author-email: Andreas Motl <andreas.motl@panodata.org>, Richard Pobering <richard.pobering@panodata.org>
License: MIT
Project-URL: homepage, https://github.com/mqtt-tools/pytest-mqtt
Project-URL: documentation, https://github.com/mqtt-tools/pytest-mqtt
Project-URL: repository, https://github.com/mqtt-tools/pytest-mqtt
Project-URL: changelog, https://github.com/mqtt-tools/pytest-mqtt/blob/main/CHANGES.rst
Keywords: mqtt,pytest,testing,mosquitto,paho
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Customer Service
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Legal Industry
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Communications
Classifier: Topic :: Education
Classifier: Topic :: Home Automation
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Object Brokering
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: dataclasses; python_version < "3.7"
Requires-Dist: importlib-metadata; python_version < "3.8"
Requires-Dist: paho-mqtt<3
Requires-Dist: pytest-docker-fixtures<2
Provides-Extra: test
Requires-Dist: coverage<8; extra == "test"
Requires-Dist: pytest<9; extra == "test"
Requires-Dist: pytest-fixture-order<1; extra == "test"
Requires-Dist: pytest-ordering<1; extra == "test"
Provides-Extra: develop
Requires-Dist: isort<6; extra == "develop"
Requires-Dist: black<25; extra == "develop"
Requires-Dist: poethepoet<1; extra == "develop"
Requires-Dist: ruff<0.6; extra == "develop"
Provides-Extra: release
Requires-Dist: build<2; extra == "release"
Requires-Dist: twine<6; extra == "release"

###########
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 <https://github.com/mqtt-tools/pytest-mqtt>`_
- `Documentation <https://github.com/mqtt-tools/pytest-mqtt>`_
- `Python Package Index (PyPI) <https://pypi.org/project/pytest-mqtt/>`_

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/
