Class JSR166TestCase

java.lang.Object
  junit.framework.Assert
      junit.framework.TestCase
          JSR166TestCase

All Implemented Interfaces:

junit.framework.Test

Direct Known Subclasses:

AbstractExecutorServiceTest, AbstractQueuedLongSynchronizerTest, AbstractQueuedSynchronizerTest, AbstractQueueTest, ArrayBlockingQueueTest, ArrayDequeTest, AtomicBooleanTest, AtomicIntegerArrayTest, AtomicIntegerFieldUpdaterTest, AtomicIntegerTest, AtomicLongArrayTest, AtomicLongFieldUpdaterTest, AtomicLongTest, AtomicMarkableReferenceTest, AtomicReferenceArrayTest, AtomicReferenceFieldUpdaterTest, AtomicReferenceTest, AtomicStampedReferenceTest, BlockingQueueTest, ConcurrentHashMapTest, ConcurrentLinkedDequeTest, ConcurrentLinkedQueueTest, ConcurrentSkipListMapTest, ConcurrentSkipListSetTest, ConcurrentSkipListSubMapTest, ConcurrentSkipListSubSetTest, CopyOnWriteArrayListTest, CopyOnWriteArraySetTest, CountDownLatchTest, CyclicBarrierTest, DelayQueueTest, EntryTest, ExchangerTest, ExecutorCompletionServiceTest, ExecutorsTest, ForkJoinPoolTest, ForkJoinTaskTest, FutureTaskTest, LinkedBlockingDequeTest, LinkedBlockingQueueTest, LinkedListTest, LinkedTransferQueueTest, LockSupportTest, PhaserTest, PriorityBlockingQueueTest, PriorityQueueTest, RecursiveActionTest, RecursiveTaskTest, ReentrantLockTest, ReentrantReadWriteLockTest, ScheduledExecutorSubclassTest, ScheduledExecutorTest, SemaphoreTest, SynchronousQueueTest, SystemTest, ThreadLocalRandomTest, ThreadLocalTest, ThreadPoolExecutorSubclassTest, ThreadPoolExecutorTest, ThreadTest, TimeUnitTest, TreeMapTest, TreeSetTest, TreeSubMapTest, TreeSubSetTest

public class JSR166TestCase
extends junit.framework.TestCase

Base class for JSR166 Junit TCK tests. Defines some constants, utility methods and classes, as well as a simple framework for helping to make sure that assertions failing in generated threads cause the associated test that generated them to itself fail (which JUnit does not otherwise arrange). The rules for creating such tests are:

1. All assertions in code running in generated threads must use the forms threadFail(java.lang.String), threadAssertTrue(boolean), threadAssertEquals(long, long), or threadAssertNull(java.lang.Object), (not fail, assertTrue, etc.) It is OK (but not particularly recommended) for other code to use these forms too. Only the most typically used JUnit assertion methods are defined this way, but enough to live with.
2. If you override setUp() or tearDown(), make sure to invoke super.setUp and super.tearDown within them. These methods are used to clear and check for thread assertion failures.
3. All delays and timeouts must use one of the constants SHORT_DELAY_MS, SMALL_DELAY_MS, MEDIUM_DELAY_MS, LONG_DELAY_MS. The idea here is that a SHORT is always discriminable from zero time, and always allows enough time for the small amounts of computation (creating a thread, calling a few methods, etc) needed to reach a timeout point. Similarly, a SMALL is always discriminable as larger than SHORT and smaller than MEDIUM. And so on. These constants are set to conservative values, but even so, if there is ever any doubt, they can all be increased in one spot to rerun tests on slower platforms.
4. All threads generated must be joined inside each test case method (or fail to do so) before returning from the method. The joinPool method can be used to do this when using Executors.

Other notes

• Usually, there is one testcase method per JSR166 method covering "normal" operation, and then as many exception-testing methods as there are exceptions the method can throw. Sometimes there are multiple tests per JSR166 method when the different "normal" behaviors differ significantly. And sometimes testcases cover multiple methods when they cannot be tested in isolation.
• The documentation style for testcases is to provide as javadoc a simple sentence or two describing the property that the testcase method purports to test. The javadocs do not say anything about how the property is tested. To find out, read the code.
• These tests are "conformance tests", and do not attempt to test throughput, latency, scalability or other performance factors (see the separate "jtreg" tests for a set intended to check these for the most central aspects of functionality.) So, most tests use the smallest sensible numbers of threads, collection sizes, etc needed to check basic conformance.
• The test classes currently do not declare inclusion in any particular package to simplify things for people integrating them in TCK test suites.
• As a convenience, the main of this class (JSR166TestCase) runs all JSR166 unit tests.

