org.apache.commons.collections.collection
public abstract class AbstractTestCollection extends AbstractTestObject
You should create a concrete subclass of this class to test any custom {@link Collection} implementation. At minimum, you'll have to implement the {@link #makeCollection()} method. You might want to override some of the additional public methods as well:
Element Population Methods
Override these if your collection restricts what kind of elements are
allowed (for instance, if null
is not permitted):
Supported Operation Methods
Override these if your collection doesn't support certain operations:
Fixture Methods
Fixtures are used to verify that the the operation results in correct state
for the collection. Basically, the operation is performed against your
collection implementation, and an identical operation is performed against a
confirmed collection implementation. A confirmed collection
implementation is something like java.util.ArrayList
, which is
known to conform exactly to its collection interface's contract. After the
operation takes place on both your collection implementation and the
confirmed collection implementation, the two collections are compared to see
if their state is identical. The comparison is usually much more involved
than a simple equals
test. This verification is used to ensure
proper modifications are made along with ensuring that the collection does
not change when read-only modifications are made.
The {@link #collection} field holds an instance of your collection implementation; the {@link #confirmed} field holds an instance of the confirmed collection implementation. The {@link #resetEmpty()} and {@link #resetFull()} methods set these fields to empty or full collections, so that tests can proceed from a known state.
After a modification operation to both {@link #collection} and {@link #confirmed}, the {@link #verify()} method is invoked to compare the results. You may want to override {@link #verify()} to perform additional verifications. For instance, when testing the collection views of a map, {@link AbstractTestMap} would override {@link #verify()} to make sure the map is changed after the collection view is changed.
If you're extending this class directly, you will have to provide implementations for the following:
Those methods should provide a confirmed collection implementation that's compatible with your collection implementation.
If you're extending {@link AbstractTestList}, {@link AbstractTestSet}, or {@link AbstractTestBag}, you probably don't have to worry about the above methods, because those three classes already override the methods to provide standard JDK confirmed collections.
Other notes
If your {@link Collection} fails one of these tests by design, you may still use this base set of cases. Simply override the test case (method) your {@link Collection} fails.
Field Summary | |
---|---|
Collection | collection
A collection instance that will be used for testing. |
Collection | confirmed
Confirmed collection. |
Constructor Summary | |
---|---|
AbstractTestCollection(String testName)
JUnit constructor.
|
Method Summary | |
---|---|
boolean | areEqualElementsDistinguishable()
Specifies whether equal elements in the collection are, in fact,
distinguishable with information not readily available. |
Entry | cloneMapEntry(Entry entry)
Creates a new Map Entry that is independent of the first and the map. |
Object[] | getFullElements()
Returns an array of objects that are contained in a collection
produced by {@link #makeFullCollection()}. |
Object[] | getFullNonNullElements()
Returns a list of elements suitable for return by
{@link #getFullElements()}. |
Object[] | getFullNonNullStringElements()
Returns a list of string elements suitable for return by
{@link #getFullElements()}. |
Object[] | getOtherElements()
Returns an array of elements that are not contained in a
full collection. |
Object[] | getOtherNonNullElements()
Returns the default list of objects returned by
{@link #getOtherElements()}. |
Object[] | getOtherNonNullStringElements()
Returns a list of string elements suitable for return by
{@link #getOtherElements()}. |
boolean | isAddSupported()
Returns true if the collections produced by
{@link #makeCollection()} and {@link #makeFullCollection()}
support the add and addAll
operations.Default implementation returns true. |
boolean | isEqualsCheckable()
Returns true to indicate that the collection supports equals() comparisons.
|
boolean | isFailFastSupported()
Returns true to indicate that the collection supports fail fast iterators.
|
boolean | isNullSupported()
Returns true to indicate that the collection supports holding null.
|
boolean | isRemoveSupported()
Returns true if the collections produced by
{@link #makeCollection()} and {@link #makeFullCollection()}
support the remove , removeAll ,
retainAll , clear and
iterator().remove() methods.
|
abstract Collection | makeCollection()
Return a new, empty {@link Collection} to be used for testing. |
abstract Collection | makeConfirmedCollection()
Returns a confirmed empty collection.
|
abstract Collection | makeConfirmedFullCollection()
Returns a confirmed full collection.
|
Collection | makeFullCollection()
Returns a full collection to be used for testing. |
Object | makeObject()
Returns an empty collection for Object tests. |
void | resetEmpty()
Resets the {@link #collection} and {@link #confirmed} fields to empty
collections. |
void | resetFull()
Resets the {@link #collection} and {@link #confirmed} fields to full
collections. |
void | testCollectionAdd()
Tests {@link Collection#add(Object)}. |
void | testCollectionAddAll()
Tests {@link Collection#addAll(Collection)}. |
void | testCollectionClear()
Test {@link Collection#clear()}. |
void | testCollectionContains()
Tests {@link Collection#contains(Object)}. |
void | testCollectionContainsAll()
Tests {@link Collection#containsAll(Collection)}. |
void | testCollectionIsEmpty()
Tests {@link Collection#isEmpty()}. |
void | testCollectionIterator()
Tests the read-only functionality of {@link Collection#iterator()}. |
void | testCollectionIteratorFailFast()
Tests that the collection's iterator is fail-fast. |
void | testCollectionIteratorRemove()
Tests removals from {@link Collection#iterator()}. |
void | testCollectionRemove()
Tests {@link Collection#remove(Object)}. |
void | testCollectionRemoveAll()
Tests {@link Collection#removeAll(Collection)}. |
void | testCollectionRetainAll()
Tests {@link Collection#retainAll(Collection)}. |
void | testCollectionSize()
Tests {@link Collection#size()}. |
void | testCollectionToArray()
Tests {@link Collection#toArray()}. |
void | testCollectionToArray2()
Tests {@link Collection#toArray(Object[])}. |
void | testCollectionToString()
Tests toString on a collection. |
void | testSerializeDeserializeThenCompare() |
void | testUnsupportedAdd()
If {@link #isAddSupported()} returns false, tests that add operations
raise UnsupportedOperationException. |
void | testUnsupportedRemove()
If isRemoveSupported() returns false, tests to see that remove
operations raise an UnsupportedOperationException. |
void | verify()
Verifies that {@link #collection} and {@link #confirmed} have
identical state. |
Parameters: testName the test class name
In most collection cases, elements are not distinguishable (equal is equal), thus this method defaults to return false. In some cases, however, they are. For example, the collection returned from the map's values() collection view are backed by the map, so while there may be two values that are equal, their associated keys are not. Since the keys are distinguishable, the values are.
This flag is used to skip some verifications for iterator.remove() where it is impossible to perform an equivalent modification on the confirmed collection because it is not possible to determine which value in the confirmed collection to actually remove. Tests that override the default (i.e. where equal elements are distinguishable), should provide additional tests on iterator.remove() to make sure the proper elements are removed when remove() is called on the iterator.
The default implementation returns a heterogenous array of objects with some duplicates. null is added if allowed. Override if you require specific testing elements. Note that if you override {@link #makeFullCollection()}, you must override this method to reflect the contents of a full collection.
add
and addAll
operations.Default implementation returns true. Override if your collection class does not support add or addAll.
remove
, removeAll
,
retainAll
, clear
and
iterator().remove()
methods.
Default implementation returns true. Override if your collection
class does not support removal operations.Returns: a confirmed empty collection
Returns: a confirmed full collection
addAll
on an empty collection with
the results of {@link #getFullElements()}. Override this default
if your collection doesn't support addAll.toString
on a collection.UnsupportedOperationException.