1 package org.junit.runner.manipulation;

     2 

     3 import org.junit.runner.Description;

     4 import org.junit.runner.Request;

     5 import org.junit.runner.Runner;

     6 

     7 /**

     8  * The canonical case of filtering is when you want to run a single test method in a class. Rather

     9  * than introduce runner API just for that one case, JUnit provides a general filtering mechanism.

    10  * If you want to filter the tests to be run, extend <code>Filter</code> and apply an instance of

    11  * your filter to the {@link org.junit.runner.Request} before running it (see 

    12  * {@link org.junit.runner.JUnitCore#run(Request)}. Alternatively, apply a <code>Filter</code> to 

    13  * a {@link org.junit.runner.Runner} before running tests (for example, in conjunction with 

    14  * {@link org.junit.runner.RunWith}.

    15  */

    16 public abstract class Filter {

    17 	/**

    18 	 * A null <code>Filter</code> that passes all tests through.

    19 	 */

    20 	public static Filter ALL= new Filter() {

    21 		@Override

    22 		public boolean shouldRun(Description description) {

    23 			return true;

    24 		}

    25 

    26 		@Override

    27 		public String describe() {

    28 			return "all tests";

    29 		}

    30 	};

    31 

    32 	/**

    33 	 * @param description the description of the test to be run

    34 	 * @return <code>true</code> if the test should be run

    35 	 */

    36 	public abstract boolean shouldRun(Description description);

    37 

    38 	/**

    39 	 * Invoke with a {@link org.junit.runner.Runner} to cause all tests it intends to run

    40 	 * to first be checked with the filter. Only those that pass the filter will be run.

    41 	 * @param runner the runner to be filtered by the receiver

    42 	 * @throws NoTestsRemainException if the receiver removes all tests

    43 	 */

    44 	public void apply(Runner runner) throws NoTestsRemainException {

    45 		if (runner instanceof Filterable) {

    46 			Filterable filterable= (Filterable)runner;

    47 			filterable.filter(this);

    48 		}

    49 	}

    50 

    51 	/**

    52 	 * Returns a textual description of this Filter

    53 	 * @return a textual description of this Filter

    54 	 */

    55 	public abstract String describe();

    56 }