001    package org.junit.runners;
002    
003    import java.lang.annotation.ElementType;
004    import java.lang.annotation.Inherited;
005    import java.lang.annotation.Retention;
006    import java.lang.annotation.RetentionPolicy;
007    import java.lang.annotation.Target;
008    import java.util.Collections;
009    import java.util.List;
010    
011    import org.junit.internal.builders.AllDefaultPossibilitiesBuilder;
012    import org.junit.runner.Description;
013    import org.junit.runner.Runner;
014    import org.junit.runner.notification.RunNotifier;
015    import org.junit.runners.model.InitializationError;
016    import org.junit.runners.model.RunnerBuilder;
017    
018    /**
019     * Using <code>Suite</code> as a runner allows you to manually
020     * build a suite containing tests from many classes. It is the JUnit 4 equivalent of the JUnit 3.8.x
021     * static {@link junit.framework.Test} <code>suite()</code> method. To use it, annotate a class
022     * with <code>@RunWith(Suite.class)</code> and <code>@SuiteClasses({TestClass1.class, ...})</code>.
023     * When you run this class, it will run all the tests in all the suite classes.
024     *
025     * @since 4.0
026     */
027    public class Suite extends ParentRunner<Runner> {
028        /**
029         * Returns an empty suite.
030         */
031        public static Runner emptySuite() {
032            try {
033                return new Suite((Class<?>) null, new Class<?>[0]);
034            } catch (InitializationError e) {
035                throw new RuntimeException("This shouldn't be possible");
036            }
037        }
038    
039        /**
040         * The <code>SuiteClasses</code> annotation specifies the classes to be run when a class
041         * annotated with <code>@RunWith(Suite.class)</code> is run.
042         */
043        @Retention(RetentionPolicy.RUNTIME)
044        @Target(ElementType.TYPE)
045        @Inherited
046        public @interface SuiteClasses {
047            /**
048             * @return the classes to be run
049             */
050            Class<?>[] value();
051        }
052    
053        private static Class<?>[] getAnnotatedClasses(Class<?> klass) throws InitializationError {
054            SuiteClasses annotation = klass.getAnnotation(SuiteClasses.class);
055            if (annotation == null) {
056                throw new InitializationError(String.format("class '%s' must have a SuiteClasses annotation", klass.getName()));
057            }
058            return annotation.value();
059        }
060    
061        private final List<Runner> runners;
062    
063        /**
064         * Called reflectively on classes annotated with <code>@RunWith(Suite.class)</code>
065         *
066         * @param klass the root class
067         * @param builder builds runners for classes in the suite
068         */
069        public Suite(Class<?> klass, RunnerBuilder builder) throws InitializationError {
070            this(builder, klass, getAnnotatedClasses(klass));
071        }
072    
073        /**
074         * Call this when there is no single root class (for example, multiple class names
075         * passed on the command line to {@link org.junit.runner.JUnitCore}
076         *
077         * @param builder builds runners for classes in the suite
078         * @param classes the classes in the suite
079         */
080        public Suite(RunnerBuilder builder, Class<?>[] classes) throws InitializationError {
081            this(null, builder.runners(null, classes));
082        }
083    
084        /**
085         * Call this when the default builder is good enough. Left in for compatibility with JUnit 4.4.
086         *
087         * @param klass the root of the suite
088         * @param suiteClasses the classes in the suite
089         */
090        protected Suite(Class<?> klass, Class<?>[] suiteClasses) throws InitializationError {
091            this(new AllDefaultPossibilitiesBuilder(), klass, suiteClasses);
092        }
093    
094        /**
095         * Called by this class and subclasses once the classes making up the suite have been determined
096         *
097         * @param builder builds runners for classes in the suite
098         * @param klass the root of the suite
099         * @param suiteClasses the classes in the suite
100         */
101        protected Suite(RunnerBuilder builder, Class<?> klass, Class<?>[] suiteClasses) throws InitializationError {
102            this(klass, builder.runners(klass, suiteClasses));
103        }
104    
105        /**
106         * Called by this class and subclasses once the runners making up the suite have been determined
107         *
108         * @param klass root of the suite
109         * @param runners for each class in the suite, a {@link Runner}
110         */
111        protected Suite(Class<?> klass, List<Runner> runners) throws InitializationError {
112            super(klass);
113            this.runners = Collections.unmodifiableList(runners);
114        }
115    
116        @Override
117        protected List<Runner> getChildren() {
118            return runners;
119        }
120    
121        @Override
122        protected Description describeChild(Runner child) {
123            return child.getDescription();
124        }
125    
126        @Override
127        protected void runChild(Runner runner, final RunNotifier notifier) {
128            runner.run(notifier);
129        }
130    }