Nested Class Summary

static class	JSR166TestCase.AdjustablePolicy A security policy where new permissions can be dynamically added or all cleared.
static class	JSR166TestCase.CallableOne
class	JSR166TestCase.CheckedBarrier A CyclicBarrier that fails with AssertionFailedErrors instead of throwing checked exceptions.
class	JSR166TestCase.CheckedCallable<T>
class	JSR166TestCase.CheckedInterruptedCallable<T>
class	JSR166TestCase.CheckedInterruptedRunnable
class	JSR166TestCase.CheckedRecursiveAction Analog of CheckedRunnable for RecursiveAction
class	JSR166TestCase.CheckedRecursiveTask<T> Analog of CheckedCallable for RecursiveTask
class	JSR166TestCase.CheckedRunnable
class	JSR166TestCase.LongPossiblyInterruptedRunnable
class	JSR166TestCase.MediumInterruptedRunnable
class	JSR166TestCase.MediumPossiblyInterruptedRunnable
class	JSR166TestCase.MediumRunnable
static class	JSR166TestCase.NoOpCallable
static class	JSR166TestCase.NoOpREHandler For use as RejectedExecutionHandler in constructors
static class	JSR166TestCase.NoOpRunnable
static class	JSR166TestCase.NPETask
class	JSR166TestCase.RunnableShouldThrow
class	JSR166TestCase.ShortInterruptedRunnable
class	JSR166TestCase.ShortRunnable
static class	JSR166TestCase.SimpleThreadFactory For use as ThreadFactory in constructors
class	JSR166TestCase.SmallCallable
class	JSR166TestCase.SmallPossiblyInterruptedRunnable
class	JSR166TestCase.SmallRunnable
static class	JSR166TestCase.StringTask
class	JSR166TestCase.ThreadShouldThrow
static class	JSR166TestCase.TrackedCallable
static class	JSR166TestCase.TrackedLongRunnable
static class	JSR166TestCase.TrackedMediumRunnable
static class	JSR166TestCase.TrackedNoOpRunnable
static interface	JSR166TestCase.TrackedRunnable
static class	JSR166TestCase.TrackedShortRunnable
static class	JSR166TestCase.TrackedSmallRunnable

Field Summary

static java.lang.Integer	eight
protected static boolean	expensiveTests
static java.lang.Integer	five
static java.lang.Integer	four
static long	LONG_DELAY_MS
static java.lang.Integer	m1
static java.lang.Integer	m10
static java.lang.Integer	m2
static java.lang.Integer	m3
static java.lang.Integer	m4
static java.lang.Integer	m5
static java.lang.Integer	m6
static long	MEDIUM_DELAY_MS
static java.lang.Integer	nine
static java.lang.Integer	one
static java.lang.Integer	seven
static long	SHORT_DELAY_MS
static java.lang.Integer	six
static int	SIZE The number of elements to place in collections, arrays, etc.
static long	SMALL_DELAY_MS
static java.lang.String	TEST_STRING
static java.lang.Integer	three
static java.lang.Integer	two
static java.lang.Integer	zero

Constructor Summary

JSR166TestCase()

Method Summary

