diff --git a/src/docbkx/developer.xml b/src/docbkx/developer.xml
index 7bb26293a26..a82515b5feb 100644
--- a/src/docbkx/developer.xml
+++ b/src/docbkx/developer.xml
@@ -166,6 +166,221 @@ Access restriction: The method getLong(Object, long) from the type Unsafe is not
+
+
+ Tests
+
+HBase tests are divided into two groups: and
+.
+Unit tests are run by the Apache Continuous Integration server and by developers
+when they are verifying a fix does not cause breakage elsewhere in the code base.
+Integration tests are generally long-running tests that are invoked out-of-bound of
+the CI server when you want to do more intensive testing beyond the unit test set.
+Integration tests, for example, are run proving a release candidate or a production
+deploy. Below we go into more detail on each of these test types. Developers at a
+minimum should familiarize themselves with the unit test detail; unit tests in
+HBase have a character not usually seen in other projects.
+
+
+Unit Tests
+HBase unit tests are subdivided into three categories: small, medium and large, with
+corresponding JUnit categories:
+SmallTests, MediumTests,
+LargeTests. JUnit categories are denoted using java annotations
+and look like this in your unit test code.
+...
+@Category(SmallTests.class)
+public class TestHRegionInfo {
+
+ @Test
+ public void testCreateHRegionInfoName() throws Exception {
+ // ...
+ }
+}
+The above example shows how to mark a test as belonging to the small category.
+
+
+Small tests are executed in a shared JVM. We put in this category all the tests that can
+be executed quickly in a shared JVM. The maximum execution time for a test is 15 seconds,
+and they do not use a cluster. Medium tests represent tests that must be executed
+before proposing a patch. They are designed to run in less than 30 minutes altogether,
+and are quite stable in their results. They are designed to last less than 50 seconds
+individually. They can use a cluster, and each of them is executed in a separate JVM.
+Large tests are everything else. They are typically integration-like
+tests (yes, some large tests should be moved out to be HBase ),
+regression tests for specific bugs, timeout tests, performance tests.
+They are executed before a commit on the pre-integration machines. They can be run on
+the developer machine as well.
+
+HBase uses a patched maven surefire plugin and maven profiles to implement its
+unit test characterizations.
+
+
+Running tests
+Below we describe how to run the HBase junit categories.
+
+
+Default: small and medium category tests
+
+Running mvn run will execute all small tests in a single JVM and medium tests in a separate JVM for
+each test instance. Medium tests are NOT executed if there is an error in a small test.
+Large tests are NOT executed. There is one report for small tests, and one report for
+medium tests if they are executed.
+
+
+
+
+Running all tests
+Running mvn test -P runAllTests
+will execute small tests in a single JVM then medium and large tests in a separate JVM for each test.
+Medium and large tests are NOT executed if there is an error in a small test.
+Large tests are NOT executed if there is an error in a small or medium test.
+There is one report for small tests, and one report for medium and large tests if they are executed
+
+
+
+
+Running a single test or all tests in a package
+To run an individual test, MyTest, do
+mvn test -P localTests -Dtest=MyTest You can also
+pass multiple individual tests comma-delimited: e.g.
+mvn test -P localTests -Dtest=MyTest1,MyTest2,MyTest3
+You can also pass a package and all tests under the package will be run by doing as follows:
+mvn test -P localTests -Dtest=org.apache.hadoop.hbase.client.*.
+
+
+
+The -P localTests will remove the JUnit category effect (without this specific profile,
+the profiles are taken into account). It will actually use the official release of surefire
+and the old connector (The HBase build uses a patched version of the maven surefire plugin).
+junit tests are executed in separated JVM. You will see a new message at the end of the
+report: "[INFO] Tests are skipped". It's harmless.
+
+
+
+
+Other test invocation permutations
+Running mvn test -P runSmallTests will execute small tests only, in a single JVM.
+
+Running mvn test -P runMediumTests will execute medium tests in a single JVM.
+
+Running mvn test -P runLargeTests execute medium tests in a single JVM.
+
+
+It's also possible to use the script hbasetests.sh. This script runs the medium and
+large tests in parallel with two maven instances, and provide a single report.
+It must be executed from the directory which contains the pom.xml.
+For example running
+./dev-support/hbasetests.sh will execute small and medium tests.
+Running ./dev-support/hbasetests.sh runAllTests will execute all tests.
+Running ./dev-support/hbasetests.sh replayFailed will rerun the failed tests a
+second time, in a separate jvm and without parallelisation.
+
+
+
+
+
+Writing Tests
+
+General rules
+
+
+As much as possible, tests should be written as category small tests.
+
+
+All tests must be written to support parallel execution on the same machine, hence they should not use shared resources as fixed ports or fixed file names.
+
+
+Tests should not overlog. More than 100 lines/second makes the logs complex to read and use i/o that are hence not available for the other tests.
+
+
+Tests can be written with HBaseTestingUtility.
+This class offers helper functions to create a temp directory and do the cleanup, or to start a cluster.
+Categories and execution time
+
+
+All tests must be categorized, if not they could be skipped.
+
+
+All tests should be written to be as fast as possible.
+
+
+Small category tests should last less than 15 seconds, and must not have any side effect.
+
+
+Medium category tests should last less than 50 seconds.
+
+
+Large category tests should last less than 3 minutes. This should ensure a good parallelization for people using it, and ease the analysis when the test fails.
+
+
+
+
+Sleeps in tests
+Whenever possible, tests should not use Thread.sleep, but rather waiting for the real event they need. This is faster and clearer for the reader.
+Tests should not do a Thread.sleep without testing an ending condition. This allows understanding what the test is waiting for. Moreover, the test will work whatever the machine performance is.
+Sleep should be minimal to be as fast as possible. Waiting for a variable should be done in a 40ms sleep loop. Waiting for a socket operation should be done in a 200 ms sleep loop.
+
+
+
+
+Tests using a cluster
+
+
+Tests using a HRegion do not have to start a cluster: A region can use the local file system.
+Start/stopping a cluster cost around 10 seconds. They should not be started per test method but per test class.
+Started cluster must be shutdown using HBaseTestingUtility#shutdownMiniCluster, which cleans the directories.
+As most as possible, tests should use the default settings for the cluster. When they don't, they should document it. This will allow to share the cluster later.
+
+
+
+
+
+
+Integration Tests
+HBase integration Tests are tests that are beyond HBase unit tests. They
+are generally long-lasting, sizeable (the test can be asked to 1M rows or 1B rows),
+targetable (they can take configuration that will point them at the ready-made cluster
+they are to run against; integration tests do not include cluster start/stop code),
+and verifying success, integration tests rely on public APIs only; they do not
+attempt to examine server internals asserring success/fail. Integration tests
+are what you would run when you need to more elaborate proofing of a release candidate
+beyond what unit tests can do. They are not generally run on the Apache Continuous Integration
+build server.
+
+
+Integration tests currently live under the src/test directory and
+will match the regex: **/IntegrationTest*.java.
+
+HBase 0.92 added a verify maven target.
+Invoking it, for example by doing mvn verify, will
+run all the phases up to and including the verify phase via the
+maven failsafe plugin,
+running all the above mentioned HBase unit tests as well as tests that are in the HBase integration test group.
+If you just want to run the integration tests, you need to run two commands. First:
+ mvn failsafe:integration-test.
+This actually runs ALL the integration tests.
+ This command will always output BUILD SUCCESS even if there are test failures.
+
+ At this point, you could grep the output by hand looking for failed tests. However, maven will do this for us; just use:
+ mvn failsafe:verify
+ The above command basically looks at all the test results (so don't remove the 'target' directory) for test failures and reports the results.
+
+
+ Running a subset of Integration tests
+ This is very similar to how you specify running a subset of unit tests (see above).
+To just run IntegrationTestClassXYZ.java, use:
+ mvn failsafe:integration-test -Dtest=IntegrationTestClassXYZ
+ Pretty similar, right?
+ The next thing you might want to do is run groups of integration tests, say all integration tests that are named IntegrationTestClassX*.java:
+ mvn failsafe:integration-test -Dtest=*ClassX*
+ This runs everything that is an integration test that matches *ClassX*. This means anything matching: "**/IntegrationTest*ClassX*".
+ You can also run multiple groups of integration tests using comma-delimited lists (similar to unit tests). Using a list of matches still supports full regex matching for each of the groups.This would look something like:
+ mvn failsafe:integration-test -Dtest=*ClassX*, *ClassY
+
+
+
+Maven Build Commands
@@ -179,67 +394,17 @@ Access restriction: The method getLong(Object, long) from the type Unsafe is not
mvn compile
+
- Run all Unit Tests
-
-mvn test
-
+ Running all or individual Unit Tests
+ See the section
+ above in
-
- Run a Single Unit Test
-
-mvn test -Dtest=TestXYZ
-
-
-
- Run a Few Unit Tests
-
-mvn test -Dtest=TestXYZ,TestABC
-
-
-
- Run all Unit Tests for a Package
-
-mvn test -Dtest=org.apache.hadoop.hbase.client.*
-
-
+
- Integration Tests
- HBase 0.92 added a verify maven target. Invoking it with run all the phases up to and including the verify phase via the maven failsafe plugin, running all the unit tests as well as the long running unit and integration tests.
+ Running all or individual Integration Tests
+ See
-
-mvn verify
-
- However, sometimes you will want to run just the integration tests. In that case, you need to run two commands, first:
-
-mvn failsafe:integration-test
-
- This actually runs ALL the integration tests (anything in the tests folder fitting the regex: **/IntegrationTest*.java).
- NOTE: this command will always output "BUILD SUCCESS" even if there are test failures.
- At this point, you could grep the output by hand looking for failed tests. However, maven will do this for us; just use:
-
-mvn failsafe:verify
-
- The above command basically looks at all the test results (so don't remove the 'target' directory) for test failures and reports the results.
-
-
- Running a subset of Integration tests
- This is very similar to how you specify running a subset of unit tests (see above). To just run IntegrationTestClassXYZ.java, use:
-
-mvn failsafe:integration-test -Dtest=IntegrationTestClassXYZ
-
- Pretty similar, right?
- The next thing you might want to do is run groups of integration tests, say all integration tests that are named IntegrationTestClassX*.java:
-
-
-mvn failsafe:integration-test -Dtest=*ClassX*
-
- This runs everything that is an integration test that matches *ClassX*. This means anything matching: "**/IntegrationTest*ClassX*".
- You can also run multiple groups of integration tests using comma-delimited lists (similar to unit tests). Using a list of matches still supports full regex matching for each of the groups.This would look something like:
-
-
-mvn failsafe:integration-test -Dtest=*ClassX*, *ClassY
-