Testing Projects with MUnit

logo cloud IDE Cloud IDE

logo desktop IDE Desktop IDE

Run, modify, and create MUnit tests for your implementation and integration projects in Anypoint Code Builder. Import projects that contain MUnit test files.

MUnit is a MuleSoft unit testing framework for creating and running unit tests on a Mule application, as described in MUnit Overview.

Anypoint Code Builder provides a Testing panel from which you can run tests. In the Explorer, test suites are also located within the project directory /src/test/munit. The IDE also provides a Testing Results panel that provides the status of tests and logs that identify the status of tests that you run.

For MUnit features supported by Anypoint Code Builder, see Anypoint Code Builder Release Notes. Anypoint Studio also supports MUnit testing features.

Anypoint Code Builder - MUnit Extension, part of the Anypoint Extension Pack, supports MUnit functionality in Anypoint Code Builder. For information about extensions, see Anypoint Extension Pack.

Before You Begin

Configure the settings required to run MUnit.

For guidance, see Configure Access to MUnit Features.
Understand the fundamentals of MUnit. Refer to the MUnit documentation for an overview and guidance with test configurations:

For MUnit features supported by Anypoint Code Builder, see Anypoint Code Builder Release Notes. Anypoint Studio supports testing with all MUnit features.

Configure Access to MUnit Features

Make MUnit resources available to your project. The process differs depending on whether you have a Mule enterprise edition (EE) license.

Configure Maven Settings (Licensed Access):

If you have a Mule EE license (not a trial license), configure server credentials settings in the Maven file, settings.xml.
Configure Maven Settings (Unlicensed Access):

If you don’t have a Mule EE license or if your license is a trial license, configure your mule-artifact.json for the project. This option uses the Mule Kernel (formerly, Mule Community Edition) to run the tests.

Configure Maven Settings (Licensed Access)

If you have a Mule EE license (not a trial license), configure server credentials in the Maven file, settings.xml.

See Install an Enterprise License, to acquire or install an Enterprise license. If you are a MuleSoft customer and do not have credentials to access the MuleSoft Enterprise repository, contact Support and request Nexus enterprise credentials.

Navigate to settings.xml, typically in {user.home}/.m2/.

If settings.xml does not exist, create it.

Specify server settings with your Mule username and password within <servers></servers>:

<server>
  <username>yourMuleUsername</username>
  <password>yourMulePassword</password>
  <id>releases-ee</id>
</server>

Specify repository settings within <repositories></repositories>.

<profiles>
...
    <profile>

        <id>Mule</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <repositories>
            <repository>
                <id>MuleRepository</id>
                <name>MuleRepository</name>
                <url>https://repository.mulesoft.org/nexus-ee/content/repositories/releases-ee/</url>
                <layout>default</layout>
                <releases>
                    <enabled>true</enabled>
                </releases>
                <snapshots>
                    <enabled>true</enabled>
                </snapshots>
            </repository>
        </repositories>

    </profile>
...
</profiles>

For more information, see Configure Maven to Access MuleSoft Enterprise Repository.

Configure Maven Settings (Unlicensed Access)

If you do not own a Mule Enterprise Edition (EE) license or if your license is a trial license, configure your mule-artifact.json for the project.

Open your project in the Explorer.
In the mule-artifact.json file for your project, add the key-value pair "requiredProduct" : "MULE" to the existing configuration. For example:
```
{
    "minMuleVersion": "4.6.2",
    "javaSpecificationVersions": [
        "11"
    ],
    "requiredProduct" : "MULE"
}
```

For more information about Maven settings, see Maven Settings Files in Anypoint Code Builder.

MUnit Tasks and Workflows

A typical workflow includes one or more of the following steps:

Configure Access to MUnit Features
Opening tests
Running tests
Debugging
Fixing errors

If your project does not contain any tests, Anypoint Code Builder supports the following tasks:

Importing a project that contains MUnit tests
Creating tests or test suites in an existing project

Open MUnit Tests

Open the test suite XML from the Testing panel or the Explorer.

Testing panel - Open the Testing panel from the activity bar in the IDE:
1. Open a project that contains an MUnit test suite.
2. Click (Testing) to open the Testing panel.
3. Click or mouse over the suite or test name, and click (Go to test) or highlighted (Go to test) to open the XML file that contains the test.
  
  Clicking the test name also opens to the XML file.
Explorer - From the Explorer, locate MUnit test suite files in the project directory:
1. Open a project that contains an MUnit test suite.
2. In the activity bar, click () (Explorer).
3. Navigate to src/main/test/munit.
4. Click a test suite XML file to view the tests in the suite.

