pytest-mqtt


Namepytest-mqtt JSON
Version 0.3.1 PyPI version JSON
download
home_page
Summarypytest-mqtt supports testing systems based on MQTT
upload_time2023-08-03 17:41:54
maintainer
docs_urlNone
author
requires_python>=3.6
licenseMIT
keywords mqtt pytest testing mosquitto paho
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            .. 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

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

.. image:: https://pepy.tech/badge/pytest-mqtt/month
    :target: https://pepy.tech/project/pytest-mqtt
    :alt: PyPI downloads per month

.. image:: https://img.shields.io/pypi/v/pytest-mqtt.svg
    :target: https://pypi.org/project/pytest-mqtt/
    :alt: Package version on PyPI

.. image:: https://img.shields.io/pypi/status/pytest-mqtt.svg
    :target: https://pypi.org/project/pytest-mqtt/
    :alt: Project status (alpha, beta, stable)

.. image:: https://img.shields.io/pypi/pyversions/pytest-mqtt.svg
    :target: https://pypi.org/project/pytest-mqtt/
    :alt: Supported Python versions

.. image:: https://img.shields.io/pypi/l/pytest-mqtt.svg
    :target: https://github.com/mqtt-tools/pytest-mqtt/blob/main/LICENSE
    :alt: Project license

|

###########
pytest-mqtt
###########


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

``mosquitto`` fixture
=====================

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


*****
Usage
*****

::

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

