MUnit for Java Programmers: Test Assertions

At the heart of unit tests are assertions which provide a mechanism for comparing expected outcomes with actual outcomes. JUnit provides a large selection of overloaded convenience methods that perform predefined logical assertions, such as testing for equality, negations, and conditions specified by a matcher. MUnit also provides a similar set of assertion capabilities such as to assert two values as equals, validate a logical condition, and a variety of other custom assertions that replicate familiar JUnit assertions.

Assert equality

Asserting equality is the simplest validation to set. JUnit provides a method which accepts three parameters, they are the expected value, followed by actual value, and optionally preceded by a message to output on failure.

@Test
public void testAssertEquals() {
  String actual = "animals";
  assertEquals("All animals are equal, some more than others", 
                actual, "animals");
}

Fig 1: JUnit test showing how to assert equality.

MUnit offers the equivalent. A simple equality comparison of expected with actual values with an optional message parameter that is output when the test fails.

Fig 2: MUnit test showing how to assert equality.

Assert that a condition is true

A modification of the equality assertion is the Assert That expression which asserts that an actual value satisfies a condition specified by a matcher. The matcher is provided by the hamcrest libraries. Hamcrest is a framework for writing matcher objects allowing ‘match’ rules to be defined declaratively.

@Test
public void testAssertThatHasItems() {
  assertThat(Arrays.asList("cat", "dog", "hamster"), 
                           hasItems("cat", "hamster"));
}

Fig 3: Asserts that the array contains, at least “cat” and “hamster.”

MUint replicates similar functionality with the AssertThat processor. 

Fig 4: Asserts that the array contains at least “hamster.”

Matchers

MUnit tools provide a set of matchers written as DataWeave functions that provide assertion conditions. They replicate common hamcrest matchers such as String matchers: startsWith, endsWith, containsString, and collection matchers such as everyItem, and hasItem.

Customer assertion and matchers

Some test use cases may not be adequately tested using the out-of-the-box assertions or matchers, which requires a method of creating customer assertion behaviours. This is why Hamcrest provides an abstract class (TypeSafeMatcher) to extend and implement custom matching logic.

public class IsCat extends TypeSafeMatcher {
 
  @Override
  protected boolean matchesSafely(String pet) {
    try {
      return pet.equalsIgnoreCase("cat");
    } catch (Exception e){
      return false;
    }
  }
 
  @Override
  public void describeTo(Description description) {
    description.appendText("Only cats allowed");
  }
    
  public static Matcher onlyCats() {
    return new IsCat();
  }

}

Fig. 5: Custom Hamcrest matcher.

import static com.mulesoft.assertion.IsCat.onlyCats;

@Test
public void givenAPet_whenIsOnlyCat_thenCorrect() {
  String pet = "CAT";
  assertThat(pet, onlyCats());
}

Fig. 6: Import static method to use as Hamcrest match.

MUnit provides two ways to create customer expressions that provide assertion logic: Assert expression and Run Custom. This may be expressed as a simple DataWeave script that makes a comparison, implemented as a custom DataWeave matcher or as a org.mule.munit.assertion.api.MunitAssertion implementation. 

Fig. 7: A custom validation expression written in DataWeave 2.0.

Custom DataWeave matchers

To increase the reusability of assertion logic, custom DataWeave matchers can be created and externalized into a DataWeave script located in test resources directory (src/test/resources).

import * from dw::test::Asserts

  fun beACat(): Matcher =
    (actual:String) -> do {
      var matchesCat = (actual == "Cat")
      ---
      {
        matches: matchesCat,
        description: {expected: " a cat.", actual: actual}
      }
    }

Fig 8: Custom DataWeave matcher CustomMatchers.dwl.

Fig 9: Use the CustomMatchers::beACat() custom matcher.

Custom MUnit assertions

The full power of Java can be unleashed to develop a custom assertion by implementing the org.mule.munit.assertion.api.MunitAssertion interface and execute() method. A dependency on the MUnit::Assert Module is required.

public class CustomAssertion implements MunitAssertion {
  @Override
  public void execute(TypedValue exp, Object p) throws AssertionError{ 
    if (!"CAT".equals(exp.getValue())) { 
      throw new AssertionError("Error the payload is incorrect");
    }
   }
}

The custom assertion is referenced in the Run Custom event processor.

And must also be configured in the mule-artifact.json as an exported package.

{
  "name": "mule-application",
  "minMuleVersion": "4.2.2",
  "classLoaderModelLoaderDescriptor": {
    "id": "mule",
    "attributes": {
      "exportedPackages": ["com.mulesoft.assertion.custom"]
    }
  }
}

Conclusion

The assertion capabilities provided by MUnit replicate the most commonly used assertions by developers of JUnit tests. It includes conveniences by predefining assertion types — such as Assert Equals — but also allows the developer to create bespoke assertion testing with the Custom DataWeave Matchers. A Java developer will add ease with the manner in which MUnit provides for assertion testing and thanks to its faithful replication of typical JUnit assertions and HamCrest matchers.

If you are interested in learning more about MUnit and DevOps related activities essential for the implementation of production-ready Mule applications then consider taking our course Anypoint Platform Development: Production-Ready Development Practices (Mule 4).