Skip to content

hivemq.md

Latest commit

 

History

History
235 lines (158 loc) · 9.08 KB

hivemq.md

File metadata and controls

235 lines (158 loc) · 9.08 KB
Raw

HiveMQ Module

drawing

Automatic starting HiveMQ docker containers for JUnit4 and JUnit5 tests. This enables testing MQTT client applications and integration testing of custom HiveMQ extensions.

Please make sure to check out the hivemq-docs for the Community Edition and the Enterprise Edition.

Using HiveMQ CE/EE

HiveMQ provides different editions of on Docker Hub:

Both editions can be used directly:

Using the Community Edition:

Community Edition HiveMQ image inside_block:ceVersion

Using the Enterprise Edition:

Enterprise Edition HiveMQ image inside_block:eeVersion

Using a specifc version is possible by using the tag:

Specific HiveMQ Version inside_block:specificVersion

Test your MQTT 3 and MQTT 5 client application

Using an Mqtt-client (e.g. the HiveMQ-Mqtt-Client) you can start testing directly.

MQTT5 Client inside_block:mqtt5client

Settings

There are several things that can be adjusted before container setup. The following example shows how to enable the Control Center (this is an enterprise feature), set the log level to DEBUG and load a HiveMQ-config-file from the classpath.

Config Examples inside_block:eeVersionWithControlCenter

Note: The Control Center of HiveMQ can be accessed via the URL presented in the output of the starting container:

2021-09-10 10:35:53,511 INFO  - The HiveMQ Control Center is reachable under: http://localhost:55032

Please be aware that the Control Center is a feature of the enterprise edition of HiveMQ and thus only available with the enterprise image.

Testing HiveMQ extensions

Using the Extension SDK the functionality of all editions of HiveMQ can be extended. The HiveMQ module also supports testing your own custom extensions.

Wait Strategy

The raw HiveMQ module is built to wait for certain startup log messages to signal readiness. Since extensions are loaded dynamically they can be available a short while after the main container has started. We therefore provide custom wait conditions for HiveMQ Extensions:

The following will specify an extension to be loaded from src/test/resources/modifier-extension into the container and wait for an extension named 'My Extension Name' to be started:

Custom Wait Strategy inside_block:waitStrategy

Next up we have an example for using an extension directly from the classpath and waiting directly on the extension:

Extension from Classpath inside_block:extensionClasspath

Note Debugging extensions

Both examples contain .withDebugging() which enables remote debugging on the container. With debugging enabled you can start putting breakpoints right into your extensions.

Testing extensions using Gradle

In a Gradle based HiveMQ Extension project, testing is supported using the dedicated HiveMQ Extension Gradle Plugin.

The plugin adds an integrationTest task which executes tests from the integrationTest source set.

  • Integration test source files are defined in src/integrationTest.
  • Integration test dependencies are defined via the integrationTestImplementation, integrationTestRuntimeOnly, etc. configurations.

The integrationTest task builds the extension and unzips it to the build/hivemq-extension-test directory. The tests can then load the built extension into the HiveMQ Testcontainer.

Extension from filesystem inside_block:startFromFilesystem

Enable/Disable an extension

It is possible to enable and disable HiveMQ extensions during runtime. Extensions can also be disabled on startup.

Note: that disabling or enabling of extension during runtime is only supported in HiveMQ 4 Enterprise Edition Containers.

The following example shows how to start a HiveMQ container with the extension called my-extension being disabled.

Disable Extension at startup inside_block:startDisabled

The following test then proceeds to enable and then disable the extension:

Enable/Disable extension at runtime inside_block:runtimeEnable

Enable/Disable an extension loaded from a folder

Extensions loaded from an extension folder during runtime can also be enabled/disabled on the fly. If the extension folder contains a DISABLED file, the extension will be disabled during startup.

Note: that disabling or enabling of extension during runtime is only supported in HiveMQ 4 Enterprise Edition Containers.

We first load the extension from the filesytem:

Extension from filesystem inside_block:startFromFilesystem

Now we can enable/disable the extension using its name:

Enable/Disable extension at runtime inside_block:runtimeEnableFilesystem

Remove prepackaged HiveMQ Extensions

Since HiveMQ's 4.4 release, HiveMQ Docker images come with the HiveMQ Extension for Kafka, the HiveMQ Enterprise Bridge Extension and the HiveMQ Enterprise Security Extension. These Extensions are disabled by default, but sometimes you my need to remove them before the container starts.

Removing all extension is as simple as:

Remove all extensions inside_block:noExtensions

A single extension (e.g. Kafka) can be removed as easily:

Remove a specific extension inside_block:noKafkaExtension

Put files into the container

Put a file into HiveMQ home

Put file into HiveMQ home inside_block:hivemqHome

Put files into extension home

Put file into HiveMQ-Extension home inside_block:extensionHome

Put license files into the container

Put license file into the HiveMQ container inside_block:withLicenses

Customize the Container further

Since the HiveMQContainer extends from Testcontainer's GenericContainer the container can be customized as desired.

Add to your project

Gradle

Add to build.gradle:

testImplementation 'org.testcontainers:hivemq:{{latest_version}}'

Add to build.gradle.kts:

testImplementation("org.testcontainers:hivemq:{{latest_version}}")

Maven

Add to pom.xml:

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>hivemq</artifactId>
    <version>{{latest_version}}</version>
    <scope>test</scope>
</dependency>