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)

Browse Source 
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]]
=== 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.
* Describe what this testcase tests. Talk about resources initialized in @BeforeClass (before
* any test is run) and before each test is run, etc.
*/
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
*/
// 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());
}
}
----