How to Disable JUnit Test Method with @Disabled Annotation

In this lesson, you will learn about the @Disabled annotation that will help you to disable the test.

Usually, it is not a good idea to disable a test. If the test is failing for some reason and you are not sure why it is failing, do not disable it. Try to figure out why it is failing and fix it. But if you do need to disable the test, there are a couple of ways to do it.

@Disabled Annotation

The best way to disable a test method is to use the @Disabled annotation. @Disabled annotation is used to tell JUnit 5 engine that the annotated test class or test method is currently disabled and should not be executed. The test method will not be executed and will be included in the test report as a disabled test.

Notice how in the below code example, the method is annotated with a @Disabled annotation. You can also use it above the class and disable all test methods in the class.

@Disabled("TODO: Still need to work on it")
@DisplayName("Division by zero")
@Test
void testIntegerDivision_WhenDividendIsDividedByZero_ShouldThrowArithmeticException() {
  
  // TODO: Still need to work on it
   
}

Another way

Another way to disable a test method is to simply comment out the @Test annotation.

 @DisplayName("Division by zero")
 // @Test
 void testIntegerDivision_WhenDividendIsDividedByZero_ShouldThrowArithmeticException() {
  // TODO: Still need to work on it
 }

If there is no test annotation, then it is not a test method. Methods that are not annotated with @Test annotation will not be executed as JUnit test methods and will not be included in the test report.

Providing a Reason for the @Disabled Annotation

JUnit 5 provides a simple and intuitive way for developers to disable certain test methods or classes temporarily. This can be achieved using the @Disabled annotation. A common reason to disable a test could be that the test is not yet implemented or that there’s a known issue causing the test to fail.

In this section, we’ll walk you through the process of providing a reason for the @Disabled annotation. JUnit 5 allows you to specify a custom message for the @Disabled annotation, which can be incredibly useful for both you and others looking at your code. This custom message will be displayed when JUnit encounters a disabled test during execution, providing a clear context of why the test was skipped.

Let’s start by understanding the basics of how to use the @Disabled annotation with a custom message. Consider the following code snippet:

@Disabled("TODO: Still need to work on it")
@DisplayName("Division by zero")
@Test
void testIntegerDivision_WhenDividendIsDividedByZero_ShouldThrowArithmeticException() { 
    // TODO: Still need to work on it 
}

In the above example, the test method testIntegerDivision_WhenDividendIsDividedByZero_ShouldThrowArithmeticException has been annotated with @Disabled. Notice the text within the parentheses of @Disabled. This is a custom message that provides the reason for disabling the test.

Here are the steps for you to follow:

  1. Annotating the Test Method: The first step is to decide which test method or test class you want to disable. Once you’ve decided, annotate that method or class with @Disabled.
  2. Providing a Reason: To provide a reason for disabling the test, you simply need to add a string in the parentheses of @Disabled. The syntax is as follows: @Disabled("Your custom message here"). The custom message should be a brief description of why the test is disabled. In the provided example, the reason is “TODO: Still need to work on it”, indicating that the test implementation is pending.
  3. Displaying the Test Name: You can use the @DisplayName annotation to provide a human-readable name for your test. This is not mandatory but is a good practice to make your tests more understandable.
  4. Disabling the Test: With the @Disabled annotation in place and a reason provided, JUnit will not execute this test method. Instead, it will display your custom message, giving a clear indication of why the test was not executed.

Remember, while the @Disabled annotation is a handy tool, it’s important to use it judiciously. Tests are disabled typically on a temporary basis, for reasons like pending bug fixes or incomplete implementation. It’s a good practice to periodically review disabled tests to ensure they get the attention they require.

This is the essence of providing a reason for the @Disabled annotation in JUnit 5. I hope that this has given you a good understanding of why and how to use this feature. Happy testing!

Frequently Asked Questions

  1. Does @Disabled disable all the test methods in a test class?
    Yes, if you annotate a test class with @Disabled, all test methods within that class will be disabled.
  2. What is the difference between @Ignore in JUnit 4 and @Disabled in JUnit 5?
    Both annotations serve the same purpose – to disable certain tests or test classes. @Ignore is used in JUnit 4, while @Disabled is used in JUnit 5.
  3. Does the @Disabled annotation work with @BeforeEach and @AfterEach annotations?
    No, the @BeforeEach and @AfterEach methods will not be run for a @Disabled test method or for test methods in a @Disabled test class.
  4. Can I use @Disabled on nested tests?
    Yes, you can use @Disabled on nested tests. If a @Nested test class is annotated with @Disabled, all tests within the nested class will be disabled.
  5. Can I use conditional expressions with @Disabled, similar to @DisabledOnOs or @DisabledIfEnvironmentVariable?
    The standard @Disabled annotation does not support conditional expressions. However, JUnit 5 offers other annotations like @DisabledOnOs, @DisabledOnJre, @DisabledIfSystemProperty, @DisabledIfEnvironmentVariable, and @DisabledIf for more granular, condition-based disabling of tests.

Video Tutorial

I hope this tutorial was helpful to you. To learn more about how to test Java code with JUnit and Mockito, please have a look at the video course below.

You can also head over to the Testing Java Code page, where you’ll discover a collection of invaluable tutorials designed to help you craft meticulously structured and optimized test cases.