Run MUnit Tests

Run MUnit tests using any of these options:

Run Tests from the Testing Panel
Run Tests from the MUnit Configuration XML File
Run Tests with an MUnit Launch Configuration
Run MUnit Tests in Debug Mode
Run MUnit Tests with Coverage

When you run a test, a test build executes, and the Terminal displays the progress of the test. If all tests execute successfully the build succeeds. Otherwise, the build fails.

The IDE displays the results of the tests in the Testing panel, the Terminal, and the Test Results panels. Time-stamped logs are also available from the Test Results panel. You can clear the results at any time.

Run Tests from the Testing Panel

Run all tests, all tests in a suite, or a single test from the Testing panel. The Testing panel lists all MUnit test suites in the project.

To run tests:

Open a project that contains an MUnit test suite.

To check for test suites, see Open MUnit Tests.
From the activity bar, click (Testing) to open the Testing panel.

If the icon is not present, try right-clicking within the activity bar and selecting Testing to display the icon.

Run tests from the Testing panel at any of three levels:

Testing panel

Run tests with or without debugging features. If your XML contains breakpoints and you opt to debug, test execution stops at your breakpoints. For information about debugging, see Run MUnit Tests in Debug Mode.

1	All suites: To run all tests in all suites, click the Run Tests, Debug Tests, or Run Tests with Coverage icon. You can select the same options from the right-click menu.
2	Suite: To run all tests in a single suite, hover over or click the suite, and then click the Run Test, Debug Test, or Run Test with Coverage icon. You can select the same options from the right-click menu.
3	Test: To run a single test, hover over or click a test in a test suite, and then click the Run Test, Debug Test, or Run Test with Coverage icon.

You can select the same options from the right-click menu.

Monitor the test and review test results:

Testing panel and XML:

The following example displays a running test.

After the test runs, the panel and XML show the result.

Terminal:

The following example provides the progress of a test that runs and fails.

================================================================================
=== Running suite: myTestSuiteEx3.xml                                         ===
================================================================================


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Running test: test-03-suite3                                                 +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
java.lang.AssertionError:  at file: [myTestSuiteEx3.xml], line: [27]
Expected: "this" as String {encoding: "UTF-8", mediaType: "application/java; charset=UTF-8", mimeType: "application/java", class: "java.lang.String", contentLength: 4}
     but: "that" as String {encoding: "UTF-8", mediaType: "application/java; charset=UTF-8", mimeType: "application/java", class: "java.lang.String", contentLength: 4} at (root)
        at org.hamcrest.MatcherAssert.assertThat(MatcherAssert.java:20)

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
[INFO] ===============================================================================
[INFO] MUnit Run Summary - Product: MULE_EE, Version: 4.6.0
[INFO] ===============================================================================
[INFO]  >> myTestSuiteEx3.xml test result: Tests: 1, Errors: 0, Failures: 1, Skipped: 0
[INFO]   --- test-03-suite3 <<< FAILED
[INFO]
[INFO] ===============================================================================
[INFO]  > Tests:        1
[INFO]  > Errors:       0
[INFO]  > Failures:     1
[INFO]  > Skipped:      0
[INFO] ===============================================================================
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  03:10 min
[INFO] Finished at: 2024-04-29T08:49:39-07:00
[INFO] ------------------------------------------------------------------------

If the test results indicate any failures, go to Fix Test Errors.

To clear test results, see Clear Test Results.

Run Tests from the MUnit Configuration XML File

To run tests from the test suite XML:

From the Testing panel, open a test suite XML file in your project.

For guidance with opening from the Testing panel, see Open MUnit Tests.
Run a single test or all tests in the test suite XML file:
- To run a single test in the test suite XML:
  
  Place your cursor on a line that contains the XML for a test (munit:test).
  
  For example, on any line within XML similar to this example:
  
  <munit:test name="test-02-suite1"> <munit:validation> <munit-tools:assert-equals actual='#["that"]' expected='#["this"]' /> </munit:validation> </munit:test>
  
  Right-click, and select one of the following options:
  
  Run Test at Cursor
  
  Debug Test at Cursor
  
  Run Test at Cursor with Coverage
  
  If you do not see these menu items, be sure to open the XML file from or highlighted (*Go to test*) in the *Testing* panel.
- To run all tests in the test suite XML:
  
  Place your cursor in the XML file.
  
  Right-click, and select one of the following options:
  
  Run Tests in Current File
  
  Debug Tests in Current File
  
  Run Tests with Coverage in Current File
  
  If you do not see these menu items, be sure to open the XML file from or highlighted (*Go to test*) in the *Testing* panel.
