Mailing-List: contact common-commits-help@hadoop.apache.org; run by ezmlm
Precedence: bulk
Reply-To: common-dev@hadoop.apache.org
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
From: Apache Wiki <wikidiffs@apache.org>
To: Apache Wiki <wikidiffs@apache.org>
Date: Sat, 23 Jan 2010 11:05:09 -0000
Message-ID: <20100123110509.12230.52546@eos.apache.org>
Subject: 
 =?utf-8?q?=5BHadoop_Wiki=5D_Update_of_=22HowToDevelopUnitTests=22_by_Stev?=
 =?utf-8?q?eLoughran?=

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Hadoop Wiki" for ch=
ange notification.

The "HowToDevelopUnitTests" page has been changed by SteveLoughran.
The comment on this change is: Added more best practises: logging, exceptio=
ns.
http://wiki.apache.org/hadoop/HowToDevelopUnitTests?action=3Ddiff&rev1=3D2&=
rev2=3D3

--------------------------------------------------

- =3D How to develop unit tests =3D
+ =3D How to develop Hadoop Tests =3D
  =

- This page will be getting more details about Hadoop testing and unit test=
 development guidelines.
+ This page contains Hadoop testing and test development guidelines.
  =

  =3D=3D=3D Cheat sheet of tests development for JUnit v4 =3D=3D=3D
  =

- Hadoop has been using JUnit4 for awhile now, however it seems that many n=
ew tests are still being developed for JUnit v3. It is partially JUnit's fa=
ult because for the false sense of backward compatibility all v3 {{{junit.f=
ramework}}} 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 f=
ault because for the false sense of backward compatibility all v3 {{{junit.=
framework}}} classes are packaged along with v4 classes and it all is calle=
d {{{junit-4.5.jar}}}. This is necessary to permit mixing of the old and ne=
w 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 ye=
t another JUnit v3 test case
  =

@@ -15, +15 @@

     * DO use only {{{org.junit}}} imports
     * DO NOT {{{extends TestCase}}} (now, you can create your own test cla=
ss structures if needed!)
     * DO use {{{@Test}}} annotation to highlight what methods represent yo=
ur test cases
+    * DO NOT put a JUnit 3.x JAR on your classpath; check in {{{ANT_HOME/l=
ib}}} 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 use=
d to select test cases to be executed.
+    * DO NOT give non Test classes classnames starting with the word {{{Te=
st}}}. 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 hav=
e 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.
+ =

+ =

+ =3D=3D Assertions =3D=3D
+ =

-    * 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 import=
ed 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; th=
e Hadoop team is yet to come down against it, though they reserve the right.
+ =

+ =3D=3D Logging =3D=3D
+ =

+ 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 =3D
+     LogFactory.getLog(TestSomething.class);
+ }
+ }}}
+ =

+ =3D=3D Exception Handling in Tests =3D=3D
+ =

+ All test methods can declare that they throw {{{Throwable}}}. There is no=
 need to catch exceptions and wrap them in JUnit {{{RuntimeException}}} ins=
tances.
+ =

+ =3D=3D=3D Bad =3D=3D=3D
+ {{{
+ @Test
+ public testCode() {
+   try {
+     doSomethingThatFails();
+   catch(IOException ioe) {
+    fail("something went wrong");
+   }
+ }
+ }}}
+ =

+ =3D=3D=3D good =3D=3D=3D
+ {{{
+ @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.
+ =

+ =3D=3D References =3D=3D
+ =

+  * [[http://code.google.com/p/t2framework/wiki/JUnitQuickTutorial|Quick t=
utorial]] on the JUnit website.
+=20