Class AbstractTestCollection
- java.lang.Object
-
- junit.framework.Assert
-
- junit.framework.TestCase
-
- org.apache.commons.collections.BulkTest
-
- org.apache.commons.collections.AbstractTestObject
-
- org.apache.commons.collections.collection.AbstractTestCollection
-
- All Implemented Interfaces:
java.lang.Cloneable
,junit.framework.Test
- Direct Known Subclasses:
AbstractTestList
,AbstractTestMap.TestMapValues
,AbstractTestSet
public abstract class AbstractTestCollection extends AbstractTestObject
Abstract test class forCollection
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 themakeCollection()
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:
isAddSupported()
isRemoveSupported()
areEqualElementsDistinguishable()
isNullSupported()
isFailFastSupported()
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 simpleequals
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; theconfirmed
field holds an instance of the confirmed collection implementation. TheresetEmpty()
andresetFull()
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
andconfirmed
, theverify()
method is invoked to compare the results. You may want to overrideverify()
to perform additional verifications. For instance, when testing the collection views of a map,AbstractTestMap
would overrideverify()
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
, orAbstractTestBag
, 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) yourCollection
fails.
-
-
Field Summary
Fields Modifier and Type Field Description java.util.Collection
collection
A collection instance that will be used for testing.java.util.Collection
confirmed
Confirmed collection.-
Fields inherited from class org.apache.commons.collections.AbstractTestObject
COLLECTIONS_MAJOR_VERSION
-
-
Constructor Summary
Constructors Constructor Description AbstractTestCollection(java.lang.String testName)
JUnit constructor.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description boolean
areEqualElementsDistinguishable()
Specifies whether equal elements in the collection are, in fact, distinguishable with information not readily available.java.util.Map.Entry
cloneMapEntry(java.util.Map.Entry entry)
Creates a new Map Entry that is independent of the first and the map.java.lang.Object[]
getFullElements()
Returns an array of objects that are contained in a collection produced bymakeFullCollection()
.java.lang.Object[]
getFullNonNullElements()
Returns a list of elements suitable for return bygetFullElements()
.java.lang.Object[]
getFullNonNullStringElements()
Returns a list of string elements suitable for return bygetFullElements()
.java.lang.Object[]
getOtherElements()
Returns an array of elements that are not contained in a full collection.java.lang.Object[]
getOtherNonNullElements()
Returns the default list of objects returned bygetOtherElements()
.java.lang.Object[]
getOtherNonNullStringElements()
Returns a list of string elements suitable for return bygetOtherElements()
.boolean
isAddSupported()
Returns true if the collections produced bymakeCollection()
andmakeFullCollection()
support theadd
andaddAll
operations.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 bymakeCollection()
andmakeFullCollection()
support theremove
,removeAll
,retainAll
,clear
anditerator().remove()
methods.abstract java.util.Collection
makeCollection()
Return a new, emptyCollection
to be used for testing.abstract java.util.Collection
makeConfirmedCollection()
Returns a confirmed empty collection.abstract java.util.Collection
makeConfirmedFullCollection()
Returns a confirmed full collection.java.util.Collection
makeFullCollection()
Returns a full collection to be used for testing.java.lang.Object
makeObject()
Returns an empty collection for Object tests.void
resetEmpty()
Resets thecollection
andconfirmed
fields to empty collections.void
resetFull()
Resets thecollection
andconfirmed
fields to full collections.void
testCollectionAdd()
TestsCollection.add(Object)
.void
testCollectionAddAll()
TestsCollection.addAll(Collection)
.void
testCollectionClear()
TestCollection.clear()
.void
testCollectionContains()
TestsCollection.contains(Object)
.void
testCollectionContainsAll()
TestsCollection.containsAll(Collection)
.void
testCollectionIsEmpty()
TestsCollection.isEmpty()
.void
testCollectionIterator()
Tests the read-only functionality ofCollection.iterator()
.void
testCollectionIteratorFailFast()
Tests that the collection's iterator is fail-fast.void
testCollectionIteratorRemove()
Tests removals fromCollection.iterator()
.void
testCollectionRemove()
TestsCollection.remove(Object)
.void
testCollectionRemoveAll()
TestsCollection.removeAll(Collection)
.void
testCollectionRetainAll()
TestsCollection.retainAll(Collection)
.void
testCollectionSize()
TestsCollection.size()
.void
testCollectionToArray()
TestsCollection.toArray()
.void
testCollectionToArray2()
TestsCollection.toArray(Object[])
.void
testCollectionToString()
TeststoString
on a collection.void
testSerializeDeserializeThenCompare()
void
testUnsupportedAdd()
IfisAddSupported()
returns false, tests that add operations raiseUnsupportedOperationException.
void
testUnsupportedRemove()
If isRemoveSupported() returns false, tests to see that remove operations raise an UnsupportedOperationException.void
verify()
Verifies thatcollection
andconfirmed
have identical state.-
Methods inherited from class org.apache.commons.collections.AbstractTestObject
getCanonicalEmptyCollectionName, getCanonicalFullCollectionName, getCompatibilityVersion, isTestSerialization, readExternalFormFromBytes, readExternalFormFromDisk, skipSerializedCanonicalTests, supportsEmptyCollections, supportsFullCollections, testCanonicalEmptyCollectionExists, testCanonicalFullCollectionExists, testEqualsNull, testObjectEqualsSelf, testObjectHashCodeEqualsContract, testObjectHashCodeEqualsSelfHashCode, testSimpleSerialization, writeExternalFormToBytes, writeExternalFormToDisk
-
Methods inherited from class org.apache.commons.collections.BulkTest
clone, ignoredTests, makeSuite, toString
-
Methods inherited from class junit.framework.TestCase
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, countTestCases, createResult, fail, fail, failNotEquals, failNotSame, failSame, format, getName, run, run, runBare, runTest, setName, setUp, tearDown
-
-
-
-
Field Detail
-
collection
public java.util.Collection collection
A collection instance that will be used for testing.
-
confirmed
public java.util.Collection confirmed
Confirmed collection. This is an instance of a collection that is confirmed to conform exactly to the java.util.Collection contract. Modification operations are tested by performing a mod on your collection, performing the exact same mod on an equivalent confirmed collection, and then calling verify() to make sure your collection still matches the confirmed collection.
-
-
Method Detail
-
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.
-
isAddSupported
public boolean isAddSupported()
Returns true if the collections produced bymakeCollection()
andmakeFullCollection()
support theadd
andaddAll
operations.Default implementation returns true. Override if your collection class does not support add or addAll.
-
isRemoveSupported
public boolean isRemoveSupported()
Returns true if the collections produced bymakeCollection()
andmakeFullCollection()
support theremove
,removeAll
,retainAll
,clear
anditerator().remove()
methods. Default implementation returns true. Override if your collection class does not support removal operations.
-
isNullSupported
public boolean isNullSupported()
Returns true to indicate that the collection supports holding null. The default implementation returns true;
-
isFailFastSupported
public boolean isFailFastSupported()
Returns true to indicate that the collection supports fail fast iterators. The default implementation returns true;
-
isEqualsCheckable
public boolean isEqualsCheckable()
Returns true to indicate that the collection supports equals() comparisons. This implementation returns false;- Overrides:
isEqualsCheckable
in classAbstractTestObject
-
verify
public void verify()
Verifies thatcollection
andconfirmed
have identical state.
-
resetEmpty
public void resetEmpty()
Resets thecollection
andconfirmed
fields to empty collections. Invoke this method before performing a modification test.
-
resetFull
public void resetFull()
Resets thecollection
andconfirmed
fields to full collections. Invoke this method before performing a modification test.
-
makeConfirmedCollection
public abstract java.util.Collection makeConfirmedCollection()
Returns a confirmed empty collection. For instance, anArrayList
for lists or aHashSet
for sets.- Returns:
- a confirmed empty collection
-
makeConfirmedFullCollection
public abstract java.util.Collection makeConfirmedFullCollection()
Returns a confirmed full collection. For instance, anArrayList
for lists or aHashSet
for sets. The returned collection should contain the elements returned bygetFullElements()
.- Returns:
- a confirmed full collection
-
makeCollection
public abstract java.util.Collection makeCollection()
Return a new, emptyCollection
to be used for testing.
-
makeFullCollection
public java.util.Collection makeFullCollection()
Returns a full collection to be used for testing. The collection returned by this method should contain every element returned bygetFullElements()
. The default implementation, in fact, simply invokesaddAll
on an empty collection with the results ofgetFullElements()
. Override this default if your collection doesn't support addAll.
-
makeObject
public java.lang.Object makeObject()
Returns an empty collection for Object tests.- Specified by:
makeObject
in classAbstractTestObject
- Returns:
- the object to test
-
cloneMapEntry
public java.util.Map.Entry cloneMapEntry(java.util.Map.Entry entry)
Creates a new Map Entry that is independent of the first and the map.
-
getFullElements
public java.lang.Object[] getFullElements()
Returns an array of objects that are contained in a collection produced bymakeFullCollection()
. 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.
-
getOtherElements
public java.lang.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 bymakeFullCollection()
. 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.
-
getFullNonNullElements
public java.lang.Object[] getFullNonNullElements()
Returns a list of elements suitable for return bygetFullElements()
. 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.
-
getOtherNonNullElements
public java.lang.Object[] getOtherNonNullElements()
Returns the default list of objects returned bygetOtherElements()
. Includes many objects of different types.
-
getFullNonNullStringElements
public java.lang.Object[] getFullNonNullStringElements()
Returns a list of string elements suitable for return bygetFullElements()
. Override getFullElements to return the results of this method if your collection does not support heterogenous elements or the null element.
-
getOtherNonNullStringElements
public java.lang.Object[] getOtherNonNullStringElements()
Returns a list of string elements suitable for return bygetOtherElements()
. Override getOtherElements to return the results of this method if your collection does not support heterogenous elements or the null element.
-
testCollectionAdd
public void testCollectionAdd()
TestsCollection.add(Object)
.
-
testCollectionAddAll
public void testCollectionAddAll()
TestsCollection.addAll(Collection)
.
-
testUnsupportedAdd
public void testUnsupportedAdd()
IfisAddSupported()
returns false, tests that add operations raiseUnsupportedOperationException.
-
testCollectionClear
public void testCollectionClear()
TestCollection.clear()
.
-
testCollectionContains
public void testCollectionContains()
TestsCollection.contains(Object)
.
-
testCollectionContainsAll
public void testCollectionContainsAll()
TestsCollection.containsAll(Collection)
.
-
testCollectionIsEmpty
public void testCollectionIsEmpty()
TestsCollection.isEmpty()
.
-
testCollectionIterator
public void testCollectionIterator()
Tests the read-only functionality ofCollection.iterator()
.
-
testCollectionIteratorRemove
public void testCollectionIteratorRemove()
Tests removals fromCollection.iterator()
.
-
testCollectionRemove
public void testCollectionRemove()
TestsCollection.remove(Object)
.
-
testCollectionRemoveAll
public void testCollectionRemoveAll()
TestsCollection.removeAll(Collection)
.
-
testCollectionRetainAll
public void testCollectionRetainAll()
TestsCollection.retainAll(Collection)
.
-
testCollectionSize
public void testCollectionSize()
TestsCollection.size()
.
-
testCollectionToArray
public void testCollectionToArray()
TestsCollection.toArray()
.
-
testCollectionToArray2
public void testCollectionToArray2()
TestsCollection.toArray(Object[])
.
-
testCollectionToString
public void testCollectionToString()
TeststoString
on a collection.
-
testUnsupportedRemove
public void testUnsupportedRemove()
If isRemoveSupported() returns false, tests to see that remove operations raise an UnsupportedOperationException.
-
testCollectionIteratorFailFast
public void testCollectionIteratorFailFast()
Tests that the collection's iterator is fail-fast.
-
testSerializeDeserializeThenCompare
public void testSerializeDeserializeThenCompare() throws java.lang.Exception
- Overrides:
testSerializeDeserializeThenCompare
in classAbstractTestObject
- Throws:
java.lang.Exception
-
-