Check the status of the running test in the Testing, Terminal, and Testing Results panels. See the example.

To clear test results, see Clear Test Results.

Run Tests with an MUnit Launch Configuration

Run MUnit tests from the Run and Debug panel with an MUnit launch configuration.

Create and run an MUnit launch configuration:

Open the Run and Debug panel.
Show me how
- Click the (Run and Debug) icon in the activity bar.
- Use the keyboard shortcuts:
  
  Mac: Cmd+Shift+d
  
  Windows: Ctrl+Shift+d
- In the desktop IDE, select View > Run.
- In the cloud IDE, click the (menu) icon, and select View > Run.

Add a launch configuration to launch.json:

Click (gear icon) to open the launch.json tab.

The default configuration looks something like this:

{
    "version": "0.2.0",
    "configurations": [
      {
        "type": "mule-xml-debugger",
        "request": "launch",
        "name": "Debug Mule Application",
        "mule.project": "${workspaceFolder}",
        "mule.runtime.args": "${config:mule.runtime.defaultArguments}"
      }
    ]
  }

In the launch.json file, add a comma after the first object in the array, and append the MUnit launch configuration by pressing Ctrl+Space to open the auto-complete menu and selecting MUnit Debug Launch. For example:

Adding launch configuration for MUnit from the auto-complete menu

This action adds a new JSON object named Munit Debug Tests to the file. For example:

{
    "version": "0.2.0",
    "configurations": [
      {
        "type": "mule-xml-debugger", (1)
        "request": "launch",
        "name": "Debug Mule Application",
        "mule.project": "${workspaceFolder}",
        "mule.runtime.args": "${config:mule.runtime.defaultArguments}"
      },
      {
        "type": "munit-xml-debugger", (2)
        "request": "launch",
        "name": "Munit Run Tests",
        "mule.project": "${workspaceFolder}",
        "munit.runtime.args": "${config:munit.runtime.defaultArguments}",
        "munit.runtime.debugger.version": "${config:munit.runtime.debugger.version}",
        "munit.debug": "false"
      }
    ]
  }

1	Launcher for the standard debugger, named `Debug Mule Application`.
2	Launcher for the MUnit debugger, named `Munit Run Tests`.

Save the configuration to launch.json.
Run MUnit tests from the MUnit Debug Tests launch configuration:
1. In the Run and Debug panel, select MUnit Debug Tests from the launch menu. For example:
2. Execute MUnit Debug Tests by clicking (launch) in the Run an Debug panel.
Verify that the MUnit tests run. See the example.

Run MUnit Tests in Debug Mode

Run your test in debug mode after adding breakpoints to the XML for your tests or Mule application. When Mule reaches the breakpoint, you can review variables in the Run and Debug panel.

Open a project that contains an MUnit test suite.
Add breakpoints to the XML for the Mule application or test suites.

For guidance with breakpoints and the Mule event, see Debugging Mule Applications.
Run your test with a debugging command using one of the following options:
- From the Testing panel, click (Debug test) at any level (all tests, all tests in a suite, or a single test).
  
  For more guidance, see Run Tests from the Testing Panel.
- From the suite XML, use the right-click menu to run the test.
  
  For more guidance, see Run Tests from the MUnit Configuration XML File.
- From a launch configuration in the Run and Debug panel.
  
  For guidance, see Run Tests with an MUnit Launch Configuration.
When the build process reaches a breakpoint, click (Run and Debug) from the activity bar to review variables, including the Mule event variables and test parameters. For example:
Examine the data, and address any issues.

By default, running tests fail after a timeout period. If a debugging session reaches a breakpoint in a test, the test and the build fail at timeout. See Test TimeOut Attribute.

Run MUnit Tests with Coverage

Run your test with coverage to measure how much of a Mule application is executed by a set of MUnit tests.

Open a project that contains an MUnit test suite.
Run your test with coverage using one of the following options:
- From the Testing panel, click Run Test with Coverage at any level (all tests, all tests in a suite, or a single test).
  
  For more guidance, see Run Tests from the Testing Panel.
- From the suite XML, right-click and select an option to run the test.
  
  For more guidance, see Run Tests from the MUnit Configuration XML File.
After the test suite runs, view coverage results using one of the following options:
- In the activity bar, click (Testing) to open the Testing panel. The Test Coverage panel shows coverage for directories and files:
- In the activity bar, click () (Explorer). Coverage is shown for directories and files.

