{"id":18974889,"url":"https://github.com/mqtt-tools/pytest-mqtt","last_synced_at":"2026-01-28T03:30:30.602Z","repository":{"id":162985516,"uuid":"538919947","full_name":"mqtt-tools/pytest-mqtt","owner":"mqtt-tools","description":"pytest-mqtt supports testing systems based on MQTT.","archived":false,"fork":false,"pushed_at":"2025-12-24T22:47:23.000Z","size":70,"stargazers_count":17,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-12-26T12:25:54.219Z","etag":null,"topics":["mosquitto","mosquitto-broker","mosquitto-clients","mqtt","mqtt-broker","mqtt-client","mqtt-library","mqtt-test","mqtt-testing","mqtt-tool","pytest","pytest-mqtt","pytest-plugin","python-qa","python-testing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mqtt-tools.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-09-20T10:00:25.000Z","updated_at":"2025-12-24T22:47:25.000Z","dependencies_parsed_at":"2026-01-06T19:03:20.520Z","dependency_job_id":null,"html_url":"https://github.com/mqtt-tools/pytest-mqtt","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/mqtt-tools/pytest-mqtt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mqtt-tools%2Fpytest-mqtt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mqtt-tools%2Fpytest-mqtt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mqtt-tools%2Fpytest-mqtt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mqtt-tools%2Fpytest-mqtt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mqtt-tools","download_url":"https://codeload.github.com/mqtt-tools/pytest-mqtt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mqtt-tools%2Fpytest-mqtt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28836690,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T02:10:51.810Z","status":"ssl_error","status_checked_at":"2026-01-28T02:10:50.806Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mosquitto","mosquitto-broker","mosquitto-clients","mqtt","mqtt-broker","mqtt-client","mqtt-library","mqtt-test","mqtt-testing","mqtt-tool","pytest","pytest-mqtt","pytest-plugin","python-qa","python-testing"],"created_at":"2024-11-08T15:16:36.759Z","updated_at":"2026-01-28T03:30:30.597Z","avatar_url":"https://github.com/mqtt-tools.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"###########\npytest-mqtt\n###########\n\n|\n\n.. start-badges\n\n|status| |license| |pypi-downloads| |pypi-version|\n\n|ci-tests| |ci-coverage| |python-versions|\n\n.. |ci-tests| 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.. |ci-coverage| 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: Code coverage\n\n.. |pypi-downloads| image:: https://pepy.tech/badge/pytest-mqtt/month\n    :target: https://pepy.tech/project/pytest-mqtt\n    :alt: PyPI downloads per month\n\n.. |pypi-version| 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.. |status| 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.. |python-versions| 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.. |license| image:: https://img.shields.io/badge/license-MIT-green.svg\n    :target: https://github.com/mqtt-tools/pytest-mqtt/blob/main/LICENSE\n    :alt: Project license\n\n.. end-badges\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\nMQTT server host and port are configurable via pytest cli arguments:\n``--mqtt-host`` and ``--mqtt-port``. Default values are ``localhost``/``1883``.\n\nYou may additionally specify a username and password for connecting to the broker with:\n``--mqtt-username`` and ``--mqtt-password``. Default values are ``guest``/``guest``.\n\nBy default, the test fixture subscribes to all topics, listening on ``#``. This can be\ndisabled with the ``--no-subscribe-all`` option. You can then subscribe to the topics\nyou are interested in within each test using ``capmqtt.mqtt_client.client.subscribe(cpe.info)``.\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    import pytest\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- 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 \u003chttps://github.com/mqtt-tools/pytest-mqtt\u003e`_\n- `Documentation \u003chttps://github.com/mqtt-tools/pytest-mqtt\u003e`_\n- `Python Package Index (PyPI) \u003chttps://pypi.org/project/pytest-mqtt/\u003e`_\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/mqtt-tools/mqttwarn\n.. _Paho MQTT Python Client: https://github.com/eclipse/paho.mqtt.python\n.. _terkin-datalogger: https://github.com/hiveeyes/terkin-datalogger/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmqtt-tools%2Fpytest-mqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmqtt-tools%2Fpytest-mqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmqtt-tools%2Fpytest-mqtt/lists"}