Class IteratorTester<E extends @Nullable Object>

java.lang.Object

com.google.common.collect.testing.IteratorTester<E>

@GwtCompatible
@NullMarked
public abstract class IteratorTester<E extends @Nullable Object>
extends Object

A utility for testing an Iterator implementation by comparing its behavior to that of a "known good" reference implementation. In order to accomplish this, it's important to test a great variety of sequences of the Iterator.next(), Iterator.hasNext() and Iterator.remove() operations. This utility takes the brute-force approach of trying all possible sequences of these operations, up to a given number of steps. So, if the caller specifies to use n steps, a total of 3^n tests are actually performed.

For instance, if steps is 5, one example sequence that will be tested is:

1. remove();
2. hasNext()
3. hasNext();
4. remove();
5. next();

This particular order of operations may be unrealistic, and testing all 3^5 of them may be thought of as overkill; however, it's difficult to determine which proper subset of this massive set would be sufficient to expose any possible bug. Brute force is simpler.

To use this class the concrete subclass must implement the AbstractIteratorTester.newTargetIterator() method. This is because it's impossible to test an Iterator without changing its state, so the tester needs a steady supply of fresh Iterators.

If your iterator supports modification through remove(), you may wish to override the verify() method, which is called after each sequence and is guaranteed to be called using the latest values obtained from AbstractIteratorTester.newTargetIterator().

The value you pass to the parameter steps should be greater than the length of your iterator, so that this class can check that your iterator behaves correctly when it is exhausted.

For example, to test Collections.unmodifiableList's iterator:

List<String> expectedElements =
    Arrays.asList("a", "b", "c", "d", "e");
List<String> actualElements =
    Collections.unmodifiableList(
        Arrays.asList("a", "b", "c", "d", "e"));
IteratorTester<String> iteratorTester =
    new IteratorTester<String>(
        6,
        IteratorFeature.UNMODIFIABLE,
        expectedElements,
        IteratorTester.KnownOrder.KNOWN_ORDER) {
      @Override
      protected Iterator<String> newTargetIterator() {
        return actualElements.iterator();
      }
    };
iteratorTester.test();
iteratorTester.testForEachRemaining();

Note: It is necessary to use IteratorTester.KnownOrder as shown above, rather than KnownOrder directly, because otherwise the code cannot be compiled.

Author:

Kevin Bourrillion, Chris Povirk

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	IteratorTester(int steps, Iterable<? extends IteratorFeature> features, Iterable<E> expectedElements, com.google.common.collect.testing.AbstractIteratorTester.KnownOrder knownOrder)	Creates an IteratorTester.

Method Summary

Modifier and Type	Method	Description
protected final Iterable<com.google.common.collect.testing.AbstractIteratorTester.Stimulus<E, Iterator<E>>>	getStimulusValues()	I'd like to make this a parameter to the constructor, but I can't because the stimulus instances refer to this.
protected abstract Iterator<E>	newTargetIterator()	Returns a new target iterator each time it's called.
final void	test()	Executes the test.
protected void	verify(List<E> elements)	Override this to verify anything after running a list of Stimuli.

Methods inherited from class java.lang.Object

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

Constructor Details

IteratorTester

protected IteratorTester(int steps,
 Iterable<? extends IteratorFeature> features,
 Iterable<E> expectedElements,
 com.google.common.collect.testing.AbstractIteratorTester.KnownOrder knownOrder)

Creates an IteratorTester.

Parameters:

steps - how many operations to test for each tested pair of iterators

features - the features supported by the iterator

Method Details

getStimulusValues

protected final Iterable<com.google.common.collect.testing.AbstractIteratorTester.Stimulus<E, Iterator<E>>> getStimulusValues()

I'd like to make this a parameter to the constructor, but I can't because the stimulus instances refer to this.

newTargetIterator

protected abstract Iterator<E> newTargetIterator()

Returns a new target iterator each time it's called. This is the iterator you are trying to test. This must return an Iterator that returns the expected elements passed to the constructor in the given order. Warning: it is not enough to simply pull multiple iterators from the same source Iterable, unless that Iterator is unmodifiable.

verify

protected void verify(List<E> elements)

Override this to verify anything after running a list of Stimuli.

For example, verify that calls to remove() actually removed the correct elements.

Parameters:

elements - the expected elements passed to the constructor, as mutated by remove(), set(), and add() calls

test

public final void test()

Executes the test.