JUnit - Assuming conditions with org.junit.Assume

[Last Updated: May 4, 2017]

The JUnit class Assume can be used to establish an assumption about the condition in which a test should be run. The default JUnit runner ignores the test execution on failing the assumption. Custom runners may behave differently. With default runner, it's a way to ignore the tests programmatically. In following examples, we are going go through each method of Assume with default runner.

Using Assume#assumeTrue()

The test execution will stop and be ignored if the provided expression is false:

public class MyTest {

  @Test
  public void testMethod1() {
      Assume.assumeTrue("applicable time zone assumption",
              ZoneId.systemDefault().getId().equals("America/New_York"));
      System.out.println("assumption passed");
      System.out.println("test continues");
  }
    .............
}

mvn -q test -Dtest=MyTest#testMethod1

Output

d:\example-projects\junit\junit-assume-examples>mvn -q test -Dtest=MyTest#testMethod1

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.logicbig.example.MyTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 1, Time elapsed: 0.047 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 1

Note that each method of Assume has an overloaded variant without first parameter (the message).

In above example the assumption failed because the system time zone is not the specified one. In case assumption fails, JUnit doesn't execute next lines. JUnits does that by throwing AssumptionViolatedException, which is internally handled by the test caller (the runner).

In above example, what happens if assumption passes. Let's check that with reversed assumption:

public class MyTest {
    .............
  @Test
  public void testMethod2() {
      Assume.assumeTrue("not applicable time zone assumption",
              !ZoneId.systemDefault().getId().equals("America/New_York"));
      System.out.println("assumption passed");
      System.out.println("test continues");
  }
    .............
}

mvn -q test -Dtest=MyTest#testMethod2

Output

d:\example-projects\junit\junit-assume-examples>mvn -q test -Dtest=MyTest#testMethod2

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.logicbig.example.MyTest
assumption passed
test continues
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.047 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Assumption passes and test continues this time.

Note that there's another similar method Assert#assumeFalse() which does the opposite.

Assume#assumeNoException

It is used to assume that an operation completes normally without the specified exception. It's a way to force ignoring a test in a catch block:

public class MyTest {
    .............
  @Test
  public void testMethod3() {
      System.out.println("test starts");
      try {
          int i = 1 / 0;
          System.out.println(i);
      } catch (ArithmeticException e) {
          Assume.assumeNoException("No ArithmeticException assumption", e);
      }

      System.out.println("test continues");
  }
    .............
}

mvn -q test -Dtest=MyTest#testMethod3

Output

d:\example-projects\junit\junit-assume-examples>mvn -q test -Dtest=MyTest#testMethod3

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.logicbig.example.MyTest
test starts
Tests run: 1, Failures: 0, Errors: 0, Skipped: 1, Time elapsed: 0.036 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 1

The test is not executed further after exception is thrown and assumption fails in catch block. In above example, let's not throw the exception and see the output:

public class MyTest {
    .............
  @Test
  public void testMethod4() {
      System.out.println("test starts");
      try {
          int i = 1 / 2;
          System.out.println("i: " + i);
      } catch (ArithmeticException e) {
          Assume.assumeNoException("No ArithmeticException assumption", e);
      }

      System.out.println("test continues");
  }
    .............
}

mvn -q test -Dtest=MyTest#testMethod4

Output

d:\example-projects\junit\junit-assume-examples>mvn -q test -Dtest=MyTest#testMethod4

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.logicbig.example.MyTest
test starts
i: 0
test continues
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.032 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Using Assume#assumeThat

static <T> void assumeThat(String message,
                           T actual,
                           org.hamcrest.Matcher<T> matcher)

This method assumes that first argument (actual) satisfies the condition specified by matcher. If not, the test halts and is ignored.

public class MyTest {
    .............
  @Test
  public void testMethod5() {
      System.out.println("test starts");
      int x = 1;
      Assume.assumeThat("x being 10 assumption", x, CoreMatchers.is(10));
      System.out.println("test continues");
  }
    .............
}

mvn -q test -Dtest=MyTest#testMethod5

Output

d:\example-projects\junit\junit-assume-examples>mvn -q test -Dtest=MyTest#testMethod5

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.logicbig.example.MyTest
test starts
Tests run: 1, Failures: 0, Errors: 0, Skipped: 1, Time elapsed: 0.036 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 1

Let's change the value of x = 10, in that case assumption will pass and test will continue:

public class MyTest {
    .............
  @Test
  public void testMethod6() {
      System.out.println("test starts");
      int x = 10;
      Assume.assumeThat("x being 10 assumption", x, CoreMatchers.is(10));
      System.out.println("test continues");
  }
    .............
}

mvn -q test -Dtest=MyTest#testMethod6

Output

d:\example-projects\junit\junit-assume-examples>mvn -q test -Dtest=MyTest#testMethod6

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.logicbig.example.MyTest
test starts
test continues
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.036 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Using Assume#assumeNotNull

It is used with one or more objects, the test will halt and be ignored if any of them is null.

public class MyTest {
    .............
  @Test
  public void testMethod7() {
      System.out.println("test starts");
      String s = "s value";
      String t = null;
      Assume.assumeNotNull(s, t);
      System.out.println("test continues");
  }
    .............
}

mvn -q test -Dtest=MyTest#testMethod7

Output

d:\example-projects\junit\junit-assume-examples>mvn -q test -Dtest=MyTest#testMethod7

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.logicbig.example.MyTest
test starts
Tests run: 1, Failures: 0, Errors: 0, Skipped: 1, Time elapsed: 0.04 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 1

Let's make none of them being null:

public class MyTest {
    .............
  @Test
  public void testMethod8() {
      System.out.println("test starts");
      String s = "s value";
      String t = "t value";
      Assume.assumeNotNull(s, t);
      System.out.println("test continues");
  }
}

mvn -q test -Dtest=MyTest#testMethod8

Output

d:\example-projects\junit\junit-assume-examples>mvn -q test -Dtest=MyTest#testMethod8

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running com.logicbig.example.MyTest
test starts
test continues
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.038 sec

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0