MUnit Test Structure Fundamentals

MUnit Test Suite

The base file in MUnit is the test suite file, an XML file located in the src/test/munit directory of your Mule application project. You can have as many MUnit test suite files as you need. Each MUnit test suite file is a collection of MUnit tests, and runs independently from other MUnit test suites.

An MUnit test suite can contain any combination of the following components:

Before/After Suites
Before/After Tests
MUnit tests

Each MUnit test suite is, behind the scenes, no different than a Mule configuration file. You can use several of the Mule top level elements such as flow, sub-flow, and scripts.

MUnit Configuration

The MUnit configuration element (munit:config) identifies a Mule configuration file as an MUnit suite file:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:munit="http://www.mulesoft.org/schema/mule/munit" xmlns:munit-tools="http://www.mulesoft.org/schema/mule/munit-tools"
	xmlns="http://www.mulesoft.org/schema/mule/core"
	xsi:schemaLocation="
		http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
		http://www.mulesoft.org/schema/mule/munit http://www.mulesoft.org/schema/mule/munit/current/mule-munit.xsd
		http://www.mulesoft.org/schema/mule/munit-tools  http://www.mulesoft.org/schema/mule/munit-tools/current/mule-munit-tools.xsd">

	<munit:config name="An MUnit Suite" />

	<!-- Tests -->

</mule>

Ignore a Suite

To ignore a whole suite from running, you can use the ignore attribute of the configuration:

<munit:config name="A MUnit Suite" ignore="true"/>

Minimum Mule Version

To specify that a suite should run if the Mule version that is equal or newer than a specific version, use the minMuleVersion attribute of the configuration:

<munit:config name="A MUnit Suite" minMuleVersion="4.1.4"/>

MUnit Test

An MUnit test is the basic processor of an MUnit test suite. It represents each test scenario you want to try.

The MUnit test is divided in three scopes:

Scope	Description
Behavior	The behavior scope sets all the preconditions before executing the test logic.
Execution	The execution scope contains the testing logic which waits for all processes to finish before executing the next scope.
Validation	The validation scope contains all the validations for the results of the execution scope.

Scope

Description

Behavior

The behavior scope sets all the preconditions before executing the test logic.

Execution

The execution scope contains the testing logic which waits for all processes to finish before executing the next scope.

Validation

The validation scope contains all the validations for the results of the execution scope.

These scopes are optional.

<munit:test name="exampleTest" description="Test to verify scenario 1">>

     <munit:behavior>
         <!-- Processors to set preconditions for the test -->
     </munit:behavior>

     <munit:execution>
         <flow-ref name="exampleFlow"/>
     </munit:execution>

     <munit:validation>
         <!-- Processors to validate result -->
     </munit:validation>
 </munit:test>

Figure 1. A Studio representation of the MUnit Test

MUnit Test Reference

Name Description

Name	Description
`name`	Defines the name of the test. The name must be unique inside the test suite. This attribute is mandatory.
`description`	Describes the scenario being tested.
`ignore`	Defines if the test should be ignored. If not present, the test is not ignored.
`tags`	Comma separated list of tags to assign to the test.
`expectedErrorType`	Defines the error Type that should be received after the execution of this test.
`expectedException`	Defines the exception that should be received after the execution of this test.
`expectedErrorDescription`	Defines the error description that should be received after the execution of this test.
`timeOut`	Defines maximum time in milliseconds that the test can run before failing.

name

Defines the name of the test. The name must be unique inside the test suite.
This attribute is mandatory.

description

Describes the scenario being tested.

ignore

Defines if the test should be ignored. If not present, the test is not ignored.

tags

Comma separated list of tags to assign to the test.

expectedErrorType

Defines the error Type that should be received after the execution of this test.

expectedException

Defines the exception that should be received after the execution of this test.

expectedErrorDescription

Defines the error description that should be received after the execution of this test.

timeOut

Defines maximum time in milliseconds that the test can run before failing.

MUnit Test Description Attribute

In MUnit, you must write a description for your test. Ideally, you should write a useful, representative description of the scenario you are testing. This description displays in the test console before running the test, and also in the reports. The more representative the description, the easier to read and troubleshoot any failures.

