|
1 package org.junit.runner; |
|
2 |
|
3 import java.util.Comparator; |
|
4 |
|
5 import org.junit.internal.builders.AllDefaultPossibilitiesBuilder; |
|
6 import org.junit.internal.requests.ClassRequest; |
|
7 import org.junit.internal.requests.FilterRequest; |
|
8 import org.junit.internal.requests.SortingRequest; |
|
9 import org.junit.internal.runners.ErrorReportingRunner; |
|
10 import org.junit.runner.manipulation.Filter; |
|
11 import org.junit.runners.Suite; |
|
12 import org.junit.runners.model.InitializationError; |
|
13 |
|
14 /** |
|
15 * <p>A <code>Request</code> is an abstract description of tests to be run. Older versions of |
|
16 * JUnit did not need such a concept--tests to be run were described either by classes containing |
|
17 * tests or a tree of {@link org.junit.Test}s. However, we want to support filtering and sorting, |
|
18 * so we need a more abstract specification than the tests themselves and a richer |
|
19 * specification than just the classes.</p> |
|
20 * |
|
21 * <p>The flow when JUnit runs tests is that a <code>Request</code> specifies some tests to be run -> |
|
22 * a {@link org.junit.runner.Runner} is created for each class implied by the <code>Request</code> -> |
|
23 * the {@link org.junit.runner.Runner} returns a detailed {@link org.junit.runner.Description} |
|
24 * which is a tree structure of the tests to be run.</p> |
|
25 */ |
|
26 public abstract class Request { |
|
27 /** |
|
28 * Create a <code>Request</code> that, when processed, will run a single test. |
|
29 * This is done by filtering out all other tests. This method is used to support rerunning |
|
30 * single tests. |
|
31 * @param clazz the class of the test |
|
32 * @param methodName the name of the test |
|
33 * @return a <code>Request</code> that will cause a single test be run |
|
34 */ |
|
35 public static Request method(Class<?> clazz, String methodName) { |
|
36 Description method= Description.createTestDescription(clazz, methodName); |
|
37 return Request.aClass(clazz).filterWith(method); |
|
38 } |
|
39 |
|
40 /** |
|
41 * Create a <code>Request</code> that, when processed, will run all the tests |
|
42 * in a class. The odd name is necessary because <code>class</code> is a reserved word. |
|
43 * @param clazz the class containing the tests |
|
44 * @return a <code>Request</code> that will cause all tests in the class to be run |
|
45 */ |
|
46 public static Request aClass(Class<?> clazz) { |
|
47 return new ClassRequest(clazz); |
|
48 } |
|
49 |
|
50 /** |
|
51 * Create a <code>Request</code> that, when processed, will run all the tests |
|
52 * in a class. If the class has a suite() method, it will be ignored. |
|
53 * @param clazz the class containing the tests |
|
54 * @return a <code>Request</code> that will cause all tests in the class to be run |
|
55 */ |
|
56 public static Request classWithoutSuiteMethod(Class<?> clazz) { |
|
57 return new ClassRequest(clazz, false); |
|
58 } |
|
59 |
|
60 /** |
|
61 * Create a <code>Request</code> that, when processed, will run all the tests |
|
62 * in a set of classes. |
|
63 * @param classes the classes containing the tests |
|
64 * @return a <code>Request</code> that will cause all tests in the classes to be run |
|
65 */ |
|
66 public static Request classes(Class<?>... classes) { |
|
67 try { |
|
68 return runner(new Suite(new AllDefaultPossibilitiesBuilder(true), classes)); |
|
69 } catch (InitializationError e) { |
|
70 throw new RuntimeException( |
|
71 "Bug in saff's brain: Suite constructor, called as above, should always complete"); |
|
72 } |
|
73 } |
|
74 |
|
75 /** |
|
76 * Not used within JUnit. Clients should simply instantiate ErrorReportingRunner themselves |
|
77 */ |
|
78 @Deprecated |
|
79 public static Request errorReport(Class<?> klass, Throwable cause) { |
|
80 return runner(new ErrorReportingRunner(klass, cause)); |
|
81 } |
|
82 |
|
83 /** |
|
84 * @param runner the runner to return |
|
85 * @return a <code>Request</code> that will run the given runner when invoked |
|
86 */ |
|
87 public static Request runner(final Runner runner) { |
|
88 return new Request(){ |
|
89 @Override |
|
90 public Runner getRunner() { |
|
91 return runner; |
|
92 } |
|
93 }; |
|
94 } |
|
95 |
|
96 /** |
|
97 * Returns a {@link Runner} for this Request |
|
98 * @return corresponding {@link Runner} for this Request |
|
99 */ |
|
100 public abstract Runner getRunner(); |
|
101 |
|
102 /** |
|
103 * Returns a Request that only contains those tests that should run when |
|
104 * <code>filter</code> is applied |
|
105 * @param filter The {@link Filter} to apply to this Request |
|
106 * @return the filtered Request |
|
107 */ |
|
108 public Request filterWith(Filter filter) { |
|
109 return new FilterRequest(this, filter); |
|
110 } |
|
111 |
|
112 /** |
|
113 * Returns a Request that only runs contains tests whose {@link Description} |
|
114 * equals <code>desiredDescription</code> |
|
115 * @param desiredDescription {@link Description} of those tests that should be run |
|
116 * @return the filtered Request |
|
117 */ |
|
118 public Request filterWith(final Description desiredDescription) { |
|
119 return filterWith(new Filter() { |
|
120 @Override |
|
121 public boolean shouldRun(Description description) { |
|
122 if (description.isTest()) |
|
123 return desiredDescription.equals(description); |
|
124 |
|
125 // explicitly check if any children want to run |
|
126 for (Description each : description.getChildren()) |
|
127 if (shouldRun(each)) |
|
128 return true; |
|
129 return false; |
|
130 } |
|
131 |
|
132 @Override |
|
133 public String describe() { |
|
134 return String.format("Method %s", desiredDescription.getDisplayName()); |
|
135 } |
|
136 }); |
|
137 } |
|
138 |
|
139 /** |
|
140 * Returns a Request whose Tests can be run in a certain order, defined by |
|
141 * <code>comparator</code> |
|
142 * |
|
143 * For example, here is code to run a test suite in alphabetical order: |
|
144 * |
|
145 * <pre> |
|
146 private static Comparator<Description> forward() { |
|
147 return new Comparator<Description>() { |
|
148 public int compare(Description o1, Description o2) { |
|
149 return o1.getDisplayName().compareTo(o2.getDisplayName()); |
|
150 } |
|
151 }; |
|
152 } |
|
153 |
|
154 public static main() { |
|
155 new JUnitCore().run(Request.aClass(AllTests.class).sortWith(forward())); |
|
156 } |
|
157 * </pre> |
|
158 * |
|
159 * @param comparator definition of the order of the tests in this Request |
|
160 * @return a Request with ordered Tests |
|
161 */ |
|
162 public Request sortWith(Comparator<Description> comparator) { |
|
163 return new SortingRequest(this, comparator); |
|
164 } |
|
165 } |