Apache
/
hbase
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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 <stack@apache.org>
This commit is contained in:
Apekshit 2016-05-31 03:30:50 -07:00 committed by stack
parent 75c2360543
commit 5ea2f09233
1 changed files with 33 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
src/main/asciidoc/_chapters/developer.adoc
View File

@ -864,7 +864,8 @@ Also, keep in mind that if you are running tests in the `hbase-server` module yo
[[hbase.unittests]] [[hbase.unittests]]
=== Unit Tests === 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. JUnit categories are denoted using java annotations and look like this in your unit test code.
[source,java] [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. The above example shows how to mark a test case as belonging to the `small` category.
All unit tests in HBase have a categorization. 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. In other words, these three categorizations are for HBase unit tests.
The `integration` category is not for unit tests, but for integration tests. The `integration` category is not for unit tests, but for integration tests.
These are run when you invoke `$ mvn verify`. 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. 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 .Categorizing Tests
Small Tests (((SmallTests))):: Small Tests (((SmallTests)))::
_Small_ tests are executed in a shared JVM. _Small_ test cases are executed in a shared JVM and individual test cases should run in 15 seconds
We put in this category all the tests that can be executed quickly in a shared JVM. or less; i.e. a link:https://en.wikipedia.org/wiki/JUnit[junit test fixture], a java object made
The maximum execution time for a small test is 15 seconds, and small tests should not use a (mini)cluster. 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 (((MediumTests)))::
_Medium_ tests represent tests that must be executed before proposing a patch. _Medium_ test cases are executed in separate JVM and individual test case should run in 50 seconds
They are designed to run in less than 30 minutes altogether, and are quite stable in their results. or less. Together, they should take less than 30 minutes, and are quite stable in their results.
They are designed to last less than 50 seconds individually. These test cases can use a mini cluster. These are run as part of patch pre-commit.
They can use a cluster, and each of them is executed in a separate JVM.
Large Tests (((LargeTests))):: 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 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 are executed before a commit on the pre-integration machines.
They can be run on the developer machine as well. 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 must be categorized, if not they could be skipped.
* All tests should be written to be as fast as possible. * 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. * See <<hbase.unittests,hbase.unittests> for test case categories and corresponding timeouts.
* 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. This should ensure a good parallelization for people using it, and ease the analysis when the test fails.
[[hbase.tests.sleeps]] [[hbase.tests.sleeps]]
@ -1080,56 +1081,28 @@ This will allow to share the cluster later.
[[hbase.tests.example.code]] [[hbase.tests.example.code]]
==== Tests Skeleton 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] [source,java]
---- ----
/** /**
* Licensed to the Apache Software Foundation (ASF) under one * Describe what this testcase tests. Talk about resources initialized in @BeforeClass (before
* or more contributor license agreements. See the NOTICE file * any test is run) and before each test is run, etc.
* 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; // Specify the category as explained in <<hbase.unittests,hbase.unittests>>.
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
*/
// 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.
@Category(SmallTests.class) @Category(SmallTests.class)
public class TestExample { public class TestExample {
// Handy test rule that allows you subsequently get at the name of the current method. See // Replace the TestExample.class in the below with the name of your test fixture class.
// down in 'test()' where we use it in the 'fail' message. 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(); @Rule public TestName testName = new TestName();
// Rather than put a @Test (timeout=.... on each test so for sure the test times out, instead // CategoryBasedTimeout.forClass(<testcase>) decides the timeout based on the category
// just the CategoryBasedTimeout... It will apply to each test in this test set, the timeout // (small/medium/large) of the testcase. @ClassRule requires that the full testcase runs within
// that goes w/ the particular test categorization. // this timeout irrespective of individual test methods' times.
@Rule public final TestRule timeout = CategoryBasedTimeout.builder().withTimeout(this.getClass()). @ClassRule
withLookingForStuckThread(true).build(); public static TestRule timeout = CategoryBasedTimeout.forClass(TestExample.class);
@Before @Before
public void setUp() throws Exception { public void setUp() throws Exception {
@ -1140,8 +1113,8 @@ public class TestExample {
} }
@Test @Test
public void test() { public void testExampleFoo() {
fail(testName.getMethodName() + " is not yet implemented"); LOG.info("Running test " + testName.getMethodName());
} }
} }
---- ----