1 /* 2 * Copyright (C) 2007 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.collect.testing; 18 19 import com.google.common.annotations.GwtCompatible; 20 import java.util.Collections; 21 import java.util.Iterator; 22 23 /** 24 * A utility for testing an Iterator implementation by comparing its behavior to that of a "known 25 * good" reference implementation. In order to accomplish this, it's important to test a great 26 * variety of sequences of the {@link Iterator#next}, {@link Iterator#hasNext} and {@link 27 * Iterator#remove} operations. This utility takes the brute-force approach of trying <i>all</i> 28 * possible sequences of these operations, up to a given number of steps. So, if the caller 29 * specifies to use <i>n</i> steps, a total of <i>3^n</i> tests are actually performed. 30 * 31 * <p>For instance, if <i>steps</i> is 5, one example sequence that will be tested is: 32 * 33 * <ol> 34 * <li>remove(); 35 * <li>hasNext() 36 * <li>hasNext(); 37 * <li>remove(); 38 * <li>next(); 39 * </ol> 40 * 41 * <p>This particular order of operations may be unrealistic, and testing all 3^5 of them may be 42 * thought of as overkill; however, it's difficult to determine which proper subset of this massive 43 * set would be sufficient to expose any possible bug. Brute force is simpler. 44 * 45 * <p>To use this class the concrete subclass must implement the {@link 46 * IteratorTester#newTargetIterator()} method. This is because it's impossible to test an Iterator 47 * without changing its state, so the tester needs a steady supply of fresh Iterators. 48 * 49 * <p>If your iterator supports modification through {@code remove()}, you may wish to override the 50 * verify() method, which is called <em>after</em> each sequence and is guaranteed to be called 51 * using the latest values obtained from {@link IteratorTester#newTargetIterator()}. 52 * 53 * <p>The value you pass to the parameter {@code steps} should be greater than the length of your 54 * iterator, so that this class can check that your iterator behaves correctly when it is exhausted. 55 * 56 * <p>For example, to test {@link java.util.Collections#unmodifiableList(java.util.List) 57 * Collections.unmodifiableList}'s iterator: 58 * 59 * <pre>{@code 60 * List<String> expectedElements = 61 * Arrays.asList("a", "b", "c", "d", "e"); 62 * List<String> actualElements = 63 * Collections.unmodifiableList( 64 * Arrays.asList("a", "b", "c", "d", "e")); 65 * IteratorTester<String> iteratorTester = 66 * new IteratorTester<String>( 67 * 6, 68 * IteratorFeature.UNMODIFIABLE, 69 * expectedElements, 70 * IteratorTester.KnownOrder.KNOWN_ORDER) { 71 * @Override 72 * protected Iterator<String> newTargetIterator() { 73 * return actualElements.iterator(); 74 * } 75 * }; 76 * iteratorTester.test(); 77 * iteratorTester.testForEachRemaining(); 78 * }</pre> 79 * 80 * <p><b>Note</b>: It is necessary to use {@code IteratorTester.KnownOrder} as shown above, rather 81 * than {@code KnownOrder} directly, because otherwise the code cannot be compiled. 82 * 83 * @author Kevin Bourrillion 84 * @author Chris Povirk 85 */ 86 @GwtCompatible 87 public abstract class IteratorTester<E> extends AbstractIteratorTester<E, Iterator<E>> { 88 /** 89 * Creates an IteratorTester. 90 * 91 * @param steps how many operations to test for each tested pair of iterators 92 * @param features the features supported by the iterator 93 */ IteratorTester( int steps, Iterable<? extends IteratorFeature> features, Iterable<E> expectedElements, KnownOrder knownOrder)94 protected IteratorTester( 95 int steps, 96 Iterable<? extends IteratorFeature> features, 97 Iterable<E> expectedElements, 98 KnownOrder knownOrder) { 99 super(steps, Collections.<E>singleton(null), features, expectedElements, knownOrder, 0); 100 } 101 102 @Override getStimulusValues()103 protected final Iterable<Stimulus<E, Iterator<E>>> getStimulusValues() { 104 return iteratorStimuli(); 105 } 106 } 107