View Javadoc
1   /*
2    * Copyright (C) 2008 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 static java.util.Collections.disjoint;
20  import static java.util.logging.Level.FINER;
21  
22  import com.google.common.annotations.GwtIncompatible;
23  import com.google.common.collect.testing.features.ConflictingRequirementsException;
24  import com.google.common.collect.testing.features.Feature;
25  import com.google.common.collect.testing.features.FeatureUtil;
26  import com.google.common.collect.testing.features.TesterRequirements;
27  import java.lang.reflect.Method;
28  import java.util.ArrayList;
29  import java.util.Arrays;
30  import java.util.Collection;
31  import java.util.Collections;
32  import java.util.Enumeration;
33  import java.util.HashSet;
34  import java.util.LinkedHashSet;
35  import java.util.List;
36  import java.util.Set;
37  import java.util.logging.Logger;
38  import junit.framework.Test;
39  import junit.framework.TestCase;
40  import junit.framework.TestSuite;
41  
42  /**
43   * Creates, based on your criteria, a JUnit test suite that exhaustively tests
44   * the object generated by a G, selecting appropriate tests by matching them
45   * against specified features.
46   *
47   * @param <B> The concrete type of this builder (the 'self-type'). All the
48   * Builder methods of this class (such as {@link #named}) return this type, so
49   * that Builder methods of more derived classes can be chained onto them without
50   * casting.
51   * @param <G> The type of the generator to be passed to testers in the
52   * generated test suite. An instance of G should somehow provide an
53   * instance of the class under test, plus any other information required
54   * to parameterize the test.
55   *
56   * @author George van den Driessche
57   */
58  @GwtIncompatible
59  public abstract class FeatureSpecificTestSuiteBuilder<
60      B extends FeatureSpecificTestSuiteBuilder<B, G>, G> {
61    @SuppressWarnings("unchecked")
62    protected B self() {
63      return (B) this;
64    }
65  
66    // Test Data
67  
68    private G subjectGenerator;
69    // Gets run before every test.
70    private Runnable setUp;
71    // Gets run at the conclusion of every test.
72    private Runnable tearDown;
73  
74    protected B usingGenerator(G subjectGenerator) {
75      this.subjectGenerator = subjectGenerator;
76      return self();
77    }
78  
79    public G getSubjectGenerator() {
80      return subjectGenerator;
81    }
82  
83    public B withSetUp(Runnable setUp) {
84      this.setUp = setUp;
85      return self();
86    }
87  
88    protected Runnable getSetUp() {
89      return setUp;
90    }
91  
92    public B withTearDown(Runnable tearDown) {
93      this.tearDown = tearDown;
94      return self();
95    }
96  
97    protected Runnable getTearDown() {
98      return tearDown;
99    }
100 
101   // Features
102 
103   private Set<Feature<?>> features = new LinkedHashSet<>();
104 
105   /**
106    * Configures this builder to produce tests appropriate for the given
107    * features.  This method may be called more than once to add features
108    * in multiple groups.
109    */
110   public B withFeatures(Feature<?>... features) {
111     return withFeatures(Arrays.asList(features));
112   }
113 
114   public B withFeatures(Iterable<? extends Feature<?>> features) {
115     for (Feature<?> feature : features) {
116       this.features.add(feature);
117     }
118     return self();
119   }
120 
121   public Set<Feature<?>> getFeatures() {
122     return Collections.unmodifiableSet(features);
123   }
124 
125   // Name
126 
127   private String name;
128 
129   /** Configures this builder produce a TestSuite with the given name. */
130   public B named(String name) {
131     if (name.contains("(")) {
132       throw new IllegalArgumentException(
133           "Eclipse hides all characters after "
134               + "'('; please use '[]' or other characters instead of parentheses");
135     }
136     this.name = name;
137     return self();
138   }
139 
140   public String getName() {
141     return name;
142   }
143 
144   // Test suppression
145 
146   private Set<Method> suppressedTests = new HashSet<>();
147 
148   /**
149    * Prevents the given methods from being run as part of the test suite.
150    *
151    * <em>Note:</em> in principle this should never need to be used, but it
152    * might be useful if the semantics of an implementation disagree in
153    * unforeseen ways with the semantics expected by a test, or to keep dependent
154    * builds clean in spite of an erroneous test.
155    */
156   public B suppressing(Method... methods) {
157     return suppressing(Arrays.asList(methods));
158   }
159 
160   public B suppressing(Collection<Method> methods) {
161     suppressedTests.addAll(methods);
162     return self();
163   }
164 
165   public Set<Method> getSuppressedTests() {
166     return suppressedTests;
167   }
168 
169   private static final Logger logger =
170       Logger.getLogger(FeatureSpecificTestSuiteBuilder.class.getName());
171 
172   /**
173    * Creates a runnable JUnit test suite based on the criteria already given.
174    */
175   /*
176    * Class parameters must be raw. This annotation should go on testerClass in
177    * the for loop, but the 1.5 javac crashes on annotations in for loops:
178    * <http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6294589>;
179    */
180   @SuppressWarnings("unchecked")
181   public TestSuite createTestSuite() {
182     checkCanCreate();
183 
184     logger.fine(" Testing: " + name);
185     logger.fine("Features: " + formatFeatureSet(features));
186 
187     FeatureUtil.addImpliedFeatures(features);
188 
189     logger.fine("Expanded: " + formatFeatureSet(features));
190 
191     // Class parameters must be raw.
192     List<Class<? extends AbstractTester>> testers = getTesters();
193 
194     TestSuite suite = new TestSuite(name);
195     for (Class<? extends AbstractTester> testerClass : testers) {
196       final TestSuite testerSuite =
197           makeSuiteForTesterClass((Class<? extends AbstractTester<?>>) testerClass);
198       if (testerSuite.countTestCases() > 0) {
199         suite.addTest(testerSuite);
200       }
201     }
202     return suite;
203   }
204 
205   /**
206    * Throw {@link IllegalStateException} if {@link #createTestSuite()} can't
207    * be called yet.
208    */
209   protected void checkCanCreate() {
210     if (subjectGenerator == null) {
211       throw new IllegalStateException("Call using() before createTestSuite().");
212     }
213     if (name == null) {
214       throw new IllegalStateException("Call named() before createTestSuite().");
215     }
216     if (features == null) {
217       throw new IllegalStateException("Call withFeatures() before createTestSuite().");
218     }
219   }
220 
221   // Class parameters must be raw.
222   protected abstract List<Class<? extends AbstractTester>> getTesters();
223 
224   private boolean matches(Test test) {
225     final Method method;
226     try {
227       method = extractMethod(test);
228     } catch (IllegalArgumentException e) {
229       logger.finer(Platform.format("%s: including by default: %s", test, e.getMessage()));
230       return true;
231     }
232     if (suppressedTests.contains(method)) {
233       logger.finer(Platform.format("%s: excluding because it was explicitly suppressed.", test));
234       return false;
235     }
236     final TesterRequirements requirements;
237     try {
238       requirements = FeatureUtil.getTesterRequirements(method);
239     } catch (ConflictingRequirementsException e) {
240       throw new RuntimeException(e);
241     }
242     if (!features.containsAll(requirements.getPresentFeatures())) {
243       if (logger.isLoggable(FINER)) {
244         Set<Feature<?>> missingFeatures = Helpers.copyToSet(requirements.getPresentFeatures());
245         missingFeatures.removeAll(features);
246         logger.finer(
247             Platform.format(
248                 "%s: skipping because these features are absent: %s", method, missingFeatures));
249       }
250       return false;
251     }
252     if (intersect(features, requirements.getAbsentFeatures())) {
253       if (logger.isLoggable(FINER)) {
254         Set<Feature<?>> unwantedFeatures = Helpers.copyToSet(requirements.getAbsentFeatures());
255         unwantedFeatures.retainAll(features);
256         logger.finer(
257             Platform.format(
258                 "%s: skipping because these features are present: %s", method, unwantedFeatures));
259       }
260       return false;
261     }
262     return true;
263   }
264 
265   private static boolean intersect(Set<?> a, Set<?> b) {
266     return !disjoint(a, b);
267   }
268 
269   private static Method extractMethod(Test test) {
270     if (test instanceof AbstractTester) {
271       AbstractTester<?> tester = (AbstractTester<?>) test;
272       return Helpers.getMethod(tester.getClass(), tester.getTestMethodName());
273     } else if (test instanceof TestCase) {
274       TestCase testCase = (TestCase) test;
275       return Helpers.getMethod(testCase.getClass(), testCase.getName());
276     } else {
277       throw new IllegalArgumentException("unable to extract method from test: not a TestCase.");
278     }
279   }
280 
281   protected TestSuite makeSuiteForTesterClass(Class<? extends AbstractTester<?>> testerClass) {
282     final TestSuite candidateTests = new TestSuite(testerClass);
283     final TestSuite suite = filterSuite(candidateTests);
284 
285     Enumeration<?> allTests = suite.tests();
286     while (allTests.hasMoreElements()) {
287       Object test = allTests.nextElement();
288       if (test instanceof AbstractTester) {
289         @SuppressWarnings("unchecked")
290         AbstractTester<? super G> tester = (AbstractTester<? super G>) test;
291         tester.init(subjectGenerator, name, setUp, tearDown);
292       }
293     }
294 
295     return suite;
296   }
297 
298   private TestSuite filterSuite(TestSuite suite) {
299     TestSuite filtered = new TestSuite(suite.getName());
300     final Enumeration<?> tests = suite.tests();
301     while (tests.hasMoreElements()) {
302       Test test = (Test) tests.nextElement();
303       if (matches(test)) {
304         filtered.addTest(test);
305       }
306     }
307     return filtered;
308   }
309 
310   protected static String formatFeatureSet(Set<? extends Feature<?>> features) {
311     List<String> temp = new ArrayList<>();
312     for (Feature<?> feature : features) {
313       Object featureAsObject = feature; // to work around bogus JDK warning
314       if (featureAsObject instanceof Enum) {
315         Enum<?> f = (Enum<?>) featureAsObject;
316         temp.add(f.getDeclaringClass().getSimpleName() + "." + feature);
317       } else {
318         temp.add(feature.toString());
319       }
320     }
321     return temp.toString();
322   }
323 }