Contact Us 1-800-596-4880
  1. Homepage
  2. MUnit (3.2)

  3. MUnit Test Structure Fundamentals

MUnit Test Structure Fundamentals

logo acb active Anypoint Code Builder

logo studio active Anypoint Studio

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 use multiple MUnit test suite files. 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 similar to 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

Specify the minimum required Mule version to run a test suite by defining 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 and it represents the scenario to test.

Three optional scopes divide MUnit tests:

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.

 
<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>
munit-test
Figure 1. A Studio representation of the MUnit Test

MUnit Test Reference

Name Description

name

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

description

Describes the scenario to test.

ignore

Defines if the test must be ignored. If not present, the test isn’t ignored.

tags

Comma-separated list of tags to assign to the test.

expectedErrorType

Defines the error Type to receive after executing the test.

expectedException

Defines the exception to receive after executing the test.

expectedErrorDescription

Defines the error description to receive after executing the test.

timeOut

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

MUnit Test Description Attribute

MUnit tests require a description. The description must be useful and representative of the tested scenario. This description shows in the test console before running the test, and also in the reports. The more representative the description, the easier it is to read and troubleshoot failures.

Ignore a Test

When a test fails or has inconvenient side effects, you can shut it down without commenting out the code.

To ignore a test, add the ignore boolean to its 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.

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 the 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')]">

MUnit ignores this test if the Mule version is earlier than 4.1.4. Other possible functions are muleVersionEqualTo and muleVersionNewerThan.

Test TimeOut Attribute

An 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

You can tag your tests and 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>
Tags field highlighted in Studio.
Figure 2. In Anypoint Studio, you can define tags in the Tags field.

MUnit Test Expected Error and Exception Attributes

To validate that a flow or sub-flow you’re testing fails and throws a specific error, add the expectedErrorType, expectException, and expectedErrorDescription attributes 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>
Failure Expectation section highlighted in Studio.
Figure 3. A visual representation on Anypoint Studio

  • The expectedErrorType attribute expects an error ID defined in the tested application.
    This attribute validates that your application throws a defined error type. If you define an errorType that does not exist in your application, the test doesn’t 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 throws an FTP:ILLEGAL_PATH error.
    If none of your flows are using an FTP connector, then the error type isn’t defined within your application and the test doesn’t run.

    You mustn’t typify ErrorTypes that belong to the Mule Runtime. For example, you can define MULE:RETRY_EXHAUSTED 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 same type of the class name you’re 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 validates that your application throws an error and the error has a description that is equal to or contains the expected error description. If you define that your test expects an error and none is thrown or the error 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 so you can add processing or actions to run before and after the entire MUnit test or MUnit test suite executes:

  • Before and After Suite Scopes.

  • Before and After Test Scopes.

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

See Before and After Scopes reference for additional information.