Abstract test class for
java.util.Collection
methods and contracts.
You should create a concrete subclass of this class to test any custom
Collection
implementation. At minimum, you'll have to
implement the
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
collection
field holds an instance of your collection
implementation; the
confirmed
field holds an instance of the
confirmed collection implementation. The
resetEmpty()
and
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
collection
and
confirmed
, the
verify()
method is invoked to compare
the results. You may want to override
verify()
to perform
additional verifications. For instance, when testing the collection
views of a map,
AbstractTestMap
would override
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
AbstractTestList
,
AbstractTestSet
,
or
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
Collection
fails one of these tests by design,
you may still use this base set of cases. Simply override the
test case (method) your
Collection
fails.
areEqualElementsDistinguishable
public boolean areEqualElementsDistinguishable()
Specifies whether equal elements in the collection are, in fact,
distinguishable with information not readily available. That is, if a
particular value is to be removed from the collection, then there is
one and only one value that can be removed, even if there are other
elements which are equal to it.
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.
cloneMapEntry
public Map.Entry cloneMapEntry(Map.Entry entry)
Creates a new Map Entry that is independent of the first and the map.
getFullElements
public Object[] getFullElements()
Returns an array of objects that are contained in a collection
produced by
makeFullCollection()
. Every element in the
returned array
must be an element in a full collection.
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
makeFullCollection()
, you
must override
this method to reflect the contents of a full collection.
getFullNonNullElements
public Object[] getFullNonNullElements()
Returns a list of elements suitable for return by
getFullElements()
. The array returned by this method
does not include null, but does include a variety of objects
of different types. Override getFullElements to return
the results of this method if your collection does not support
the null element.
getFullNonNullStringElements
public Object[] getFullNonNullStringElements()
Returns a list of string elements suitable for return by
getFullElements()
. Override getFullElements to return
the results of this method if your collection does not support
heterogenous elements or the null element.
getOtherElements
public Object[] getOtherElements()
Returns an array of elements that are
not contained in a
full collection. Every element in the returned array must
not exist in a collection returned by
makeFullCollection()
.
The default implementation returns a heterogenous array of elements
without null. Note that some of the tests add these elements
to an empty or full collection, so if your collection restricts
certain kinds of elements, you should override this method.
getOtherNonNullElements
public Object[] getOtherNonNullElements()
Returns the default list of objects returned by
getOtherElements()
. Includes many objects
of different types.
getOtherNonNullStringElements
public Object[] getOtherNonNullStringElements()
Returns a list of string elements suitable for return by
getOtherElements()
. Override getOtherElements to return
the results of this method if your collection does not support
heterogenous elements or the null element.
isAddSupported
public boolean isAddSupported()
Returns true if the collections produced by
makeCollection()
and
makeFullCollection()
support the
add
and
addAll
operations.
Default implementation returns true. Override if your collection
class does not support add or addAll.
isEqualsCheckable
public boolean isEqualsCheckable()
Returns true to indicate that the collection supports equals() comparisons.
This implementation returns false;
isFailFastSupported
public boolean isFailFastSupported()
Returns true to indicate that the collection supports fail fast iterators.
The default implementation returns true;
isNullSupported
public boolean isNullSupported()
Returns true to indicate that the collection supports holding null.
The default implementation returns true;
isRemoveSupported
public boolean isRemoveSupported()
Returns true if the collections produced by
makeCollection()
and
makeFullCollection()
support the
remove
,
removeAll
,
retainAll
,
clear
and
iterator().remove()
methods.
Default implementation returns true. Override if your collection
class does not support removal operations.
makeCollection
public abstract Collection makeCollection()
Return a new, empty Collection
to be used for testing.
makeConfirmedCollection
public abstract Collection makeConfirmedCollection()
Returns a confirmed empty collection.
For instance, an java.util.ArrayList
for lists or a
java.util.HashSet
for sets.
- a confirmed empty collection
makeConfirmedFullCollection
public abstract Collection makeConfirmedFullCollection()
Returns a confirmed full collection.
For instance, an
java.util.ArrayList
for lists or a
java.util.HashSet
for sets. The returned collection
should contain the elements returned by
getFullElements()
.
- a confirmed full collection
makeFullCollection
public Collection makeFullCollection()
Returns a full collection to be used for testing. The collection
returned by this method should contain every element returned by
getFullElements()
. The default implementation, in fact,
simply invokes
addAll
on an empty collection with
the results of
getFullElements()
. Override this default
if your collection doesn't support addAll.
makeObject
public Object makeObject()
Returns an empty collection for Object tests.
resetEmpty
public void resetEmpty()
Resets the
collection
and
confirmed
fields to empty
collections. Invoke this method before performing a modification
test.
resetFull
public void resetFull()
Resets the
collection
and
confirmed
fields to full
collections. Invoke this method before performing a modification
test.
testCollectionAdd
public void testCollectionAdd()
Tests Collection.add(Object)
.
testCollectionAddAll
public void testCollectionAddAll()
Tests Collection.addAll(Collection)
.
testCollectionClear
public void testCollectionClear()
Test Collection.clear()
.
testCollectionContains
public void testCollectionContains()
Tests Collection.contains(Object)
.
testCollectionContainsAll
public void testCollectionContainsAll()
Tests Collection.containsAll(Collection)
.
testCollectionIsEmpty
public void testCollectionIsEmpty()
Tests Collection.isEmpty()
.
testCollectionIterator
public void testCollectionIterator()
Tests the read-only functionality of Collection.iterator()
.
testCollectionIteratorFailFast
public void testCollectionIteratorFailFast()
Tests that the collection's iterator is fail-fast.
testCollectionIteratorRemove
public void testCollectionIteratorRemove()
Tests removals from Collection.iterator()
.
testCollectionRemove
public void testCollectionRemove()
Tests Collection.remove(Object)
.
testCollectionRemoveAll
public void testCollectionRemoveAll()
Tests Collection.removeAll(Collection)
.
testCollectionRetainAll
public void testCollectionRetainAll()
Tests Collection.retainAll(Collection)
.
testCollectionSize
public void testCollectionSize()
Tests Collection.size()
.
testCollectionToArray
public void testCollectionToArray()
Tests Collection.toArray()
.
testCollectionToArray2
public void testCollectionToArray2()
Tests Collection.toArray(Object[])
.
testCollectionToString
public void testCollectionToString()
Tests toString
on a collection.
testSerializeDeserializeThenCompare
public void testSerializeDeserializeThenCompare()
throws Exception
testUnsupportedAdd
public void testUnsupportedAdd()
If
isAddSupported()
returns false, tests that add operations
raise
UnsupportedOperationException.
testUnsupportedRemove
public void testUnsupportedRemove()
If isRemoveSupported() returns false, tests to see that remove
operations raise an UnsupportedOperationException.
verify
public void verify()