<build>
<plugins>
...
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<version>${munit.version}</version>
<executions>
<execution>
<id>test</id>
<phase>test</phase>
<goals>
<goal>test</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
MUnit Maven Plugin
MUnit provides a Maven plugin that allows you to run your MUnit tests as part of your continuous integration environment.
Setting Up MUnit Maven Plugin
This documentation assumes you have the <munit.version>
property in your pom.xml.
-
Enable the MUnit Maven plugin in your
pom.xml
file:MUnit Maven Plugin -
Add MUnit dependencies to your
pom.xml
file:Dependencies<dependencies> ... <dependency> <groupId>com.mulesoft.munit</groupId> <artifactId>munit-runner</artifactId> <version>${munit.version}</version> <classifier>mule-plugin</classifier> <scope>test</scope> </dependency> <dependency> <groupId>com.mulesoft.munit</groupId> <artifactId>munit-tools</artifactId> <version>${munit.version}</version> <classifier>mule-plugin</classifier> <scope>test</scope> </dependency> ... </dependencies>
-
Configure the repositories for the MUnit dependencies and plugin:
Repositories<repositories> <repository> <id>mulesoft-releases</id> <name>MuleSoft Releases Repository</name> <url>https://repository.mulesoft.org/releases/</url> <layout>default</layout> </repository> </repositories>
Plugin Repositories<pluginRepositories> <pluginRepository> <id>mulesoft-release</id> <name>mulesoft release repository</name> <layout>default</layout> <url>https://repository.mulesoft.org/releases/</url> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories>
MUnit has Surefire support built in. The reports output to target/surefire-reports
.
Handling Parent POM Files
You can declare the MUnit plugin in a parent pom.xml
file and every child project under this file can reference this definition.
To configure the MUnit Maven plugin in a parent-child POM relationship, include the MUnit plugin declaration in the <pluginManagement>
section of your parent pom.xml
file.
In the following example, the pirate-pom
project declares the MUnit Maven plugin in its plugin management section, which defines a global configuration that each child under this parent can reference, override or even ignore.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.1.0</modelVersion>
<groupId>org.pirate</groupId>
<artifactId>pirate-pom</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>
<properties>
<munit.version>2.1.0</munit.version>
</properties>
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<version>${munit.version}</version>
<executions>
<execution>
<id>test</id>
<phase>test</phase>
<goals>
<goal>test</goal>
</goals>
</execution>
</executions>
<configuration>
<coverage>
<runCoverage>true</runCoverage>
<failBuild>false</failBuild>
<requiredApplicationCoverage>0</requiredApplicationCoverage>
<requiredResourceCoverage>0</requiredResourceCoverage>
<requiredFlowCoverage>0</requiredFlowCoverage>
<formats>
<format>console</format>
<format>html</format>
</formats>
</coverage>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>
Inheriting a Parent’s Plugin
To inherit the MUnit plugin in your child pom.xml
files, reference it in the <plugin>
section of each child POM file individually.
The following sample references pirate-pom
file as its parent and then declares the MUnit plugin in a <plugin>
section without specifying its <version>
because the MUnit plugin configuration is inherited from the <pluginManagement>
section in the parent POM file:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>
<groupId>org.pirate</groupId>
<artifactId>pirate-pom</artifactId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<groupId>com.mycompany</groupId>
<artifactId>ninja</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>mule</packaging>
<name>Mule ninja Application</name>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<app.runtime>4.1.4</app.runtime>
<munit.version>2.1.0</munit.version>
</properties>
<build>
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
Ignoring a Parent’s Plugin
Each child project under a parent pom.xml
file can ignore the plugin referenced in the parent’s plugin management section and not implement the plugin configuration declared there.
By not declaring the Munit Plugin in your <plugin>
section, you avoid inheriting the plugin declared in pirate-pom:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>
<groupId>org.pirate</groupId>
<artifactId>pirate-pom</artifactId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<groupId>com.mycompany</groupId>
<artifactId>ninja</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>mule</packaging>
<name>Mule ninja Application</name>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<mule.version>4.1.0</mule.version>
<munit.version>2.1.0</munit.version>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.mule.tools.maven</groupId>
<artifactId>mule-app-maven-plugin</artifactId>
<version>${mule.tools.version}</version>
<extensions>true</extensions>
<configuration>
<copyToAppsDirectory>true</copyToAppsDirectory>
</configuration>
</plugin>
</plugins>
</build>
</project>
Overriding a Parent’s Plugin
When inheriting the plugin from a parent POM file, you can also override the parent’s configuration. Overriding the plugin configuration from your parent POM file suppresses the original configuration requiring you to declare all necessary configurations again.
The following example overrides the console coverage report from its parent POM file, replacing it by the HTML report. Because the values from the other elements in the parent (<failBuild>
, <requiredApplicationCoverage>
, <requiredResourceCoverage>
, <requiredFlowCoverage>
) are not being referenced, this child file won’t inherit them and the default values will apply:
<coverage>
<runCoverage>true</runCoverage>
<failBuild>false</failBuild>
<requiredApplicationCoverage>0</requiredApplicationCoverage>
<requiredResourceCoverage>0</requiredResourceCoverage>
<requiredFlowCoverage>0</requiredFlowCoverage>
<formats>
<format>console</format>
<format>html</format>
</formats>
</coverage>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
<coverage>
<runCoverage>true</runCoverage>
<formats>
<format>html</format>
</formats>
</coverage>
</configuration>
</plugin>
Setting Up Coverage
Enabling Coverage Reports
To enable MUnit Coverage, add the following configuration to the MUnit plugin configuration:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<coverage>
<runCoverage>true</runCoverage>
</coverage>
...
</configuration>
</plugin>
</plugins>
Seting up a Minimum Coverage Level
The MUnit Coverage report can fail the build if a certain coverage level is not reached.
To make the build fail, add the following lines to the MUnit plugin configuration:
<coverage>
<runCoverage>true</runCoverage>
<failBuild>true</failBuild>
</coverage>
After enabling the <failBuild>
, define the coverage level. MUnit Coverage handles three different levels:
-
Application
-
Resource
-
Flow
The following example shows how to define the required coverage level:
<coverage>
<runCoverage>true</runCoverage>
<failBuild>true</failBuild>
<requiredApplicationCoverage>20</requiredApplicationCoverage>
<requiredResourceCoverage>10</requiredResourceCoverage>
<requiredFlowCoverage>5</requiredFlowCoverage>
</coverage>
Each value represents a percentage.
If you define coverage levels but set the property <failBuild>
to false, a warning shows up in the MUnit Coverage summary if the levels are not reached:
INFO] [CoverageManager] Printing Coverage Report...
[INFO] ===============================================================================
[INFO] MUnit Coverage Summary
[INFO] ===============================================================================
[INFO] * Resources: 3 - Flows: 6 - Message Processors: 7
[INFO] * Application Coverage: 71.43%
[INFO]
[WARNING] ----------------------------- WARNING --------------------------------------
[WARNING] * Application coverage is below defined limit. Required: 100.0% - Current: 71.43%
If you don’t define a coverage level, MUnit Coverage assumes a -1
value, which indicates that the build won’t fail due to lack of coverage.
Ignoring Flows for Coverage Report
<coverage>
<ignoreFlows>
<ignoreFlow>the-name-of-your-flow</ignoreFlow>
</ignoreFlows>
</coverage>
<ignoreFlows>
is a list, so you can ignore as many flows as you need:
<coverage>
<ignoreFlows>
<ignoreFlow>the-name-of-your-flow</ignoreFlow>
<ignoreFlow>the-name-of-another-flow</ignoreFlow>
</ignoreFlows>
</coverage>
Preparing Your Application
A placeholder must parameterize the part of the application trying to make use of a port. For example, to have your Mule application listening for HTTP traffic, provide the following configuration:
<http:listener-config name="HTTP_Listener_config">
<http:listener-connection host="0.0.0.0" port="8081" />
</http:listener-config>
<flow name="httpFlow">
<http:listener path="/" config-ref="HTTP_Listener_config"/>
</flow>
The previous application always listens in port 8081
. To make it dynamic, change it to:
<http:listener-config name="HTTP_Listener_config">
<http:listener-connection host="0.0.0.0" port="${http.port}"/> (1)
</http:listener-config>
<flow name="httpFlow">
<http:listener path="/" config-ref="HTTP_Listener_config"/>
</flow>
1 | Notice the placeholder ${http.port} . |
With the application coded in this way and the configuration of Dynamic Ports in place, your application starts each run listening on a different port.
Enabling Surefire Reports
MUnit has built-in support for Surefire. No additional configuration is needed, but you can disable it if you don’t need it:
<enableSurefireReports>false</enableSurefireReports>
The reports can be found under ${project.build.directory}/surefire-reports
.
By default, it is set to true
.
Running Tests Using the Plugin
Running MUnit Tests for a Mule Application
mvn clean test
Running a Specific MUnit Test Suite
By using the property munit.test
, you can instruct the MUnit Maven plugin to run only tests that belong to a specific test suite:
mvn clean test -Dmunit.test=<regex-test-suite>
This path is relative to src/test/munit
.
The property munit.test
accepts regular expressions. The expression is applied to the name of the MUnit Test Suite file. The regular expression language is the Java implementation.
For example:
mvn clean test -Dmunit.test=.*my-test.*
You can leverage this feature by adding naming conventions to your MUnit Test suites.
Running Specific MUnit Tests
In the same way that you instruct MUnit to run one test suite, you can also configure it to run a specific test inside that test suite. You must use the property munit.test
with the addition of the the special character #
to append the test name:
mvn clean test -Dmunit.test=<regex-test-suite>#<regex-test-name>
It also accepts regular expressions. The expression is applied to the attribute name
of the MUnit Test. For example:
mvn clean test -Dmunit.test=.*my-test.*#.*test-scenario-1.*
The tests inside the MUnit Test Suite that don’t match the regular expression are flagged as ignored.
You can also configure this from the pom.xml
configuration:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<munitTest>example-MunitTest-suite.xml</munitTest>
...
</configuration>
</plugin>
</plugins>
Running Tests Using a Specific Tag
You can run only the tests that you grouped under one specific tag:
mvn clean test -Dmunit.tags=<munit-tag>
You can also configure this from the pom.xml
configuration:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<munitTags>exampleMunitTag</munitTags>
...
</configuration>
</plugin>
</plugins>
You can specify more than one tag by separating them using a comma.
Skipping All Tests
MUnit leverages the same mechanism as Maven. To skip tests, you must use the skipTests
parameter:
mvn clean package -DskipTests
You can also configure this from the pom.xml
configuration:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<skipMunitTests>true</skipMunitTests>
...
</configuration>
</plugin>
</plugins>
Skipping Tests After One Suite Fails
MUnit allows you to skip the rest of the tests if one test suite fails:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<skipAfterFailure>true</skipAfterFailure>
...
</configuration>
</plugin>
</plugins>
If not specified, this value is false
by default.
Specifying The Runtime Product
You can specify the type of runtime in which your applications being tested will run. Accepted values are:
-
MULE
for community edition. -
MULE_EE
for enterprise edition.
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<runtimeProduct>MULE</runtimeProduct>
...
</configuration>
</plugin>
</plugins>
Specifying the Runtime Product Version
MUnit allows you to specify the runtime version in which your applications being tested will run.
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<runtimeVersion>4.2.2</runtimeVersion>
...
</configuration>
</plugin>
</plugins>
Specifying The JVM
You can specify the JVM (or the java executable) in which your applications being tested run. You must populate the munit.jvm
parameter with the path to the executable:
mvn clean package -Dmunit.jvm=/path/to/jdk/bin/java
You can also configure this from the pom.xml
configuration:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<jvm>/path/to/jdk/bin/java</jvm>
...
</configuration>
</plugin>
</plugins>
Additional Argument Lines
You can pass additional argument lines to the JVM. Specify each argument in a separate argLine
:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<argLines>
<argLine>-XX:MaxPermSize=512m</argLine>
<argLine>-Xmx1024m</argLine>
</argLines>
...
</configuration>
</plugin>
</plugins>
Environment Variables
To set additional environment variables during the test run, you can specify them with the respective key and value:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<environmentVariables>
<MY_ENV>exampleValue</MY_ENV>
<MY_OTHER_ENV>val2</MY_OTHER_ENV>
</environmentVariables>
...
</configuration>
</plugin>
</plugins>
As shown in the previous example, you can use environment variables to replace placeholders such as ${MY_ENV}
.
System Properties Variables
You may need to define specific system variables so that your MUnit test runs successfully:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<systemPropertyVariables>
<my.property.key>my.property.value</my.property.key>
</systemPropertyVariables>
...
</configuration>
</plugin>
</plugins>
Depending on the execution context, the system properties values may vary. When referencing these properties, it is a good practice to override their value to enforce test reproducibility.
You can do so using the -D
argument when running MUnit with Maven. Variables passed with the -D
argument take full priority over any other property. For example:
-Dmy.property.key=my.property.another.value
Redirecting Test Output to File
When running several tests, the build output can get very complex to read. MUnit allows you to redirect the output of each test suite to a file. This way, only the test results will remain in the build output and to you can check the respective file to check the standard output of each test suite.
These files are located in the testOutputDirectory
folder following the naming convention: munit.${suiteName}-output.txt
, where the suiteName
represents the name of the XML file relative to the MUnit test folder.
The test’s output that doesn’t belong to a particular suite won’t be printed to keep the build output clean, but it can be enabled by running maven in debug mode.
To redirect the output of each test suite to a file:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<redirectTestOutputToFile>true</redirectTestOutputToFile>
...
</configuration>
</plugin>
</plugins>
By default, it is set to false
Test Output Directory
You may want to choose the location where the test output files will be created. The path specified can be absolute or written as a Maven placeholder:
<plugins>
<plugin>
<groupId>com.mulesoft.munit.tools</groupId>
<artifactId>munit-maven-plugin</artifactId>
<configuration>
...
<testOutputDirectory>/my/absolute/path</testOutputDirectory>
...
</configuration>
</plugin>
</plugins>
<testOutputDirectory>${project.build.directory}/my/output/folder</testOutputDirectory>
By default, the files are created in ${project.build.directory}/munit-reports/output/
.
MUnit Maven Plugin Configuration Reference
The MUnit Maven Plugin offers a set of optional parameters that can be configured.
Name | Type | Description |
---|---|---|
|
List |
Additional JVM argument lines to set on the test run. |
|
Configuration |
Coverage configuration to be set on the test run. |
|
List |
Dynamic ports to be set on the test run. |
|
boolean |
Set value to |
|
String |
Name of the MUnit tests to run. |
|
String |
Name of the MUnit tags. Only tests tagged with these names will run. |
|
boolean |
Set to |
|
boolean |
Skip all tests if one fails. |
|
File |
Directory where the MUnit tests reside. |
|
String |
Version of the Mule runtime in case By default it runes with the mule-version defined in the pom.xml file of the mule-artifact.json. |
runtimeProduct |
String |
Type of runtime. Expected values are:
By default, this value is taken from the |
|
String |
Option to specify the JVM (or path to the java executable) to use. By default, the JVM will the same VM as the one used to run Maven. |
|
Map |
Additional environment variables to be set on the test run. |
|
boolean |
Set value to |
|
Map |
System properties to be set on the test run. |
|
File |
Directory where the test outputs will be written to. |