void	assertThreadJoinTimesOut(java.lang.Thread thread, long timeoutMillis) Checks that thread does not terminate within timeoutMillis milliseconds (that is, Thread.join times out).
java.lang.Runnable	awaiter(java.util.concurrent.CountDownLatch latch)
void	checkEmpty(java.util.concurrent.BlockingQueue q)
static void	delay(long ms) Delays, via Thread.sleep for the given millisecond delay, but if the sleep is shorter than specified, may re-sleep or yield until time elapses.
protected long	getShortDelay() Returns the shortest timed delay.
void	joinPool(java.util.concurrent.ExecutorService exec) Waits out termination of a thread pool or fails doing so.
java.util.concurrent.Callable<java.lang.String>	latchAwaitingStringTask(java.util.concurrent.CountDownLatch latch)
static void	main(java.lang.String[] args) Runs all JSR166 unit tests using junit.textui.TestRunner
static junit.framework.TestSuite	newTestSuite(java.lang.Object... suiteOrClasses)
static java.security.Policy	permissivePolicy() Returns a policy containing all the permissions we ever need.
java.lang.Runnable	possiblyInterruptedRunnable(long timeoutMillis)
protected void	runTest()
protected void	runTestProfiled()
void	runWithoutPermissions(java.lang.Runnable r) Runs a runnable without any permissions.
void	runWithPermissions(java.lang.Runnable r, java.security.Permission... permissions) Runs Runnable r with a security policy that permits precisely the specified permissions.
protected void	setDelays() Sets delays as multiples of SHORT_DELAY.
void	setUp()
void	shouldThrow() Fails with message "should throw exception".
void	shouldThrow(java.lang.String exceptionName) Fails with message "should throw " + exceptionName.
static junit.framework.Test	suite() Collects all JSR166 unit tests as one suite.
void	tearDown() Triggers test case failure if any thread assertions have failed, by rethrowing, in the test harness thread, any exception recorded earlier by threadRecordFailure.
void	threadAssertEquals(long x, long y) Just like assertEquals(x, y), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.
void	threadAssertEquals(java.lang.Object x, java.lang.Object y) Just like assertEquals(x, y), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.
void	threadAssertFalse(boolean b) Just like assertFalse(b), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.
void	threadAssertNull(java.lang.Object x) Just like assertNull(x), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.
void	threadAssertSame(java.lang.Object x, java.lang.Object y) Just like assertSame(x, y), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.
void	threadAssertTrue(boolean b) Just like assertTrue(b), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.
void	threadFail(java.lang.String reason) Just like fail(reason), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.
void	threadRecordFailure(java.lang.Throwable t) Records an exception so that it can be rethrown later in the test harness thread, triggering a test case failure.
void	threadShouldThrow() Calls threadFail with message "should throw exception".
void	threadShouldThrow(java.lang.String exceptionName) Calls threadFail with message "should throw" + exceptionName.
void	threadUnexpectedException(java.lang.Throwable t) Records the given exception using threadRecordFailure(java.lang.Throwable), then rethrows the exception, wrapping it in an AssertionFailedError if necessary.
static JSR166TestCase.TrackedRunnable	trackedRunnable(long timeoutMillis)

Methods inherited from class junit.framework.TestCase

countTestCases, createResult, getName, run, run, runBare, setName, toString

Methods inherited from class junit.framework.Assert

assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, fail, fail, failNotEquals, failNotSame, failSame, format

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

expensiveTests

protected static final boolean expensiveTests

SHORT_DELAY_MS

public static long SHORT_DELAY_MS

SMALL_DELAY_MS

public static long SMALL_DELAY_MS

MEDIUM_DELAY_MS

public static long MEDIUM_DELAY_MS

LONG_DELAY_MS

public static long LONG_DELAY_MS

SIZE

public static final int SIZE

The number of elements to place in collections, arrays, etc.

See Also:

Constant Field Values

zero

public static final java.lang.Integer zero

one

public static final java.lang.Integer one

two

public static final java.lang.Integer two

three

public static final java.lang.Integer three

four

public static final java.lang.Integer four

five

public static final java.lang.Integer five

six

public static final java.lang.Integer six

seven

public static final java.lang.Integer seven

eight

public static final java.lang.Integer eight

nine

public static final java.lang.Integer nine

m1

public static final java.lang.Integer m1

m2

public static final java.lang.Integer m2

m3

public static final java.lang.Integer m3

m4

public static final java.lang.Integer m4

m5

public static final java.lang.Integer m5

m6

public static final java.lang.Integer m6

m10

public static final java.lang.Integer m10

TEST_STRING

public static final java.lang.String TEST_STRING

See Also:

Constant Field Values

Constructor Detail

JSR166TestCase

public JSR166TestCase()

Method Detail

runTest

protected void runTest()
                throws java.lang.Throwable

Overrides:

runTest in class junit.framework.TestCase

Throws:

java.lang.Throwable

runTestProfiled

protected void runTestProfiled()
                        throws java.lang.Throwable

Throws:

java.lang.Throwable

main

public static void main(java.lang.String[] args)

Runs all JSR166 unit tests using junit.textui.TestRunner

