/* * Copyright (C) 2007 The Guava Authors * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.google.common.collect.testing; import com.google.common.annotations.GwtCompatible; import java.util.Collections; import java.util.Iterator; /** * 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 * {@link Iterator#next}, {@link Iterator#hasNext} and {@link 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 * {@link IteratorTester#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 {@code 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 {@link IteratorTester#newTargetIterator()}. * * @author Kevin Bourrillion * @author Chris Povirk */ @GwtCompatible public abstract class IteratorTester extends AbstractIteratorTester> { /** * Creates an IteratorTester. * * @param steps how many operations to test for each tested pair of iterators * @param features the features supported by the iterator */ protected IteratorTester(int steps, Iterable features, Iterable expectedElements, KnownOrder knownOrder) { super(steps, Collections.singleton(null), features, expectedElements, knownOrder, 0); } @Override protected final Iterable>> getStimulusValues() { return iteratorStimuli(); } }