Ignore a Test

There may be scenarios where you need to shut down a test. Whether this be because the test is failing or because it has inconvenient side effects. MUnit allows you to ignore a specific test so that you don’t have to manually comment out the code.

You can ignore any of your tests by adding the ignore boolean to the test definition:

<munit:test name="my-flow-Test"
      ignore="true"
      description="Test to verify scenario 1">
</munit:test>

The default value for the ignore attribute is false.

In Anypoint Studio, you can check the Ignore Test option.

You can also use expressions to ignore a test based on your current mule version or on your current operating system:

Ignore a Test Based on Operating System

<munit:test name="linux-ignore-test" ignore="#[Munit::osEqualTo('Mac OS X')]">

Ignore a Test Based on Mule Runtime Engine Version

<munit:test name="mule-version-ignore-test" ignore="#[Munit::muleVersionPriorTo('4.1.4')]">

This test will be ignored if the Mule version is prior to 4.1.4. Other possible functions are muleVersionEqualTo and muleVersionNewerThan.

Test TimeOut Attribute

Each MUnit test automatically fails if it takes more than 2 minutes to complete. Use the timeOut attribute to set a custom maximum time --in milliseconds-- that the test can run before failing:

<munit:test
  name="custom-timeout-test"
  description="This test has a timeout of 10 seconds"
  timeOut="10000" >
  ....
</munit:test>

Test Tag Attribute

MUnit allows you to tag your tests, so you can choose to run tests under a specific tag. For example:

<munit:test
  name="exampleTest"
  description="A test that works as an example"
  ignore="true"
  tags="integration,http" >
		…
</munit:test>

Figure 2. In Anypoint Studio, you can define tags in the proper field.

MUnit Test Expected Error and Exception Attributes

Assume that you want to validate that the flow or sub-flow you are testing fails and throws a specific error. MUnit allows you to add the attributes expectedErrorType, expectException, and expectedErrorDescription, as follows:

<munit:test name="MUnit-test-suite"
  description="A test that works as an example"
  expectedErrorType="RETRY_EXHAUSTED"
  expectedException="java.lang.RuntimeException"
  expectedErrorDescription="retries exhausted">
  ...
</munit:test>

Figure 3. A visual representation on Anypoint Studio

The expectedErrorType attribute expects an error ID defined inside the application being tested.
This attribute allows you to validate that a defined error type in your application is thrown. If you define an errorType that does not exist in your application, the test does not run.
```
<munit:test name="MUnit-test-suite"
  description="Test Error Type"
  expectedErrorType="FTP:ILLEGAL_PATH">
  ...
</munit:test>
```
This Error Type test expects that an FTP operation will throw an FTP:ILLEGAL_PATH error.
If none of your flows are using an FTP connector, then the error type is not defined within your application and the test will not run.

ErrorTypes that belong to the Mule Runtime do not need to be typified. For example, MULE:RETRY_EXHAUSTED can be defined as simply RETRY_EXHAUSTED.
The attribute expectException expects a literal exception class name.
You must provide the canonical class name of the exception that you expect. MUnit then validates that the underlying cause for the exception thrown is of the exact same type of the class name you are expecting.
```
<munit:test name="testExceptions"
  description="Test Exceptions"
  expectedException="java.lang.RuntimeException">
  ...
</munit:test>
```
If you define that your test expects an exception and none is thrown, the test fails immediately.
The attribute expectedErrorDescription expects an error description.
This attribute allows you to validate that an error is thrown and this error has description that is equals or contains the expected error description. If you define that your test expects an error and none is thrown or the error thrown description doesn’t match, the test fails immediately.
```
<munit:test name="testExpectedErrorDescription"
  description="Test Expected Error Description Attribute"
  expectedErrorDescription="An error has occurred">
  ...
</munit:test>
```

Before and After Scopes

As with other testing frameworks, MUnit provides a set of scopes that allow you to add processing or actions to run before and/or after the entire MUnit test or MUnit test suite execute:

Before and After Suite Scopes.
Before and After Test Scopes.

The ID field for each component must be unique across all your application. The before and after scopes cannot share the same name between them, nor have the same name as any flow in your application.

See Before/After scopes reference for more information.