---
schema_version: "1"
id: 479c2fa5ade05d99902c10c4afa2ea1717fa3eb96347f1043aaf7ef7ad124c91
title: MUnit Test Structure Fundamentals
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/munit/2.3/munit-test-concept.md
canonical_url: https://docs.mulesoft.com/munit/2.3/munit-test-concept
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 1c65923c0260a6e77ffd77e5bd30d82558e9d8da903901393ff07220938fd00e
description: MuleSoft Documentation Site
release: "2.3"
latest: false
---
---
product: MUnit
version: 2.3
---

# MUnit Test Structure Fundamentals

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## 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
<?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:

```xml
<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:

```xml
<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:

<table><colgroup><col> <col></colgroup><thead><tr><th>Scope</th><th>Description</th></tr></thead><tbody><tr><td><p>Behavior</p></td><td><p>The behavior scope sets all the preconditions before executing the test logic.</p></td></tr><tr><td><p>Execution</p></td><td><p>The execution scope contains the testing logic which waits for all processes to finish before executing the next scope.</p></td></tr><tr><td><p>Validation</p></td><td><p>The validation scope contains all the validations for the results of the execution scope.</p></td></tr></tbody></table>

These scopes are optional.

```xml
<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](/mulesoft/current/en-us/munit/2.3/_images/munit-test-concept-9c736.png)

Figure 1. A Studio representation of the MUnit Test

### MUnit Test Reference

<table><colgroup><col> <col></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><p><code>name</code></p></td><td><p>Defines the name of the test. The name must be unique inside the test suite.<br>This attribute is mandatory.</p></td></tr><tr><td><p><code>description</code></p></td><td><p>Describes the scenario being tested.</p></td></tr><tr><td><p><code>ignore</code></p></td><td><p>Defines if the test should be ignored. If not present, the test is not ignored.</p></td></tr><tr><td><p><code>tags</code></p></td><td><p>Comma separated list of tags to assign to the test.</p></td></tr><tr><td><p><code>expectedErrorType</code></p></td><td><p>Defines the error Type that should be received after the execution of this test.</p></td></tr><tr><td><p><code>expectedException</code></p></td><td><p>Defines the exception that should be received after the execution of this test.</p></td></tr><tr><td><p><code>expectedErrorDescription</code></p></td><td><p>Defines the error description that should be received after the execution of this test.</p></td></tr><tr><td><p><code>timeOut</code></p></td><td><p>Defines maximum time in milliseconds that the test can run before failing.</p></td></tr></tbody></table>

#### 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:

```xml
<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.

![ignore-test](/mulesoft/current/en-us/munit/2.3/_images/munit-test-concept-de4c9.png)

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

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

Ignore a Test Based on Mule Runtime Engine Version

```xml
<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:

```xml
<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:

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

![test-tags](/mulesoft/current/en-us/munit/2.3/_images/munit-test-concept-c2d9f.png)

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:

```xml
<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>
```

![munit test concept e7280](/mulesoft/current/en-us/munit/2.3/_images/munit-test-concept-e7280.png)

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.

  ```xml
  <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.

  ```xml
  <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.

  ```xml
  <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](https://docs.mulesoft.com/munit/2.3/before-after-scopes-reference) reference for more information.