001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect.testing; 018 019import com.google.common.annotations.GwtCompatible; 020import java.util.Collections; 021import java.util.Iterator; 022import org.jspecify.annotations.NullMarked; 023import org.jspecify.annotations.Nullable; 024 025/** 026 * A utility for testing an Iterator implementation by comparing its behavior to that of a "known 027 * good" reference implementation. In order to accomplish this, it's important to test a great 028 * variety of sequences of the {@link Iterator#next}, {@link Iterator#hasNext} and {@link 029 * Iterator#remove} operations. This utility takes the brute-force approach of trying <i>all</i> 030 * possible sequences of these operations, up to a given number of steps. So, if the caller 031 * specifies to use <i>n</i> steps, a total of <i>3^n</i> tests are actually performed. 032 * 033 * <p>For instance, if <i>steps</i> is 5, one example sequence that will be tested is: 034 * 035 * <ol> 036 * <li>remove(); 037 * <li>hasNext() 038 * <li>hasNext(); 039 * <li>remove(); 040 * <li>next(); 041 * </ol> 042 * 043 * <p>This particular order of operations may be unrealistic, and testing all 3^5 of them may be 044 * thought of as overkill; however, it's difficult to determine which proper subset of this massive 045 * set would be sufficient to expose any possible bug. Brute force is simpler. 046 * 047 * <p>To use this class the concrete subclass must implement the {@link 048 * IteratorTester#newTargetIterator()} method. This is because it's impossible to test an Iterator 049 * without changing its state, so the tester needs a steady supply of fresh Iterators. 050 * 051 * <p>If your iterator supports modification through {@code remove()}, you may wish to override the 052 * verify() method, which is called <em>after</em> each sequence and is guaranteed to be called 053 * using the latest values obtained from {@link IteratorTester#newTargetIterator()}. 054 * 055 * <p>The value you pass to the parameter {@code steps} should be greater than the length of your 056 * iterator, so that this class can check that your iterator behaves correctly when it is exhausted. 057 * 058 * <p>For example, to test {@link java.util.Collections#unmodifiableList(java.util.List) 059 * Collections.unmodifiableList}'s iterator: 060 * 061 * {@snippet : 062 * List<String> expectedElements = 063 * Arrays.asList("a", "b", "c", "d", "e"); 064 * List<String> actualElements = 065 * Collections.unmodifiableList( 066 * Arrays.asList("a", "b", "c", "d", "e")); 067 * IteratorTester<String> iteratorTester = 068 * new IteratorTester<String>( 069 * 6, 070 * IteratorFeature.UNMODIFIABLE, 071 * expectedElements, 072 * IteratorTester.KnownOrder.KNOWN_ORDER) { 073 * @Override 074 * protected Iterator<String> newTargetIterator() { 075 * return actualElements.iterator(); 076 * } 077 * }; 078 * iteratorTester.test(); 079 * iteratorTester.testForEachRemaining(); 080 * } 081 * 082 * <p><b>Note</b>: It is necessary to use {@code IteratorTester.KnownOrder} as shown above, rather 083 * than {@code KnownOrder} directly, because otherwise the code cannot be compiled. 084 * 085 * @author Kevin Bourrillion 086 * @author Chris Povirk 087 */ 088@GwtCompatible 089@NullMarked 090public abstract class IteratorTester<E extends @Nullable Object> 091 extends AbstractIteratorTester<E, Iterator<E>> { 092 /** 093 * Creates an IteratorTester. 094 * 095 * @param steps how many operations to test for each tested pair of iterators 096 * @param features the features supported by the iterator 097 */ 098 protected IteratorTester( 099 int steps, 100 Iterable<? extends IteratorFeature> features, 101 Iterable<E> expectedElements, 102 KnownOrder knownOrder) { 103 super(steps, Collections.<E>singleton(null), features, expectedElements, knownOrder, 0); 104 } 105 106 @Override 107 protected final Iterable<Stimulus<E, Iterator<E>>> getStimulusValues() { 108 return iteratorStimuli(); 109 } 110}