HiveMQ Testcontainer Released
HiveMQ Testcontainers
Automated integration testing of MQTT applications is a challenging task since it requires you to simulate or set up an MQTT deployment of some kind. When testing MQTT client applications, you need a deployed MQTT broker. Sharing the deployment across multiple tests can be troublesome. Shared deployments can cause unwanted interferences between tests that produce unexpected results and flaky tests. Integration-testing custom HiveMQ extensions can be even more difficult since the extension must be packaged, deployed, and started automatically. While developing extensions such as our Enterprise Security Extension or the HiveMQ Extension for Kafka, we frequently encountered this issue. To eliminate this pain point, we developed the official HiveMQ Testcontaier, whose release we proudly announce today.
The HiveMQ Testcontainer is a Java library that gives you the right tools for automated JUnit 4 and JUnit 5 testing of MQTT client applications and custom HiveMQ extensions. Use the Testcontainer to start up customizable HiveMQ docker containers that are exclusive to each integration test. On top of that, the process of packaging and deploying HiveMQ extensions directly from source can be automated.
See the project on GitHub.
The library is available on Maven Central for JUnit 4 and JUnit 5.
Add to your project
To add the HiveMQ Testcontainer to your project, add these dependencies to your pom.xml
:
Test your MQTT application
Testing your MQTT application can look something like this:
Create a new
HiveMQTestContainerRule
Register the
Rule
with JUnit 4Connect your MQTT clients to the HiveMQ instance that is running inside the container. Use the port that you retrieve from the rule with the
getMqttPort()
method.Assert the expected behavior.
Test your custom HiveMQ extension
To test your custom HiveMQ extension, you need to have the HiveMQ Extension SDK on your classpath. If the SDK is not already there, add it to your pom.xml
:
The extension to test provides a custom PublishInboundInterceptor
which replaces every incoming publish payload with the string "modified"
. It looks like this:
To actually test the HiveMQ extension, we do the following:
Create a new
HiveMQTestContainerRule
Register the
Rule
with JUnit 4Add the HiveMQ Extension to the
HiveMQTestContainerRule
by providing itsid
,name
,version
,priority
,start-priority
andmain class
`Connect your MQTT clients to the HiveMQ instance that is running inside the container. Use the port that you retrieve from the rule with the
getMqttPort()
method.Assert the expected behavior.
Using JUnit5
If you want to use JUnit 5, add these dependencies to your pom.xml
:
The API is almost identical. Simply replace @Rule
with @RegisterExtension
and HiveMQTestContainerRule
with HiveMQTestContainerExtension
:
Conclusion
Using the HiveMQ Testcontainer makes the process of automatic testing of MQTT client applications and custom HiveMQ extensions easier and more robust.
Yannick Weber
Yannick is a Senior Software Engineer and one of the core members of HiveMQ's product development team. He has a strong interest in messaging technologies and is focusing on quality development of HiveMQ's many tools and extensions. In addition, he is the maintainer of the HiveMQ module in the testcontainers-java project.