JUnit Notes, Do's and Don'ts

A skeleton JUnit 4 test case:

import java.util.*;
import org.junit.*;
import static org.junit.Assert.*;

public class MyTest {
/** 4 optional lifecycle callback methods */
@Before public void before() {}  //must be public void no-arg

@After public void after() {}    //must be public void no-arg

@BeforeClass public static void beforeClass() {} //must be public static void no-arg

@AfterClass public static void afterClass() {}  //must be public static void no-arg

@Test public void testAdd() {
  int a = 1, b =2, expected = 3;
  int actual = a + b;
  assertEquals(expected, actual);
}
}

Do not name your test main class Test.java, which has the same short name as @Test annotation. Unless you explicitly use @org.junit.Test, @Test will resolve to your test class, instead of org.junit.Test annotation type.

Avoid using Java assert; use static assertXXX methods (statically imported) in org.junit.Assert class. Java assert is turned off by default, and can be enabled only at command line with "java -ea", or "java -enableassertions" options. So some tests using Java assert will always pass when running with the default configuration, regardless of the actual test conditions. For example, the following method passes unless -ea option is passed to java:

@Test public void testNumber() {
  assert(1 < 0);
}

java -cp $tmp/junit-4.8.1.jar:. org.junit.runner.JUnitCore MyTest
JUnit version 4.8.1
Time: 0.009
OK (4 tests)

A secondary reason to favor org.junit.Assert.assertXXX over Java assert is, the former is a richer API with more descriptive output, whereas Java assert, in its common form, only fails with java.lang.AssertionError and stack trace with no description. Java assert can also provide details with a second param: assert false : reason

maven surefire plugin automatically enables Java assertions when running JUnit tests on JDK 1.4 and above. So when running with surefire, there is no problem of false positive test results. But still I would like my JUnit tests to work the same way across all testing environment.

Avoid using assertTrue(list1.equals(list2)); use assertEquals(list1, list2) instead. assertTrue will only print out the useless message like "expecting true, but actual false", whereas assertEquals gives more helpful message like "expected:[null, 1, 2], but was:[1, 2]"

Do not add assertTrue(true) at the end of a @Test to signal the success result. It's just not needed. The test simply passes when nothing goes wrong.

@Test method can declare throws clause, e.g., throws NamingException. When an exception is thrown during test run, the test is failed. So use exception as a means to communicate test failures. Do not try-catch an exception, just to print it and manually fail() it. For example, do this:

@Test public void testNumber() {
      int i = 10 / 0;
}

Do NOT do this:

@Test public void testNumber() {
    try {
      int i = 10 / 0;
    } catch (ArithmeticException e) {
        e.printStackTrace();
        fail();      // or even worse, assert(false);
    }
}

When running the try-catch version, ArithmeticException stack trace is printed, followed by another stack trace of java.lang.AssertionError from calling fail(), whereas in the shorter version, only the ArithmeticException is logged and hence much easier to trace.

How to run a single test? org.junit.runner.JUnitCore, the default command-line runner, takes a list of test classes as input, but doesn't support running a single test method. Other tools and IDE may support it by providing their own runner. With maven surefire 2.7.3+ and JUnit 4 tests, it is supported with a -D sysprop (link):

mvn test -Dtest=com.my.test.TestMain#test1
mvn test -Dtest=com.my.test.TestMain#*egative*
mvn org.apache.maven.plugins:maven-surefire-plugin:2.8:test -Dtest=com.my.test.TestMain#test1

I prefer to put the test name at the very end of the line so it's easier to go through the history and edit command.

To check the version of your JUnit:

$ java -cp $tmp/junit.jar junit.runner.Version
4.8.1

To skip or exclude a test, use @Ignore (org.junit.Ignore).