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’s 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=""
	xmlns:munit="" xmlns:munit-tools=""

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

	<!-- Tests -->


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. All of them are optional:

Scope Description


The behavior scope is meant to set all the preconditions before executing the test logic.
Mocks and Spies should go in this section.


The execution scope is meant to have the testing logic which will wait for all processes to finish before executing the next scope.


The validation scope is meant to have all the validations regarding the result of the execution scope.
Assertions and Verifications should go here.

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


         <flow-ref name="exampleFlow"/>

         <munit-tools:assert-that ...>
Figure 1. A Studio representation of the MUnit Test

MUnit Test Reference

Name Description


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


Describes the scenario being tested.
This attribute is mandatory.


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


Comma separated list of tags to assign to the test.


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


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

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.

Ignoring 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"
      description="Test to verify scenario 1">

The default value for the ignore attribute is false.

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


Test Tag Attribute

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

  description="A test that works as an example"
  tags="integration,http" >
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 and expectException as follows:

<munit:test name="MUnit-test-suite"
  description="A test that works as an example"
  expectedErrorDescription="retries exhausted">
munit test concept e7280
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 exists in your application, the test does not run.

    <munit:test name="MUnit-test-suite"
      description="Test Error Type"

    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 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"

    If you define that your test expects an exception and none is thrown, the test fails immediately.

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.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub
Give us your feedback!
We want to build the best documentation experience for you!
Help us improve with your feedback.
Take the survey!