- Both fixtures currently do not support changing the MQTT broker hostname and
  port number differently than ``localhost:1883``.

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

            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "pytest-mqtt",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "",
    "keywords": "mqtt,pytest,testing,mosquitto,paho",
    "author": "",
    "author_email": "Andreas Motl <andreas.motl@panodata.org>, Richard Pobering <richard.pobering@panodata.org>",
    "download_url": "https://files.pythonhosted.org/packages/a6/7e/07d02001bbaf8380c65c5c5a424752b8efdb408dac0530baf371bfbdef54/pytest-mqtt-0.3.1.tar.gz",
    "platform": null,
    "description": ".. image:: https://github.com/mqtt-tools/pytest-mqtt/actions/workflows/tests.yml/badge.svg\n    :target: https://github.com/mqtt-tools/pytest-mqtt/actions/workflows/tests.yml\n    :alt: CI outcome\n\n.. image:: https://codecov.io/gh/mqtt-tools/pytest-mqtt/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/mqtt-tools/pytest-mqtt\n    :alt: Test suite code coverage\n\n.. image:: https://pepy.tech/badge/pytest-mqtt/month\n    :target: https://pepy.tech/project/pytest-mqtt\n    :alt: PyPI downloads per month\n\n.. image:: https://img.shields.io/pypi/v/pytest-mqtt.svg\n    :target: https://pypi.org/project/pytest-mqtt/\n    :alt: Package version on PyPI\n\n.. image:: https://img.shields.io/pypi/status/pytest-mqtt.svg\n    :target: https://pypi.org/project/pytest-mqtt/\n    :alt: Project status (alpha, beta, stable)\n\n.. image:: https://img.shields.io/pypi/pyversions/pytest-mqtt.svg\n    :target: https://pypi.org/project/pytest-mqtt/\n    :alt: Supported Python versions\n\n.. image:: https://img.shields.io/pypi/l/pytest-mqtt.svg\n    :target: https://github.com/mqtt-tools/pytest-mqtt/blob/main/LICENSE\n    :alt: Project license\n\n|\n\n###########\npytest-mqtt\n###########\n\n\n*****\nAbout\n*****\n\n``pytest-mqtt`` supports testing systems based on MQTT by providing test\nfixtures for ``pytest``. It has been conceived for the fine\n`terkin-datalogger`_ and `mqttwarn`_ programs.\n\n``capmqtt`` fixture\n===================\n\nCapture MQTT messages, using the `Paho MQTT Python Client`_, in the spirit of\n``caplog`` and ``capsys``. It can also be used to publish MQTT messages.\n\n``mosquitto`` fixture\n=====================\n\nProvide the `Mosquitto`_ MQTT broker as a session-scoped fixture to your test\ncases.\n\n\n*****\nUsage\n*****\n\n::\n\n    from pytest_mqtt.model import MqttMessage\n\n    @pytest.mark.capmqtt_decode_utf8\n    def test_mqtt_send_receive(mosquitto, capmqtt):\n        \"\"\"\n        Basic send/receive roundtrip, using text payload (`str`).\n\n        By using the `capmqtt_decode_utf8` marker, the message payloads\n        will be recorded as `str`, after decoding them from `utf-8`.\n        Otherwise, message payloads would be recorded as `bytes`.\n        \"\"\"\n\n        # Submit a basic MQTT message.\n        capmqtt.publish(topic=\"foo\", payload=\"bar\")\n\n        # Demonstrate the \"messages\" property.\n        # It returns a list of \"MqttMessage\" objects.\n        assert capmqtt.messages == [\n            MqttMessage(topic=\"foo\", payload=\"bar\", userdata=None),\n        ]\n\n        # Demonstrate the \"records\" property.\n        # It returns tuples of \"(topic, payload, userdata)\".\n        assert capmqtt.records == [\n            (\"foo\", \"bar\", None),\n        ]\n\n\nThe ``capmqtt_decode_utf8`` setting can be enabled in three ways.\n\n\n1. Session-wide, per ``pytestconfig`` option, for example within ``conftest.py``::\n\n      @pytest.fixture(scope=\"session\", autouse=True)\n      def configure_capmqtt_decode_utf8(pytestconfig):\n          pytestconfig.option.capmqtt_decode_utf8 = True\n\n2. On the module level, just say ``capmqtt_decode_utf8 = True`` on top of your file.\n3. On individual test cases as a test case marker, using ``@pytest.mark.capmqtt_decode_utf8``.\n\n\n******\nIssues\n******\n\n- Both fixtures currently do not support changing the MQTT broker hostname and\n  port number differently than ``localhost:1883``.\n\n- The ``mosquitto`` fixture currently does not support either authentication or\n  encryption.\n\n- ``capmqtt`` should be able to capture messages only from specified topics.\n\n\n***********\nDevelopment\n***********\n\n::\n\n    git clone https://github.com/mqtt-tools/pytest-mqtt\n    cd pytest-mqtt\n    python3 -m venv .venv\n    source .venv/bin/activate\n    pip install --editable=.[test,develop]\n    poe test\n\n\n*******************\nProject information\n*******************\n\nContributions\n=============\n\nEvery kind of contribution, feedback, or patch, is much welcome. `Create an\nissue`_ or submit a patch if you think we should include a new feature, or to\nreport or fix a bug.\n\nResources\n=========\n\n- `Source code <https://github.com/mqtt-tools/pytest-mqtt>`_\n- `Documentation <https://github.com/mqtt-tools/pytest-mqtt>`_\n- `Python Package Index (PyPI) <https://pypi.org/project/pytest-mqtt/>`_\n\nLicense\n=======\n\nThe project is licensed under the terms of the MIT license, see `LICENSE`_.\n\n\n.. _Create an issue: https://github.com/mqtt-tools/pytest-mqtt/issues/new\n.. _LICENSE: https://github.com/mqtt-tools/pytest-mqtt/blob/main/LICENSE\n.. _Mosquitto: https://github.com/eclipse/mosquitto\n.. _mqttwarn: https://github.com/jpmens/mqttwarn/\n.. _Paho MQTT Python Client: https://github.com/eclipse/paho.mqtt.python\n.. _terkin-datalogger: https://github.com/hiveeyes/terkin-datalogger/\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "pytest-mqtt supports testing systems based on MQTT",
    "version": "0.3.1",
    "project_urls": {
        "changelog": "https://github.com/mqtt-tools/pytest-mqtt/blob/main/CHANGES.rst",
        "documentation": "https://github.com/mqtt-tools/pytest-mqtt",
        "homepage": "https://github.com/mqtt-tools/pytest-mqtt",
        "repository": "https://github.com/mqtt-tools/pytest-mqtt"
    },
    "split_keywords": [
        "mqtt",
        "pytest",
        "testing",
        "mosquitto",
        "paho"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f19f4ce641f5c78990df0e6f117a1691a35e32ff50d0e461f636be844b423ce7",
                "md5": "0080aebf6828086d65d69959e8e5c815",
                "sha256": "0048e63d4a08cfde96212268ae93d2d03ceea96a19b614fa88f5cc4297f496cb"
            },
            "downloads": -1,
            "filename": "pytest_mqtt-0.3.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0080aebf6828086d65d69959e8e5c815",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 8845,
            "upload_time": "2023-08-03T17:41:52",
            "upload_time_iso_8601": "2023-08-03T17:41:52.060531Z",
            "url": "https://files.pythonhosted.org/packages/f1/9f/4ce641f5c78990df0e6f117a1691a35e32ff50d0e461f636be844b423ce7/pytest_mqtt-0.3.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "a67e07d02001bbaf8380c65c5c5a424752b8efdb408dac0530baf371bfbdef54",
                "md5": "5cde1df62ef77139d1380ea7d8292f85",
                "sha256": "25580fea812dcb7b2a13931c9c5ec62e8310e4eba90e830fb92de990a643ec20"
            },
            "downloads": -1,
            "filename": "pytest-mqtt-0.3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "5cde1df62ef77139d1380ea7d8292f85",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 9885,
            "upload_time": "2023-08-03T17:41:54",
            "upload_time_iso_8601": "2023-08-03T17:41:54.021227Z",
            "url": "https://files.pythonhosted.org/packages/a6/7e/07d02001bbaf8380c65c5c5a424752b8efdb408dac0530baf371bfbdef54/pytest-mqtt-0.3.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-08-03 17:41:54",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "mqtt-tools",
    "github_project": "pytest-mqtt",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "pytest-mqtt"
}
        
Elapsed time: 0.09715s