001    package org.junit.runner;
002    
003    import java.io.Serializable;
004    import java.lang.annotation.Annotation;
005    import java.util.ArrayList;
006    import java.util.Arrays;
007    import java.util.Collection;
008    import java.util.concurrent.ConcurrentLinkedQueue;
009    import java.util.regex.Matcher;
010    import java.util.regex.Pattern;
011    
012    /**
013     * A <code>Description</code> describes a test which is to be run or has been run. <code>Descriptions</code>
014     * can be atomic (a single test) or compound (containing children tests). <code>Descriptions</code> are used
015     * to provide feedback about the tests that are about to run (for example, the tree view
016     * visible in many IDEs) or tests that have been run (for example, the failures view).
017     * <p>
018     * <code>Descriptions</code> are implemented as a single class rather than a Composite because
019     * they are entirely informational. They contain no logic aside from counting their tests.
020     * <p>
021     * In the past, we used the raw {@link junit.framework.TestCase}s and {@link junit.framework.TestSuite}s
022     * to display the tree of tests. This was no longer viable in JUnit 4 because atomic tests no longer have
023     * a superclass below {@link Object}. We needed a way to pass a class and name together. Description
024     * emerged from this.
025     *
026     * @see org.junit.runner.Request
027     * @see org.junit.runner.Runner
028     * @since 4.0
029     */
030    public class Description implements Serializable {
031        private static final long serialVersionUID = 1L;
032    
033        private static final Pattern METHOD_AND_CLASS_NAME_PATTERN = Pattern
034                .compile("([\\s\\S]*)\\((.*)\\)");
035    
036        /**
037         * Create a <code>Description</code> named <code>name</code>.
038         * Generally, you will add children to this <code>Description</code>.
039         *
040         * @param name the name of the <code>Description</code>
041         * @param annotations meta-data about the test, for downstream interpreters
042         * @return a <code>Description</code> named <code>name</code>
043         */
044        public static Description createSuiteDescription(String name, Annotation... annotations) {
045            return new Description(null, name, annotations);
046        }
047    
048        /**
049         * Create a <code>Description</code> named <code>name</code>.
050         * Generally, you will add children to this <code>Description</code>.
051         *
052         * @param name the name of the <code>Description</code>
053         * @param uniqueId an arbitrary object used to define uniqueness (in {@link #equals(Object)}
054         * @param annotations meta-data about the test, for downstream interpreters
055         * @return a <code>Description</code> named <code>name</code>
056         */
057        public static Description createSuiteDescription(String name, Serializable uniqueId, Annotation... annotations) {
058            return new Description(null, name, uniqueId, annotations);
059        }
060    
061        /**
062         * Create a <code>Description</code> of a single test named <code>name</code> in the 'class' named
063         * <code>className</code>. Generally, this will be a leaf <code>Description</code>. This method is a better choice
064         * than {@link #createTestDescription(Class, String, Annotation...)} for test runners whose test cases are not
065         * defined in an actual Java <code>Class</code>.
066         *
067         * @param className the class name of the test
068         * @param name the name of the test (a method name for test annotated with {@link org.junit.Test})
069         * @param annotations meta-data about the test, for downstream interpreters
070         * @return a <code>Description</code> named <code>name</code>
071         */
072        public static Description createTestDescription(String className, String name, Annotation... annotations) {
073            return new Description(null, formatDisplayName(name, className), annotations);
074        }
075    
076        /**
077         * Create a <code>Description</code> of a single test named <code>name</code> in the class <code>clazz</code>.
078         * Generally, this will be a leaf <code>Description</code>.
079         *
080         * @param clazz the class of the test
081         * @param name the name of the test (a method name for test annotated with {@link org.junit.Test})
082         * @param annotations meta-data about the test, for downstream interpreters
083         * @return a <code>Description</code> named <code>name</code>
084         */
085        public static Description createTestDescription(Class<?> clazz, String name, Annotation... annotations) {
086            return new Description(clazz, formatDisplayName(name, clazz.getName()), annotations);
087        }
088    
089        /**
090         * Create a <code>Description</code> of a single test named <code>name</code> in the class <code>clazz</code>.
091         * Generally, this will be a leaf <code>Description</code>.
092         * (This remains for binary compatibility with clients of JUnit 4.3)
093         *
094         * @param clazz the class of the test
095         * @param name the name of the test (a method name for test annotated with {@link org.junit.Test})
096         * @return a <code>Description</code> named <code>name</code>
097         */
098        public static Description createTestDescription(Class<?> clazz, String name) {
099            return new Description(clazz, formatDisplayName(name, clazz.getName()));
100        }
101    
102        /**
103         * Create a <code>Description</code> of a single test named <code>name</code> in the class <code>clazz</code>.
104         * Generally, this will be a leaf <code>Description</code>.
105         *
106         * @param name the name of the test (a method name for test annotated with {@link org.junit.Test})
107         * @return a <code>Description</code> named <code>name</code>
108         */
109        public static Description createTestDescription(String className, String name, Serializable uniqueId) {
110            return new Description(null, formatDisplayName(name, className), uniqueId);
111        }
112    
113        private static String formatDisplayName(String name, String className) {
114            return String.format("%s(%s)", name, className);
115        }
116    
117        /**
118         * Create a <code>Description</code> named after <code>testClass</code>
119         *
120         * @param testClass A {@link Class} containing tests
121         * @return a <code>Description</code> of <code>testClass</code>
122         */
123        public static Description createSuiteDescription(Class<?> testClass) {
124            return new Description(testClass, testClass.getName(), testClass.getAnnotations());
125        }
126    
127        /**
128         * Create a <code>Description</code> named after <code>testClass</code>
129         *
130         * @param testClass A not null {@link Class} containing tests
131         * @param annotations meta-data about the test, for downstream interpreters
132         * @return a <code>Description</code> of <code>testClass</code>
133         */
134        public static Description createSuiteDescription(Class<?> testClass, Annotation... annotations) {
135            return new Description(testClass, testClass.getName(), annotations);
136        }
137    
138        /**
139         * Describes a Runner which runs no tests
140         */
141        public static final Description EMPTY = new Description(null, "No Tests");
142    
143        /**
144         * Describes a step in the test-running mechanism that goes so wrong no
145         * other description can be used (for example, an exception thrown from a Runner's
146         * constructor
147         */
148        public static final Description TEST_MECHANISM = new Description(null, "Test mechanism");
149    
150        /*
151         * We have to use the f prefix until the next major release to ensure
152         * serialization compatibility. 
153         * See https://github.com/junit-team/junit4/issues/976
154         */
155        private final Collection<Description> fChildren = new ConcurrentLinkedQueue<Description>();
156        private final String fDisplayName;
157        private final Serializable fUniqueId;
158        private final Annotation[] fAnnotations;
159        private volatile /* write-once */ Class<?> fTestClass;
160    
161        private Description(Class<?> clazz, String displayName, Annotation... annotations) {
162            this(clazz, displayName, displayName, annotations);
163        }
164    
165        private Description(Class<?> testClass, String displayName, Serializable uniqueId, Annotation... annotations) {
166            if ((displayName == null) || (displayName.length() == 0)) {
167                throw new IllegalArgumentException(
168                        "The display name must not be empty.");
169            }
170            if ((uniqueId == null)) {
171                throw new IllegalArgumentException(
172                        "The unique id must not be null.");
173            }
174            this.fTestClass = testClass;
175            this.fDisplayName = displayName;
176            this.fUniqueId = uniqueId;
177            this.fAnnotations = annotations;
178        }
179    
180        /**
181         * @return a user-understandable label
182         */
183        public String getDisplayName() {
184            return fDisplayName;
185        }
186    
187        /**
188         * Add <code>Description</code> as a child of the receiver.
189         *
190         * @param description the soon-to-be child.
191         */
192        public void addChild(Description description) {
193            fChildren.add(description);
194        }
195    
196        /**
197         * Gets the copy of the children of this {@code Description}.
198         * Returns an empty list if there are no children.
199         */
200        public ArrayList<Description> getChildren() {
201            return new ArrayList<Description>(fChildren);
202        }
203    
204        /**
205         * @return <code>true</code> if the receiver is a suite
206         */
207        public boolean isSuite() {
208            return !isTest();
209        }
210    
211        /**
212         * @return <code>true</code> if the receiver is an atomic test
213         */
214        public boolean isTest() {
215            return fChildren.isEmpty();
216        }
217    
218        /**
219         * @return the total number of atomic tests in the receiver
220         */
221        public int testCount() {
222            if (isTest()) {
223                return 1;
224            }
225            int result = 0;
226            for (Description child : fChildren) {
227                result += child.testCount();
228            }
229            return result;
230        }
231    
232        @Override
233        public int hashCode() {
234            return fUniqueId.hashCode();
235        }
236    
237        @Override
238        public boolean equals(Object obj) {
239            if (!(obj instanceof Description)) {
240                return false;
241            }
242            Description d = (Description) obj;
243            return fUniqueId.equals(d.fUniqueId);
244        }
245    
246        @Override
247        public String toString() {
248            return getDisplayName();
249        }
250    
251        /**
252         * @return true if this is a description of a Runner that runs no tests
253         */
254        public boolean isEmpty() {
255            return equals(EMPTY);
256        }
257    
258        /**
259         * @return a copy of this description, with no children (on the assumption that some of the
260         *         children will be added back)
261         */
262        public Description childlessCopy() {
263            return new Description(fTestClass, fDisplayName, fAnnotations);
264        }
265    
266        /**
267         * @return the annotation of type annotationType that is attached to this description node,
268         *         or null if none exists
269         */
270        public <T extends Annotation> T getAnnotation(Class<T> annotationType) {
271            for (Annotation each : fAnnotations) {
272                if (each.annotationType().equals(annotationType)) {
273                    return annotationType.cast(each);
274                }
275            }
276            return null;
277        }
278    
279        /**
280         * @return all of the annotations attached to this description node
281         */
282        public Collection<Annotation> getAnnotations() {
283            return Arrays.asList(fAnnotations);
284        }
285    
286        /**
287         * @return If this describes a method invocation,
288         *         the class of the test instance.
289         */
290        public Class<?> getTestClass() {
291            if (fTestClass != null) {
292                return fTestClass;
293            }
294            String name = getClassName();
295            if (name == null) {
296                return null;
297            }
298            try {
299                fTestClass = Class.forName(name, false, getClass().getClassLoader());
300                return fTestClass;
301            } catch (ClassNotFoundException e) {
302                return null;
303            }
304        }
305    
306        /**
307         * @return If this describes a method invocation,
308         *         the name of the class of the test instance
309         */
310        public String getClassName() {
311            return fTestClass != null ? fTestClass.getName() : methodAndClassNamePatternGroupOrDefault(2, toString());
312        }
313    
314        /**
315         * @return If this describes a method invocation,
316         *         the name of the method (or null if not)
317         */
318        public String getMethodName() {
319            return methodAndClassNamePatternGroupOrDefault(1, null);
320        }
321    
322        private String methodAndClassNamePatternGroupOrDefault(int group,
323                String defaultString) {
324            Matcher matcher = METHOD_AND_CLASS_NAME_PATTERN.matcher(toString());
325            return matcher.matches() ? matcher.group(group) : defaultString;
326        }
327    }