Debian Codegraph @

guava-testlib/src/com/google/common/collect/testing/FeatureSpecificTestSuiteBuilder.java

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