Request.java

package org.junit.runner;

import java.util.Comparator;

import org.junit.internal.requests.ClassRequest;
import org.junit.internal.requests.ClassesRequest;
import org.junit.internal.requests.ErrorReportingRequest;
import org.junit.internal.requests.FilterRequest;
import org.junit.internal.requests.SortingRequest;
import org.junit.runner.manipulation.Filter;

/**
 * <p>A <code>Request</code> is an abstract description of tests to be run. Older versions of 
 * JUnit did not need such a concept--tests to be run were described either by classes containing
 * tests or a tree of {@link  org.junit.Test}s. However, we want to support filtering and sorting,
 * so we need a more abstract specification than the tests themselves and a richer
 * specification than just the classes.</p>
 * 
 * <p>The flow when JUnit runs tests is that a <code>Request</code> specifies some tests to be run ->
 * a {@link org.junit.runner.Runner} is created for each class implied by the <code>Request</code> -> 
 * the {@link org.junit.runner.Runner} returns a detailed {@link org.junit.runner.Description} 
 * which is a tree structure of the tests to be run.</p>
 */
public abstract class Request {
	/**
	 * Create a <code>Request</code> that, when processed, will run a single test.
	 * This is done by filtering out all other tests. This method is used to support rerunning
	 * single tests.
	 * @param clazz the class of the test
	 * @param methodName the name of the test
	 * @return a <code>Request</code> that will cause a single test be run
	 */
	public static Request method(Class<?> clazz, String methodName) {
		Description method= Description.createTestDescription(clazz, methodName);
		return Request.aClass(clazz).filterWith(method);
	}

	/**
	 * Create a <code>Request</code> that, when processed, will run all the tests
	 * in a class. The odd name is necessary because <code>class</code> is a reserved word.
	 * @param clazz the class containing the tests
	 * @return a <code>Request</code> that will cause all tests in the class to be run
	 */
	public static Request aClass(Class<?> clazz) {
		return new ClassRequest(clazz);
	}

	/**
	 * Create a <code>Request</code> that, when processed, will run all the tests
	 * in a set of classes.
	 * @param collectionName a name to identify this suite of tests
	 * @param classes the classes containing the tests
	 * @return a <code>Request</code> that will cause all tests in the classes to be run
	 */
	public static Request classes(String collectionName, Class<?>... classes) {
		return new ClassesRequest(collectionName, classes);
	}

	public static Request errorReport(Class<?> klass, Throwable cause) {
		return new ErrorReportingRequest(klass, cause);
	}

	/**
	 * Returns a {@link Runner} for this Request
	 * @return corresponding {@link Runner} for this Request
	 */
	public abstract Runner getRunner();

	/**
	 * Returns a Request that only contains those tests that should run when
	 * <code>filter</code> is applied
	 * @param filter The {@link Filter} to apply to this Request
	 * @return the filtered Request
	 */
	public Request filterWith(Filter filter) {
		return new FilterRequest(this, filter);
	}

	/**
	 * Returns a Request that only runs contains tests whose {@link Description}
	 * equals <code>desiredDescription</code>
	 * @param desiredDescription {@link Description} of those tests that should be run
	 * @return the filtered Request
	 */
	public Request filterWith(final Description desiredDescription) {
		return filterWith(new Filter() {
			@Override
			public boolean shouldRun(Description description) {
				// TODO: test for equality even if we have children?
				if (description.isTest())
					return desiredDescription.equals(description);
				for (Description each : description.getChildren())
					if (shouldRun(each))
						return true;
				return false;					
			}

			@Override
			public String describe() {
				return String.format("Method %s", desiredDescription.getDisplayName());
			}
		});
	}

	/**
	 * Returns a Request whose Tests can be run in a certain order, defined by 
	 * <code>comparator</code>
	 * 
	 * For example, here is code to run a test suite in alphabetical order:
	 * 
	 * <pre>
	private static Comparator<Description> forward() {
		return new Comparator<Description>() {
			public int compare(Description o1, Description o2) {
				return o1.getDisplayName().compareTo(o2.getDisplayName());
			}
		};
	}
	
	public static main() {
		new JUnitCore().run(Request.aClass(AllTests.class).sortWith(forward()));
	}
	 * </pre>
	 * 
	 * @param comparator definition of the order of the tests in this Request
	 * @return a Request with ordered Tests
	 */
	public Request sortWith(Comparator<Description> comparator) {
		return new SortingRequest(this, comparator);
	}

	public static Request classWithoutSuiteMethod(Class<?> newTestClass) {
		return new ClassRequest(newTestClass, false);
	}
}