Numeric and graphic percentages both indicate the percentage of event processors executed by the MUnit test.

Fix Test Errors

After running a test, fix any errors.

Review test errors in the XML by clicking the name of the failing test from the Testing panel.

The error in the XML example identifies the error java.lang.AssertionError.

Expected result (highlighted in red):

"yes" as String {encoding: "UTF-8", mediaType: "application/java;
                 charset=UTF-8", mimeType: "application/java",
                class: "java.lang.String", contentLength: 3}

Actual result (highlighted in green):

"no" as String {encoding: "UTF-8", mediaType: "application/java;
                charset=UTF-8", mimeType: "application/java",
                class: "java.lang.String", contentLength: 2} at (root)

You can also review the test results in the Test Results panel by clicking the failing test in the test logs. For example:

Error in the Test Results panel

Fix the error:
1. After reviewing the error, click the x icon to close the error message in the XML. For example:
2. Edit the XML to produce the expected output.
  
  For example, the failing test case in the example must return "yes" instead of "no".
After fixing the error, rerun the test to ensure that the fix works:
- To rerun the test from the XML, click (Test failure) for the test.
- To rerun the test from the Testing panel, click (Run test).
- To rerun the test from the Testing Results panel, open the panel, click the name of the failing test in the test logs, and click (Run test) from the test logs.

For guidance with MUnit XML configurations, see MUnit Test Structure Fundamentals and MUnit Event Processors.

To clear test results, see Clear Test Results.

Import a Project that Contains MUnit Tests

Mule projects created in Anypoint Studio and Anypoint Code Builder for your integrations or implementations can include MUnit tests.

To import and open the project into Anypoint Code Builder, see Importing Projects into the IDE.
To export a project from Anypoint Studio before importing to Anypoint Code Builder, use one of the procedures in Export Projects From Studio.
To start an integration that imports an example or template that contains MUnit tests from Anypoint Exchange, see Create an Integration Project.

Instead of starting with an empty project when creating the integration project, click Template or Example Project so that you can import the asset that contains tests into your project.

Create MUnit Tests and Test Suites

Configure MUnit tests and test suites from the XML editor.

Create an MUnit Suite
Create an MUnit Test

Create an MUnit Suite

Create an MUnit test suite in your project from the Explorer.

Open your project to /src/test/munit in the Explorer.

Create a suite file in the munit folder:

Right-click the munit folder and select New MUnit Test Suite File….
Provide a name for your suite, such as my-suite.xml.

The new suite file includes the XML declaration (<?xml>), <mule/> and <mule-config> elements. For example:

<?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"
                 xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
                 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="my-suite.xml" />

</mule>

Proceed to Create an MUnit Test.

Create an MUnit Test

Create an MUnit test in a new or existing test suite. Use auto-complete from the MUnit XML to start an MUnit tests. For guidance with your test configuration, refer to the MUnit documentation described in the prerequisites.

Open the test suite XML in the editor.

For guidance, see Open MUnit Tests.
In the XML, press Ctrl+Space to display available options, and type munit. For example:
Select munit:test and insert the test element in your suite. For example:
```
<munit:test name="name" >

</munit:test>
```

Provide a name and other XML elements to create the test.

For example, on any line within XML similar to these examples:

<munit:test name="test-01-suite1">
  <munit:validation>
    <munit-tools:assert-equals actual='#["that"]' expected='#["this"]' />
  </munit:validation>
</munit:test>

To find more examples, see MUnit Examples.

Run your test from the Test panel.

For guidance, see Run MUnit Tests.

Clear Test Results

After testing, you can clear test results from the Testing panel and the logs if you no longer need them.

From the Testing panel, click the Views and More Actions (…) menu, and select Clear All Results.
From the Test Results panel, click (Clear All Results). For example:

MUnit Examples

The MUnit documentation provides a number of examples. See MUnit Cookbook.

The following MUnit test example validates if the payload is the string "Example":

<munit:test name="my-test" doc:id="e536ea1f" description="Test Example">
  <munit:execution >
  	<flow-ref doc:name="Reference to Main Flow" doc:id="058d41ef" name="mainFlow"/>
  </munit:execution>
  <munit:validation >
  	<munit-tools:assert-equals actual="#[payload]" expected="Example"
                               message="The payload is expected to be 'Example'."/>
  </munit:validation>
</munit:test>

For information about munit:execution, munit:validation, and other MUnit testing elements, see MUnit Test Structure Fundamentals and MUnit Event Processors.