newTestSuite

public static junit.framework.TestSuite newTestSuite(java.lang.Object... suiteOrClasses)

suite

public static junit.framework.Test suite()

Collects all JSR166 unit tests as one suite.

getShortDelay

protected long getShortDelay()

Returns the shortest timed delay. This could be reimplemented to use for example a Property.

setDelays

protected void setDelays()

Sets delays as multiples of SHORT_DELAY.

threadRecordFailure

public void threadRecordFailure(java.lang.Throwable t)

Records an exception so that it can be rethrown later in the test harness thread, triggering a test case failure. Only the first failure is recorded; subsequent calls to this method from within the same test have no effect.

setUp

public void setUp()

Overrides:

setUp in class junit.framework.TestCase

tearDown

public void tearDown()
              throws java.lang.Exception

Triggers test case failure if any thread assertions have failed, by rethrowing, in the test harness thread, any exception recorded earlier by threadRecordFailure.

Overrides:

tearDown in class junit.framework.TestCase

Throws:

java.lang.Exception

threadFail

public void threadFail(java.lang.String reason)

Just like fail(reason), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.

threadAssertTrue

public void threadAssertTrue(boolean b)

Just like assertTrue(b), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.

threadAssertFalse

public void threadAssertFalse(boolean b)

Just like assertFalse(b), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.

threadAssertNull

public void threadAssertNull(java.lang.Object x)

Just like assertNull(x), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.

threadAssertEquals

public void threadAssertEquals(long x,
                               long y)

Just like assertEquals(x, y), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.

threadAssertEquals

public void threadAssertEquals(java.lang.Object x,
                               java.lang.Object y)

Just like assertEquals(x, y), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.

threadAssertSame

public void threadAssertSame(java.lang.Object x,
                             java.lang.Object y)

Just like assertSame(x, y), but additionally recording (using threadRecordFailure) any AssertionFailedError thrown, so that the current testcase will fail.

threadShouldThrow

public void threadShouldThrow()

Calls threadFail with message "should throw exception".

threadShouldThrow

public void threadShouldThrow(java.lang.String exceptionName)

Calls threadFail with message "should throw" + exceptionName.

threadUnexpectedException

public void threadUnexpectedException(java.lang.Throwable t)

Records the given exception using threadRecordFailure(java.lang.Throwable), then rethrows the exception, wrapping it in an AssertionFailedError if necessary.

delay

public static void delay(long ms)
                  throws java.lang.InterruptedException

Delays, via Thread.sleep for the given millisecond delay, but if the sleep is shorter than specified, may re-sleep or yield until time elapses.

Throws:

java.lang.InterruptedException

joinPool

public void joinPool(java.util.concurrent.ExecutorService exec)

Waits out termination of a thread pool or fails doing so.

assertThreadJoinTimesOut

public void assertThreadJoinTimesOut(java.lang.Thread thread,
                                     long timeoutMillis)

Checks that thread does not terminate within timeoutMillis milliseconds (that is, Thread.join times out).

shouldThrow

public void shouldThrow()

Fails with message "should throw exception".

shouldThrow

public void shouldThrow(java.lang.String exceptionName)

Fails with message "should throw " + exceptionName.

runWithPermissions

public void runWithPermissions(java.lang.Runnable r,
                               java.security.Permission... permissions)

Runs Runnable r with a security policy that permits precisely the specified permissions. If there is no current security manager, the runnable is run twice, both with and without a security manager. We require that any security manager permit getPolicy/setPolicy.

runWithoutPermissions

public void runWithoutPermissions(java.lang.Runnable r)

Runs a runnable without any permissions.

permissivePolicy

public static java.security.Policy permissivePolicy()

Returns a policy containing all the permissions we ever need.

latchAwaitingStringTask

public java.util.concurrent.Callable<java.lang.String> latchAwaitingStringTask(java.util.concurrent.CountDownLatch latch)

awaiter

public java.lang.Runnable awaiter(java.util.concurrent.CountDownLatch latch)

possiblyInterruptedRunnable

public java.lang.Runnable possiblyInterruptedRunnable(long timeoutMillis)

trackedRunnable

public static JSR166TestCase.TrackedRunnable trackedRunnable(long timeoutMillis)

checkEmpty

public void checkEmpty(java.util.concurrent.BlockingQueue q)