HBASE-15919 Modify docs to change from @Rule to @ClassRule. Also clarify that timeout limits are on test case level. (Apekshit)
Change-Id: Ifcd0264ea147bcb1100db74d92da95b643f4793f Signed-off-by: stack <st...@apache.org> Project: http://git-wip-us.apache.org/repos/asf/hbase/repo Commit: http://git-wip-us.apache.org/repos/asf/hbase/commit/5ea2f092 Tree: http://git-wip-us.apache.org/repos/asf/hbase/tree/5ea2f092 Diff: http://git-wip-us.apache.org/repos/asf/hbase/diff/5ea2f092 Branch: refs/heads/hbase-12439 Commit: 5ea2f092332515eea48136d7d92f7b8ea72df15b Parents: 75c2360 Author: Apekshit <apeksha...@gmail.com> Authored: Tue May 31 03:30:50 2016 -0700 Committer: stack <st...@apache.org> Committed: Tue May 31 10:12:00 2016 -0700 ---------------------------------------------------------------------- src/main/asciidoc/_chapters/developer.adoc | 93 +++++++++---------------- 1 file changed, 33 insertions(+), 60 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/hbase/blob/5ea2f092/src/main/asciidoc/_chapters/developer.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/_chapters/developer.adoc b/src/main/asciidoc/_chapters/developer.adoc index a11a04e..74ce3df 100644 --- a/src/main/asciidoc/_chapters/developer.adoc +++ b/src/main/asciidoc/_chapters/developer.adoc @@ -864,7 +864,8 @@ Also, keep in mind that if you are running tests in the `hbase-server` module yo [[hbase.unittests]] === Unit Tests -Apache HBase unit tests are subdivided into four categories: small, medium, large, and integration with corresponding JUnit link:http://www.junit.org/node/581[categories]: `SmallTests`, `MediumTests`, `LargeTests`, `IntegrationTests`. +Apache HBase test cases are subdivided into four categories: small, medium, large, and +integration with corresponding JUnit link:http://www.junit.org/node/581[categories]: `SmallTests`, `MediumTests`, `LargeTests`, `IntegrationTests`. JUnit categories are denoted using java annotations and look like this in your unit test code. [source,java] @@ -879,10 +880,11 @@ public class TestHRegionInfo { } ---- -The above example shows how to mark a unit test as belonging to the `small` category. -All unit tests in HBase have a categorization. +The above example shows how to mark a test case as belonging to the `small` category. +All test cases in HBase should have a categorization. -The first three categories, `small`, `medium`, and `large`, are for tests run when you type `$ mvn test`. +The first three categories, `small`, `medium`, and `large`, are for test cases which run when you +type `$ mvn test`. In other words, these three categorizations are for HBase unit tests. The `integration` category is not for unit tests, but for integration tests. These are run when you invoke `$ mvn verify`. @@ -890,22 +892,23 @@ Integration tests are described in <<integration.tests,integration.tests>>. HBase uses a patched maven surefire plugin and maven profiles to implement its unit test characterizations. -Keep reading to figure which annotation of the set small, medium, and large to put on your new HBase unit test. +Keep reading to figure which annotation of the set small, medium, and large to put on your new +HBase test case. .Categorizing Tests Small Tests (((SmallTests))):: - _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 small test is 15 seconds, and small tests should not use a (mini)cluster. + _Small_ test cases are executed in a shared JVM and individual test cases should run in 15 seconds + or less; i.e. a link:https://en.wikipedia.org/wiki/JUnit[junit test fixture], a java object made + up of test methods, should finish in under 15 seconds. These test cases can not use mini cluster. + These are run as part of patch pre-commit. Medium Tests (((MediumTests))):: - _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. + _Medium_ test cases are executed in separate JVM and individual test case should run in 50 seconds + or less. Together, they should take less than 30 minutes, and are quite stable in their results. + These test cases can use a mini cluster. These are run as part of patch pre-commit. Large Tests (((LargeTests))):: - _Large_ tests are everything else. + _Large_ test cases are everything else. They are typically large-scale tests, 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. @@ -1049,9 +1052,7 @@ ConnectionCount=1 (was 1) * 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. +* See <<hbase.unittests,hbase.unittests> for test case categories and corresponding timeouts. This should ensure a good parallelization for people using it, and ease the analysis when the test fails. [[hbase.tests.sleeps]] @@ -1080,56 +1081,28 @@ This will allow to share the cluster later. [[hbase.tests.example.code]] ==== Tests Skeleton Code -Here is a test skeleton code with Categorization and a Category-based timeout Rule to copy and paste and use as basis for test contribution. +Here is a test skeleton code with Categorization and a Category-based timeout rule to copy and paste and use as basis for test contribution. [source,java] ---- /** - * Licensed to the Apache Software Foundation (ASF) under one - * or more contributor license agreements. See the NOTICE file - * distributed with this work for additional information - * regarding copyright ownership. The ASF licenses this file - * to you under the Apache License, Version 2.0 (the - * "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package org.apache.hadoop.hbase; - -import static org.junit.Assert.*; - -import org.apache.hadoop.hbase.testclassification.SmallTests; -import org.junit.After; -import org.junit.Before; -import org.junit.Rule; -import org.junit.Test; -import org.junit.experimental.categories.Category; -import org.junit.rules.TestName; -import org.junit.rules.TestRule; - -/** - * Skeleton HBase test + * Describe what this testcase tests. Talk about resources initialized in @BeforeClass (before + * any test is run) and before each test is run, etc. */ -// NOTICE: See how we've 'categorized' this test. All hbase unit tests need to be categorized as -// either 'small', 'medium', or 'large'. See http://hbase.apache.org/book.html#hbase.tests -// for more on these categories. +// Specify the category as explained in <<hbase.unittests,hbase.unittests>>. @Category(SmallTests.class) public class TestExample { - // Handy test rule that allows you subsequently get at the name of the current method. See - // down in 'test()' where we use it in the 'fail' message. + // Replace the TestExample.class in the below with the name of your test fixture class. + private static final Log LOG = LogFactory.getLog(TestExample.class); + + // Handy test rule that allows you subsequently get the name of the current method. See + // down in 'testExampleFoo()' where we use it to log current test's name. @Rule public TestName testName = new TestName(); - // Rather than put a @Test (timeout=.... on each test so for sure the test times out, instead - // just the CategoryBasedTimeout... It will apply to each test in this test set, the timeout - // that goes w/ the particular test categorization. - @Rule public final TestRule timeout = CategoryBasedTimeout.builder().withTimeout(this.getClass()). - withLookingForStuckThread(true).build(); + // CategoryBasedTimeout.forClass(<testcase>) decides the timeout based on the category + // (small/medium/large) of the testcase. @ClassRule requires that the full testcase runs within + // this timeout irrespective of individual test methods' times. + @ClassRule + public static TestRule timeout = CategoryBasedTimeout.forClass(TestExample.class); @Before public void setUp() throws Exception { @@ -1140,8 +1113,8 @@ public class TestExample { } @Test - public void test() { - fail(testName.getMethodName() + " is not yet implemented"); + public void testExampleFoo() { + LOG.info("Running test " + testName.getMethodName()); } } ----
