What's the purpose of the JUnit 5 @Nested annotation?

Question

In JUnit 5, there is a new annotation: @Nested.

I understand how the annotation works, I understand why we use nested classes, I just don't understand why we need to have nested test classes.

Parceling

To form logical groupings of test cases. – Plunger

To add to that... Small example: EatsTest, BehaviourTest can be nested inside DogTest, etc. See junit.org/junit5/#nested-tests – Marcusmarcy

That link should be: junit.org/junit5/docs/current/user-guide/#nested-tests – Adaadabel

It also helps promoting Behaviour Driven Development style like rspec's describe/it:rspec.info/documentation/3.4/rspec-core/#Nested_Groups – Middleton

Answer 1

The @Nested annotation allows you to have an inner class that's essentially a test class, allowing you to group several test classes under the same parent (with the same initialization).

Mohawk

Answer 2

I just don't understand why we need to have nested test class in our test.

@Nested makes really sense to organize big test classes.

Typical use case

Very often, developer teams define a test class by class to test. That is a shared good practice but it also may make your test class very big and to count several hundred of lines. You can indeed have classes to test with multiple methods to test, multiple scenarios for each one and also some initialization steps required in the unit test methods to test the scenarios.
All of these will naturally increase the test class size.
Above a threshold (maybe 500 lines or about), it becomes legitimate to ask yourself whether a refactoring is needed.

A big class (test class or not), even well organized is harder to read, maintain than multiple classes grouping things with high cohesion/relationship between.
In the unit tests cases, it can be sometime still worse because you may not find a test scenario and write a new one while it existed but you didn't manage to find it because the test class is big.

@Nested : the solution

@Nested addresses this issue by giving the possibility to group multiple test methods inside multiple nested classes of a main(outer) test class.
The test methods of all nested classes defined in the main(outer) test class are handled as any test methods. So @BeforeEach, @AfterEach, @ExtendWith... are applied for all the them.
The single exception is @BeforeAll and @AfterAll :

Only non-static nested classes (i.e. inner classes) can serve as @Nested test classes. Nesting can be arbitrarily deep, and those inner classes are considered to be full members of the test class family with one exception: @BeforeAll and @AfterAll methods do not work by default. The reason is that Java does not allow static members in inner classes. However, this restriction can be circumvented by annotating a @Nested test class with @TestInstance(Lifecycle.PER_CLASS) (see Test Instance Lifecycle).

Using @Nested combined with @DisplayName that takes a String value becomes still finer as the display name will be used for test reporting in IDEs and build tools and may contain spaces, special characters, and even emoji.

Example

I have a FooService with multiple methods and multiple scenarios. I can groups scenarios of the same concern inside nested classes of the unit test class.
Here I choose the method to test to group them (so I group by scenario) but the discriminator could be another thing if it makes sense.

For example :

public class FooServiceTest {

    Foo foo;

    // invoked for ALL test methods
    @BeforeEach
    public void beforeEach() {
         Foo foo = new Foo(...);
    }

    @Nested
    @DisplayName("findWith methods")
    class FindMethods {
        @Test
        void findWith_when_X() throws Exception {
             //...
             foo.findWith(...);
             //...
        }
        @Test
        void findWith_when_Y() throws Exception {
             //...
             foo.findWith(...);
             //...

        }
        @Test
        void findWith_when_Z() throws Exception {
             //...
             foo.findWith(...);
             //...
        }           
    }

    @Nested
    @DisplayName("findAll methods")
    class FindAllMethods {
        @Test
        void findAll_when_X() throws Exception {
             //...
             foo.findAll(...);
             //...
        }
        @Test
        void findAll_when_Y() throws Exception {
             //...
             foo.findAll(...);
             //...

        }
        @Test
        void findAll_when_Z() throws Exception {
             //...
             foo.findAll(...);
             //...
        }   
    }   

    @Nested
    @DisplayName("computeBar methods")
    class ComputeBarMethods {   
         //...

    }

    @Nested
    @DisplayName("saveOrUpdate methods")
    class SaveOrUpdateMethods { 
         //...

    }
}

Sample renderings in the IDE

Child methods of Nesteds are folded by default :

In case or test failure or on demand you can unfold child methods of Nesteds :

Vincenza

Answer 3

All my tests need a database server running. Most of my tests also need a Users table in the database, to be able to log in. In addition to that, some tests need the Friends table, to be able to login and query friends.

Each resource has a setup and teardown. I have to start and stop server, create and delete tables.

With the @Nested annotation, I can group my tests in a hierarchy of nested classes so that every test gets the setup and teardown of all tests up the hierarchy.

This idea of nesting tests was popularized in Ruby. In Java is implemented for Junit 4 by the HierarchicalContextRunner. See the justification on its page https://github.com/bechte/junit-hierarchicalcontextrunner/wiki.

Breadnut

Answer 4

It also makes it possible (using a workaround) to extract the classes to separate files but still showing them as sub-hierarchy of the top class in test views and test reports.

Make sure the extracted classes are marked abstract to avoid running them twice. See https://github.com/junit-team/junit5/issues/1750

Here is an example using Kotlin:

class MyContainerTest {
    @Nested inner class MyNestedTestsOne : MyNestedTest1()
    @Nested inner class MyNestedTestsTwo : MyNestedTest2()

    // Can also have regular unit tests
    @Test
    fun myUnitTestInContainer() { /* ... */ }
}

MyNestedTest1.kt:

abstract class MyNestedTest1 {
    @Test
    fun myUnitTestInNestedClass1() { /* ... */ }
}

MyNestedTest2.kt:

abstract class MyNestedTest2 {
    @Test
    fun myUnitTestInNestedClass2() { /* ... */ }
}

Vieira

Answer 5

@Nested - Mainly starts from Junit5, provides the continuation logic of a feature we are attempting to do. Split the business test scenarios to multiple classes, @nested is in use.

Horrified

Answer 6

Proposal of @Nested in JUnit 5

When the JUnit 5 team first considered nested tests in the early planning phases in 2015, not everyone was immediately convinced. These tests rely on nested classes, which would lead to a considerably more complex implementation than tests defined by standard nonnested classes. The team finally decided to include nested tests in the framework, because they provide a special kind of expressiveness that’s not easy to achieve by other means.

Purpose of @Nested in JUnit 5

Nested tests are well suited for all use cases where a hierarchical split of features gives a better overview than a linear split.

How to use @Nested with JUnit 5

1. While the nesting of tests via inner classes facilitates hierarchical thinking about the test structure, it is first and foremost a layout tool.

2. The simplest possibility is to reuse the setups lifecycle methods(@BeforeEach, @AfterEach) of outer class in inner class. Such lifecycle methods annotated with parameters such as may be present at every level of the containment hierarchy and are always executed for inner tests.

Example

Here is a nested test with hierarchical setup methods:

class NestedTestWithHierarchicalSetupMethods {

    String state = "";

    @BeforeEach
    void outerSetup() {
        state = state + "outer";
    }

    @Nested
    class InnerClass {

        @BeforeEach
        void innerSetup() {
            state = state + "-inner";
        }

        @Test
        void checkSetup() {
            assertEquals("outer-inner",  state);
        }
    }
}

Alternatives to @Nested without Hierarchical Structure

Although nested tests support arranging several related tests hierarchically, the two other types of mechanisms for creating several related tests without a hierarchical structure:

1. Dynamic tests
2. Parameterized tests.

References:

1. Beyond the simple: An in-depth look at JUnit 5’s nested tests, dynamic tests, parameterized tests, and extensions

Shiite