Dear Wiki user, You have subscribed to a wiki page or wiki category on "Hadoop Wiki" for change notification.
The "HowToDevelopUnitTests" page has been changed by SteveLoughran. The comment on this change is: Added more best practises: logging, exceptions. http://wiki.apache.org/hadoop/HowToDevelopUnitTests?action=diff&rev1=2&rev2=3 -------------------------------------------------- - = How to develop unit tests = + = How to develop Hadoop Tests = - This page will be getting more details about Hadoop testing and unit test development guidelines. + This page contains Hadoop testing and test development guidelines. === Cheat sheet of tests development for JUnit v4 === - Hadoop has been using JUnit4 for awhile now, however it seems that many new tests are still being developed for JUnit v3. It is partially JUnit's fault because for the false sense of backward compatibility all v3 {{{junit.framework}}} classes are packaged along with v4 classes and it all is called {{{junit-4.5.jar}}}. Speaking of a good release management principles :-) + Hadoop has been using JUnit4 for a while now, however it seems that many new tests are still being developed for JUnit v3. It is partially JUnit's fault because for the false sense of backward compatibility all v3 {{{junit.framework}}} classes are packaged along with v4 classes and it all is called {{{junit-4.5.jar}}}. This is necessary to permit mixing of the old and new tests, and to allow the new v4 tests to run under the existing JUnit test runners in IDEs and build tools. Here's the short list of traps one need to be aware and not to develop yet another JUnit v3 test case @@ -15, +15 @@ * DO use only {{{org.junit}}} imports * DO NOT {{{extends TestCase}}} (now, you can create your own test class structures if needed!) * DO use {...@test}}} annotation to highlight what methods represent your test cases + * DO NOT put a JUnit 3.x JAR on your classpath; check in {{{ANT_HOME/lib}}} for any. If your tests don't run, this can be the cause + + Other Hadoop Test case requirements + * DO begin all your test classes with the word {{{Test}}}. This is used to select test cases to be executed. + * DO NOT give non Test classes classnames starting with the word {{{Test}}}. This confuses the test runner. + * DO give test classes methods meaningful names, ones that help people to diagnose problems from remote test runs + * DO log information that is useful to diagnose why tests failed + * DO NOT swallow or wrap exceptions, throw them from your test methods. + * AVOID looking for hard coded error strings in your test, instead have the production classes export their strings as constants, which your test methods can then reference directly. + * DO NOT assume the port numbers that Hadoop services will come up on; ask the mini clusters for the values. + * DO NOT assume the external internet is reachable. + + + == Assertions == + - * Also, any asserts your will be using need to be statically imported either one by one, i.e. + Because your test asserts your will be using need to be statically imported either one by one, i.e. {{{ import static org.junit.Assert.assertTrue; }}} @@ -24, +39 @@ import static org.junit.Assert.*; }}} - Did you find the above not to be clear enough? - Read [[http://code.google.com/p/t2framework/wiki/JUnitQuickTutorial|Quick tutorial]] right from JUnit website. + It is also possible to cheat and extend the Assert class itself + {{{ + import org.junit.Assert; + public class TestSomething extends Assert { + } + }}} + + The final tactic is half-way between JUnit 3.x and the JUnit 4 styles; the Hadoop team is yet to come down against it, though they reserve the right. + + == Logging == + + All Hadoop test cases run on a classpath which contains commons-logging; use the logging APIs just as you would in Hadoop's own codebase + + {{{ + import org.apache.commons.logging.Log; + import org.apache.commons.logging.LogFactory; + import org.junit.Test; + + public class TestSomething { + public static final Log LOG = + LogFactory.getLog(TestSomething.class); + } + }}} + + == Exception Handling in Tests == + + All test methods can declare that they throw {{{Throwable}}}. There is no need to catch exceptions and wrap them in JUnit {{{RuntimeException}}} instances. + + === Bad === + {{{ + @Test + public testCode() { + try { + doSomethingThatFails(); + catch(IOException ioe) { + fail("something went wrong"); + } + } + }}} + + === good === + {{{ + @Test + public testCode() throws Throwable { + doSomethingThatFails(); + } + }}} + + This leaves less code around (lower maintenance costs), and ensures that any failure gets reported with a full stack trace. + + == References == + + * [[http://code.google.com/p/t2framework/wiki/JUnitQuickTutorial|Quick tutorial]] on the JUnit website. +
