JUnit Jupiter Annotations, Chapter 2

Overview

In part 1 I introduced you to JUnit 5 annotations:

  • @DisplayName
  • @Test

In this chapter, I’ll show you two more annotations:

  • @Disabled
  • @Nested

With code examples for both, and a video where I write code using these annotations.

You can download the complete sample application from GitHub if you like.

Let’s get started!

The Class Under Test

Before diving into the meat of this, let me show you the class under test. It’s called Echo, and it’s very simple (so as not to get in the way of the lesson):

public class Echo {
  public String echo(String stringToEcho) {
    return stringToEcho;
  }

  public Integer echo(Integer intToEcho) {
    return intToEcho;
  }

}

The class is pretty simple: its contract stipulates that it echoes whatever is passed, unchanged.

In true Test-Driven Development (TDD) style, you’ll write the implementation after you write the unit tests.

@Disabled

@Test
@Disabled
@DisplayName("A disabled test")
void testNotRun() {
  // This method will not run
}

Use this annotation to tell the JUnit platform not to run this test method. Notice that the method is annotated with the @Test annotation. Normally, JUnit would execute this method at the appropriate point in the test lifecycle, but annotating the method with @Disabled tells JUnit not to run it.

Why not just remove the @Test annotation? It might be good for documentation purposes to leave it annotated with @Test so you know it was a test method, or maybe you just want to temporarily disable the method.

@Nested

This is a super cool new feature of JUnit 5 that allows you to create nested (inner) classes that keep groups of tests together in the same main test class, but separate from the other test methods in that class.

In the case of the Echo class, both methods are called echo, so you need some way of distinguishing which echo overload you’re testing. You could do something like this:

@Test
public void testEcho_String() {
.
.
}

@Test
public void testEcho_Integer() {
.
.
}

And that would work just fine. But JUnit 5 and the Jupiter API give you the @Nested annotation. So let’s use it!

 
  @Nested
  public class StringEchoTest {

    @Test
    public void testEcho() {

      classUnderTest = new Echo();

      String expectedString = "This is a test";

      assertAll("String version of echo() method",
          // equals() should match, 
          /// but that is not good enough
          () -> assertEquals(expectedString, 
                 classUnderTest.echo(expectedString)),
          // hash codes should match, 
          /// but still not quite good enough
          () -> assertEquals(expectedString.hashCode(), 
                 classUnderTest.echo(expectedString).hashCode()),
          // This should do the trick
          () -> assertEquals(
              System.identityHashCode(expectedString),
               System.identityHashCode(
                classUnderTest.echo(expectedString))));
    }

  }

  @Nested
  public class IntegerEchoTest {

    @Test
    public void testEcho() {

      classUnderTest = new Echo();

      Integer expectedInteger = Integer.valueOf(238);

      assertAll("String version of echo() method",
          () -> assertEquals(expectedInteger, 
                 classUnderTest.echo(expectedInteger)),
          () -> assertEquals(expectedInteger.hashCode(), 
                 classUnderTest.echo(expectedInteger).hashCode()),
          () -> assertEquals(
              System.identityHashCode(expectedInteger),
                System.identityHashCode(
                 classUnderTest.echo(expectedInteger))));
    }
  }

Video

In the video below, I’ll go over these annotations in detail, and you can watch me explain the code as I write it.

Conclusion

In this article, I showed you some of the annotations from the JUnit Jupiter API you’re most likely to use. But there is a LOT more to JUnit than the Annotations.

Be sure to follow along with this series here on my blog, and the accompanying videos on my YouTube channel.

To learn more about the annotations provided by the JUnit Jupiter API visit the JUnit 5 User’s Guide.

Check out my IBM developerWorks JUnit 5 Tutorial Series:

Check out the first post in this series here.

 

JUnit Jupiter Annotations: Chapter 1

Overview

In order to run JUnit tests, you need to tell the JUnit Platform about your test classes: which methods are test methods, which methods are part of the test method lifecycle, whether to use extensions, and so on.

You do this through annotations, which are metadata about how to run your tests.

You can download the code from GitHub if you like:

https://github.com/makotogo/HelloJUnit5

In this post, I’ll cover the two annotations you’re likely to use with JUnit, along with examples of each.

@Test

@Test
@DisplayName("When numbers are > 0")
public void testAdd() {
  // Unit test code here
}

Use this annotation to tell the JUnit platform that the method is a test method. This means it will be invoked at the appropriate point in the lifecycle, complete with all the bells and whistles.

Every method you want to run as a test method needs to be annotated with the @Test annotation.

@DisplayName

@DisplayName("Testing using JUnit 5")
public class JUnit5AppTest {
.
.
  @Test   
  @DisplayName("When numbers are > 0")   
  public void testAdd() {     
    // Unit test code here 
  }
.
.
}

By default, the name displayed for a test class or method is the name of the class or method, respectively. The @DisplayName annotation tells JUnit to use the specified name instead.

Check it out: compare the following examples, first without the annotation, then with it. (Both are from the JUnit View in Eclipse)

Without the @DisplayName annotation:

 WithoutDisplayName

And with the @DisplayName annotation:

WithDisplayName

In this simple example, you can see already that the report is cleaner. But when there are several test methods, the value of @DisplayName gets even clearer:

DisplayNameLargerTest

Video

In the video below, I’ll go over the annotations in detail, and you can watch me explain the code as I write it.

Conclusion

In this article, I showed you two of the annotations from the JUnit Jupiter API you’ll definitely want to use. Stay tuned for more in this series, where I’ll show you more annotations from the JUnit Jupiter API.

Be sure to follow along with this series here on my blog, and the accompanying videos on my YouTube channel.

To learn more about the annotations provided by the JUnit Jupiter API visit the JUnit 5 User’s Guide.

Check out my IBM developerWorks JUnit 5 Tutorial Series:

JUnit Jupiter Assertions: Setup

Hey everybody!

The Assertions class of the JUnit Jupiter API is the GO-TO for testing your code. After all, how do you check a condition without an Assertion?

I’m doing a multi-part series on the Assertions API on my YouTube channel (Makoto TV), so make sure and check it out.

In Part 0, I show you how to get the code that accompanies all of the videos, and get your Eclipse workspace setup.

 

Make sure and check it out.

And thanks for reading!

–jsp