Test Runners

/**
 * Facade for running tests and collecting results
 */
public class JUnitCore {
    /**
     * Run tests from command line
     * @param args - Fully qualified class names of test classes
     */
    public static void main(String... args);

    /**
     * Run tests and return results
     * @param classes - Test classes to run
     * @return Results of test execution
     */
    public Result run(Class<?>... classes);

    /**
     * Run tests and return results (alias for run)
     * @param classes - Test classes to run
     * @return Results of test execution
     */
    public Result runClasses(Class<?>... classes);

    /**
     * Run tests using a Request
     * @param request - Configured test request
     * @return Results of test execution
     */
    public Result run(Request request);

    /**
     * Run tests with a specific runner
     * @param runner - Runner to use
     * @return Results of test execution
     */
    public Result run(Runner runner);

    /**
     * Run a JUnit 3.x style test
     * @param test - JUnit 3.x Test to run
     * @return Results of test execution
     */
    public Result run(junit.framework.Test test);

    /**
     * Add a listener to be notified of test events
     * @param listener - Listener to add
     */
    public void addListener(RunListener listener);

    /**
     * Remove a previously added listener
     * @param listener - Listener to remove
     */
    public void removeListener(RunListener listener);

    /**
     * Get JUnit version string
     * @return Version string (e.g., "4.13.2")
     */
    public String getVersion();
}

import org.junit.runner.JUnitCore;
import org.junit.runner.Result;
import org.junit.runner.notification.Failure;

public class TestRunner {
    public static void main(String[] args) {
        // Run single test class
        Result result = JUnitCore.runClasses(MyTest.class);
        System.out.println("Tests run: " + result.getRunCount());
        System.out.println("Failures: " + result.getFailureCount());

        // Run multiple test classes
        Result multiResult = JUnitCore.runClasses(
            TestClass1.class,
            TestClass2.class,
            TestClass3.class
        );

        // Check results
        if (!multiResult.wasSuccessful()) {
            System.out.println("Some tests failed:");
            for (Failure failure : multiResult.getFailures()) {
                System.out.println(failure.toString());
            }
        }

        // Print execution time
        System.out.println("Execution time: " + multiResult.getRunTime() + "ms");
    }
}

import org.junit.runner.JUnitCore;
import org.junit.runner.Result;
import org.junit.runner.notification.RunListener;
import org.junit.runner.Description;
import org.junit.runner.notification.Failure;

public class CustomTestRunner {
    public static void main(String[] args) {
        JUnitCore core = new JUnitCore();

        // Add custom listener
        core.addListener(new RunListener() {
            @Override
            public void testStarted(Description description) {
                System.out.println("Starting: " + description.getDisplayName());
            }

            @Override
            public void testFinished(Description description) {
                System.out.println("Finished: " + description.getDisplayName());
            }

            @Override
            public void testFailure(Failure failure) {
                System.out.println("Failed: " + failure.getDescription().getDisplayName());
            }
        });

        Result result = core.run(MyTest.class);
        System.exit(result.wasSuccessful() ? 0 : 1);
    }
}

/**
 * Test execution results
 */
public class Result implements Serializable {
    /**
     * Get number of tests that were run
     * @return Count of executed tests
     */
    public int getRunCount();

    /**
     * Get number of tests that failed
     * @return Count of failed tests
     */
    public int getFailureCount();

    /**
     * Get number of tests that were ignored
     * @return Count of ignored tests
     */
    public int getIgnoreCount();

    /**
     * Get number of assumption failures
     * @return Count of assumption failures (tests skipped)
     */
    public int getAssumptionFailureCount();

    /**
     * Get total execution time in milliseconds
     * @return Execution time in milliseconds
     */
    public long getRunTime();

    /**
     * Get list of all failures
     * @return List of Failure objects
     */
    public List<Failure> getFailures();

    /**
     * Check if all tests passed
     * @return true if no failures or assumption violations
     */
    public boolean wasSuccessful();

    /**
     * Create a listener that populates this result
     * @return RunListener that updates this result
     */
    public RunListener createListener();
}

import org.junit.runner.JUnitCore;
import org.junit.runner.Result;
import org.junit.runner.notification.Failure;

public class ResultAnalyzer {
    public static void analyzeResults(Result result) {
        System.out.println("=== Test Results ===");
        System.out.println("Tests run: " + result.getRunCount());
        System.out.println("Failures: " + result.getFailureCount());
        System.out.println("Ignored: " + result.getIgnoreCount());
        System.out.println("Assumptions failed: " + result.getAssumptionFailureCount());
        System.out.println("Time: " + result.getRunTime() + "ms");
        System.out.println("Success: " + result.wasSuccessful());

        if (!result.wasSuccessful()) {
            System.out.println("\n=== Failures ===");
            for (Failure failure : result.getFailures()) {
                System.out.println(failure.getTestHeader());
                System.out.println(failure.getMessage());
                System.out.println(failure.getTrace());
            }
        }
    }

    public static void main(String[] args) {
        Result result = JUnitCore.runClasses(MyTest.class);
        analyzeResults(result);
    }
}

/**
 * Base class for test runners
 */
public abstract class Runner implements Describable {
    /**
     * Get description of tests this runner will execute
     * @return Description object
     */
    public abstract Description getDescription();

    /**
     * Run the tests, notifying the given notifier of events
     * @param notifier - Notifier for test events
     */
    public abstract void run(RunNotifier notifier);

    /**
     * Get count of tests that will be run
     * @return Number of tests
     */
    public int testCount();
}

import org.junit.runner.Runner;
import org.junit.runner.Description;
import org.junit.runner.notification.RunNotifier;
import org.junit.runners.model.InitializationError;

public class CustomRunner extends Runner {
    private Class<?> testClass;

    public CustomRunner(Class<?> testClass) throws InitializationError {
        this.testClass = testClass;
    }

    @Override
    public Description getDescription() {
        return Description.createSuiteDescription(testClass);
    }

    @Override
    public void run(RunNotifier notifier) {
        Description description = getDescription();
        notifier.fireTestStarted(description);

        try {
            // Custom test execution logic
            Object testInstance = testClass.getDeclaredConstructor().newInstance();
            // Run test methods...
            notifier.fireTestFinished(description);
        } catch (Exception e) {
            notifier.fireTestFailure(new Failure(description, e));
        }
    }
}

/**
 * A request to run tests
 */
public abstract class Request {
    /**
     * Create a request to run all tests in classes
     * @param computer - Strategy for running tests
     * @param classes - Test classes to run
     * @return Request object
     */
    public static Request classes(Computer computer, Class<?>... classes);

    /**
     * Create a request to run all tests in classes
     * @param classes - Test classes to run
     * @return Request object
     */
    public static Request classes(Class<?>... classes);

    /**
     * Create a request to run tests with a custom runner
     * @param runner - Runner to use
     * @return Request object
     */
    public static Request runner(Runner runner);

    /**
     * Create a request to run a single method
     * @param clazz - Test class
     * @param methodName - Method name
     * @return Request object
     */
    public static Request method(Class<?> clazz, String methodName);

    /**
     * Create a request for a test suite
     * @param clazz - Test class
     * @return Request object
     */
    public static Request aClass(Class<?> clazz);

    /**
     * Create a request for a test class without JUnit 3 suite() method
     * @param clazz - Test class
     * @return Request object
     */
    public static Request classWithoutSuiteMethod(Class<?> clazz);

    /**
     * Create a request that will report an error
     * @param klass - Test class that has error
     * @param cause - Exception that caused the error
     * @return Request object
     */
    public static Request errorReport(Class<?> klass, Throwable cause);

    /**
     * Get the runner for this request
     * @return Runner object
     */
    public abstract Runner getRunner();

    /**
     * Filter the tests to run
     * @param filter - Filter to apply
     * @return Filtered request
     */
    public Request filterWith(Filter filter);

    /**
     * Filter the tests by description
     * @param desiredDescription - Description to match
     * @return Filtered request
     */
    public Request filterWith(Description desiredDescription);

    /**
     * Sort the tests
     * @param comparator - Comparison function for ordering
     * @return Sorted request
     */
    public Request sortWith(Comparator<Description> comparator);

    /**
     * Order the tests using an Ordering
     * @param ordering - Ordering to apply
     * @return Ordered request
     */
    public Request orderWith(Ordering ordering);
}

import org.junit.runner.JUnitCore;
import org.junit.runner.Request;
import org.junit.runner.Result;

public class RequestExamples {
    public static void runSingleMethod() {
        // Run just one test method
        Request request = Request.method(MyTest.class, "testAddition");
        Result result = new JUnitCore().run(request);
    }

    public static void runWithFilter() {
        // Run only fast tests
        Request request = Request.aClass(MyTest.class);
        request = request.filterWith(new CategoryFilter(FastTests.class));
        Result result = new JUnitCore().run(request);
    }

    public static void runSorted() {
        // Run tests in specific order
        Request request = Request.aClass(MyTest.class);
        request = request.sortWith(new Comparator<Description>() {
            public int compare(Description d1, Description d2) {
                return d1.getMethodName().compareTo(d2.getMethodName());
            }
        });
        Result result = new JUnitCore().run(request);
    }
}

/**
 * Notifies listeners of test execution events
 */
public class RunNotifier {
    /**
     * Add a listener
     * @param listener - Listener to add
     */
    public void addListener(RunListener listener);

    /**
     * Add a listener at the front of the list
     * @param listener - Listener to add first
     */
    public void addFirstListener(RunListener listener);

    /**
     * Remove a listener
     * @param listener - Listener to remove
     */
    public void removeListener(RunListener listener);

    /**
     * Notify that a test suite is starting
     * @param description - Description of suite
     */
    public void fireTestSuiteStarted(Description description);

    /**
     * Notify that a test suite finished
     * @param description - Description of suite
     */
    public void fireTestSuiteFinished(Description description);

    /**
     * Notify that test run started
     * @param description - Description of run
     */
    public void fireTestRunStarted(Description description);

    /**
     * Notify that test run finished
     * @param result - Result of test run
     */
    public void fireTestRunFinished(Result result);

    /**
     * Notify that a test started
     * @param description - Description of test
     */
    public void fireTestStarted(Description description);

    /**
     * Notify that a test finished
     * @param description - Description of test
     */
    public void fireTestFinished(Description description);

    /**
     * Notify that a test failed
     * @param failure - Failure information
     */
    public void fireTestFailure(Failure failure);

    /**
     * Notify that a test was ignored
     * @param description - Description of ignored test
     */
    public void fireTestIgnored(Description description);

    /**
     * Notify that an assumption failed (test skipped)
     * @param failure - Assumption failure
     */
    public void fireTestAssumptionFailed(Failure failure);

    /**
     * Request that test run stop
     */
    public void pleaseStop();
}

/**
 * Listener for test execution events
 */
public abstract class RunListener {
    /**
     * Called when test run starts
     * @param description - Description of test run
     */
    public void testRunStarted(Description description) throws Exception;

    /**
     * Called when test run finishes
     * @param result - Result of test run
     */
    public void testRunFinished(Result result) throws Exception;

    /**
     * Called when test suite starts
     * @param description - Description of suite
     */
    public void testSuiteStarted(Description description) throws Exception;

    /**
     * Called when test suite finishes
     * @param description - Description of suite
     */
    public void testSuiteFinished(Description description) throws Exception;

    /**
     * Called when a test starts
     * @param description - Description of test
     */
    public void testStarted(Description description) throws Exception;

    /**
     * Called when a test finishes
     * @param description - Description of test
     */
    public void testFinished(Description description) throws Exception;

    /**
     * Called when a test fails
     * @param failure - Failure information
     */
    public void testFailure(Failure failure) throws Exception;

    /**
     * Called when an assumption fails (test skipped)
     * @param failure - Assumption failure
     */
    public void testAssumptionFailure(Failure failure);

    /**
     * Called when a test is ignored
     * @param description - Description of ignored test
     */
    public void testIgnored(Description description) throws Exception;
}

import org.junit.runner.notification.RunListener;
import org.junit.runner.Description;
import org.junit.runner.notification.Failure;
import org.junit.runner.Result;

public class DetailedLogger extends RunListener {
    private long startTime;

    @Override
    public void testRunStarted(Description description) {
        System.out.println("Starting test run: " + description.getDisplayName());
        startTime = System.currentTimeMillis();
    }

    @Override
    public void testRunFinished(Result result) {
        long duration = System.currentTimeMillis() - startTime;
        System.out.println("Test run finished in " + duration + "ms");
        System.out.println("Tests: " + result.getRunCount());
        System.out.println("Failures: " + result.getFailureCount());
        System.out.println("Ignored: " + result.getIgnoreCount());
    }

    @Override
    public void testStarted(Description description) {
        System.out.println("  Running: " + description.getMethodName());
    }

    @Override
    public void testFinished(Description description) {
        System.out.println("  Finished: " + description.getMethodName());
    }

    @Override
    public void testFailure(Failure failure) {
        System.err.println("  FAILED: " + failure.getDescription().getMethodName());
        System.err.println("    " + failure.getMessage());
    }

    @Override
    public void testIgnored(Description description) {
        System.out.println("  IGNORED: " + description.getMethodName());
    }
}

// Usage
JUnitCore core = new JUnitCore();
core.addListener(new DetailedLogger());
core.run(MyTest.class);

/**
 * Abstract base class for filtering tests
 */
public abstract class Filter {
    /**
     * A null Filter that passes all tests through
     */
    public static final Filter ALL;

    /**
     * Returns a Filter that only runs the single method described by desiredDescription
     * @param desiredDescription - Description to match
     * @return Filter that matches only this description
     */
    public static Filter matchMethodDescription(Description desiredDescription);

    /**
     * Determine if the test should be run
     * @param description - Description of the test
     * @return true if the test should be run
     */
    public abstract boolean shouldRun(Description description);

    /**
     * Returns a textual description of this Filter
     * @return Description string
     */
    public abstract String describe();

    /**
     * Invoke with a Runner to cause all tests it intends to run to first be checked with the filter
     * @param child - The runner to be filtered
     * @throws NoTestsRemainException if the receiver removes all tests
     */
    public void apply(Object child) throws NoTestsRemainException;

    /**
     * Returns a new Filter that accepts the intersection of tests accepted by this Filter and second
     * @param second - Filter to intersect with
     * @return Intersected filter
     */
    public Filter intersect(Filter second);
}

import org.junit.runner.JUnitCore;
import org.junit.runner.Request;
import org.junit.runner.manipulation.Filter;
import org.junit.runner.Description;

public class FilterExamples {
    // Run only a single test method
    public static void runSingleMethod() {
        Request request = Request.aClass(MyTest.class);
        Description methodDesc = Description.createTestDescription(
            MyTest.class, "testAddition");
        request = request.filterWith(Filter.matchMethodDescription(methodDesc));
        new JUnitCore().run(request);
    }

    // Custom filter for fast tests
    public static void runFastTests() {
        Request request = Request.aClass(MyTest.class);
        request = request.filterWith(new Filter() {
            @Override
            public boolean shouldRun(Description description) {
                // Run if annotated with @Fast or if it's a suite
                return description.getAnnotation(Fast.class) != null
                    || !description.isTest();
            }

            @Override
            public String describe() {
                return "fast tests only";
            }
        });
        new JUnitCore().run(request);
    }

    // Combine multiple filters
    public static void runIntersectedFilters() {
        Filter fastFilter = new FastTestFilter();
        Filter categoryFilter = new CategoryFilter(DatabaseTests.class);

        // Run tests that match both filters
        Filter combined = fastFilter.intersect(categoryFilter);
        Request request = Request.aClass(MyTest.class).filterWith(combined);
        new JUnitCore().run(request);
    }
}

/**
 * Interface for runners that allow filtering
 */
public interface Filterable {
    /**
     * Remove tests that don't pass the parameter filter
     * @param filter - The Filter to apply
     * @throws NoTestsRemainException if all tests are filtered out
     */
    void filter(Filter filter) throws NoTestsRemainException;
}

/**
 * Interface for runners that allow sorting of tests
 */
public interface Sortable {
    /**
     * Sorts the tests using sorter
     * @param sorter - The Sorter to use for sorting the tests
     */
    void sort(Sorter sorter);
}

/**
 * Interface for runners that allow ordering of tests
 *
 * Beware of using this interface to cope with order dependencies between tests.
 * Tests that are isolated from each other are less expensive to maintain and
 * can be run individually.
 *
 * @since 4.13
 */
public interface Orderable extends Sortable {
    /**
     * Orders the tests using orderer
     * @param orderer - The Orderer to apply
     * @throws InvalidOrderingException if orderer does something invalid (like remove or add children)
     */
    void order(Orderer orderer) throws InvalidOrderingException;
}

import org.junit.runner.manipulation.Orderable;
import org.junit.runner.manipulation.Orderer;
import org.junit.runner.manipulation.Ordering;
import org.junit.runner.manipulation.InvalidOrderingException;
import org.junit.runner.Description;
import java.util.Random;

public class OrderableRunnerExample {
    // Using Request.orderWith() to order tests (recommended approach)
    public static void orderTestsWithShuffle() {
        Request request = Request.aClass(MyTest.class);

        // Create a shuffled ordering with a specific seed for reproducibility
        Random random = new Random(12345L);
        Ordering ordering = Ordering.shuffledBy(random);

        // Apply ordering to request
        request = request.orderWith(ordering);
        new JUnitCore().run(request);
    }

    // Custom runner implementing Orderable
    public static class CustomOrderableRunner extends Runner implements Orderable {
        private List<Description> children;

        @Override
        public void order(Orderer orderer) throws InvalidOrderingException {
            // Let the orderer determine the order
            children = orderer.order(children);
        }

        @Override
        public void sort(Sorter sorter) {
            // Also support simple sorting
            Collections.sort(children, sorter);
        }

        @Override
        public Description getDescription() {
            Description suite = Description.createSuiteDescription("Custom Suite");
            for (Description child : children) {
                suite.addChild(child);
            }
            return suite;
        }

        @Override
        public void run(RunNotifier notifier) {
            // Run tests in the ordered sequence
            for (Description child : children) {
                notifier.fireTestStarted(child);
                // Execute test...
                notifier.fireTestFinished(child);
            }
        }
    }
}

/**
 * Orders tests based on a comparator
 */
public class Sorter extends Ordering implements Comparator<Description> {
    /**
     * NULL is a Sorter that leaves elements in an undefined order
     */
    public static final Sorter NULL;

    /**
     * Creates a Sorter that uses comparator to sort tests
     * @param comparator - The Comparator to use when sorting tests
     */
    public Sorter(Comparator<Description> comparator);

    /**
     * Sorts the tests in target using comparator
     * @param target - Runner to sort (typically implements Sortable)
     */
    public void apply(Object target);

    /**
     * Compare two descriptions
     * @param o1 - First description
     * @param o2 - Second description
     * @return Comparison result
     */
    public int compare(Description o1, Description o2);
}

import org.junit.runner.JUnitCore;
import org.junit.runner.Request;
import org.junit.runner.manipulation.Sorter;
import org.junit.runner.Description;
import java.util.Comparator;

public class SorterExamples {
    // Sort tests alphabetically by method name
    public static void runAlphabetically() {
        Request request = Request.aClass(MyTest.class);
        request = request.sortWith(new Comparator<Description>() {
            public int compare(Description d1, Description d2) {
                return d1.getMethodName().compareTo(d2.getMethodName());
            }
        });
        new JUnitCore().run(request);
    }

    // Sort tests by annotation priority
    public static void runByPriority() {
        Sorter sorter = new Sorter(new Comparator<Description>() {
            public int compare(Description d1, Description d2) {
                Priority p1 = d1.getAnnotation(Priority.class);
                Priority p2 = d2.getAnnotation(Priority.class);
                int priority1 = (p1 != null) ? p1.value() : Integer.MAX_VALUE;
                int priority2 = (p2 != null) ? p2.value() : Integer.MAX_VALUE;
                return Integer.compare(priority1, priority2);
            }
        });

        Request request = Request.aClass(MyTest.class);
        request = request.sortWith(sorter);
        new JUnitCore().run(request);
    }
}

/**
 * A sorter that orders tests alphanumerically by test name
 * @since 4.13
 */
public final class Alphanumeric extends Sorter implements Ordering.Factory {
    /**
     * Creates an Alphanumeric sorter
     */
    public Alphanumeric();

    /**
     * Creates an Ordering instance using the given context
     * @param context - Context for creating ordering
     * @return This Alphanumeric instance as an Ordering
     */
    public Ordering create(Context context);
}

import org.junit.runner.JUnitCore;
import org.junit.runner.Request;
import org.junit.runner.manipulation.Alphanumeric;

public class AlphanumericExamples {
    // Sort tests alphabetically using sortWith
    public static void sortAlphabetically() {
        Request request = Request.aClass(MyTest.class);
        request = request.sortWith(new Alphanumeric());
        new JUnitCore().run(request);
    }

    // Order tests alphabetically using orderWith
    public static void orderAlphabetically() {
        Request request = Request.aClass(MyTest.class);
        Alphanumeric alphanumeric = new Alphanumeric();
        try {
            request = request.orderWith(
                alphanumeric.create(null)  // Context not needed for Alphanumeric
            );
        } catch (Exception e) {
            e.printStackTrace();
        }
        new JUnitCore().run(request);
    }

    // Example test class - methods will run in alphabetical order
    public static class MyTest {
        @Test
        public void testZebra() { }

        @Test
        public void testApple() { }

        @Test
        public void testMango() { }

        // Execution order with Alphanumeric:
        // 1. testApple
        // 2. testMango
        // 3. testZebra
    }
}

/**
 * Extend this class to create a factory that creates Filter
 */
public interface FilterFactory {
    /**
     * Creates a Filter given a FilterFactoryParams argument
     * @param params - Parameters needed to create the Filter
     * @return Created filter
     * @throws FilterNotCreatedException if the Filter cannot be created
     */
    Filter createFilter(FilterFactoryParams params) throws FilterNotCreatedException;

    /**
     * Exception thrown if the Filter cannot be created
     */
    class FilterNotCreatedException extends Exception {
        public FilterNotCreatedException(Exception exception);
    }
}

import org.junit.runner.FilterFactory;
import org.junit.runner.FilterFactoryParams;
import org.junit.runner.manipulation.Filter;
import org.junit.runner.Description;

// Custom filter factory that filters by test name pattern
public class NamePatternFilterFactory implements FilterFactory {
    @Override
    public Filter createFilter(FilterFactoryParams params)
            throws FilterNotCreatedException {
        final String pattern = params.getArgs();

        if (pattern == null || pattern.isEmpty()) {
            throw new FilterNotCreatedException(
                new IllegalArgumentException("Pattern cannot be empty")
            );
        }

        return new Filter() {
            @Override
            public boolean shouldRun(Description description) {
                if (!description.isTest()) {
                    return true;  // Include suites
                }
                String methodName = description.getMethodName();
                return methodName != null && methodName.contains(pattern);
            }

            @Override
            public String describe() {
                return "tests containing '" + pattern + "'";
            }
        };
    }
}

// Custom filter factory that filters by annotation
public class AnnotationFilterFactory implements FilterFactory {
    @Override
    public Filter createFilter(FilterFactoryParams params)
            throws FilterNotCreatedException {
        final String annotationName = params.getArgs();

        try {
            final Class<?> annotationClass = Class.forName(annotationName);

            return new Filter() {
                @Override
                public boolean shouldRun(Description description) {
                    if (!description.isTest()) {
                        return true;
                    }
                    return description.getAnnotation(annotationClass) != null;
                }

                @Override
                public String describe() {
                    return "tests with @" + annotationClass.getSimpleName();
                }
            };
        } catch (ClassNotFoundException e) {
            throw new FilterNotCreatedException(e);
        }
    }
}

// Usage: From command line or programmatically
// java org.junit.runner.JUnitCore \
//   --filter=com.example.NamePatternFilterFactory=integration \
//   com.example.MyTestClass

/**
 * Utility class whose methods create a FilterFactory
 */
class FilterFactories {
    /**
     * Creates a Filter from a filter specification
     *
     * A filter specification is of the form "package.of.FilterFactory=args-to-filter-factory"
     * or "package.of.FilterFactory"
     *
     * @param request - The request that will be filtered
     * @param filterSpec - The filter specification
     * @return Created filter
     * @throws FilterFactory.FilterNotCreatedException if filter cannot be created
     */
    public static Filter createFilterFromFilterSpec(Request request, String filterSpec)
            throws FilterFactory.FilterNotCreatedException;

    /**
     * Creates a Filter from a fully qualified class name
     * @param filterFactoryFqcn - The fully qualified class name of the FilterFactory
     * @param params - The arguments to the FilterFactory
     * @return Created filter
     * @throws FilterFactory.FilterNotCreatedException if filter cannot be created
     */
    public static Filter createFilter(String filterFactoryFqcn, FilterFactoryParams params)
            throws FilterFactory.FilterNotCreatedException;

    /**
     * Creates a Filter from a FilterFactory class
     * @param filterFactoryClass - The class of the FilterFactory
     * @param params - The arguments to the FilterFactory
     * @return Created filter
     * @throws FilterFactory.FilterNotCreatedException if filter cannot be created
     */
    public static Filter createFilter(Class<? extends FilterFactory> filterFactoryClass,
                                     FilterFactoryParams params)
            throws FilterFactory.FilterNotCreatedException;
}

import org.junit.runner.Request;
import org.junit.runner.FilterFactories;
import org.junit.runner.FilterFactoryParams;
import org.junit.runner.manipulation.Filter;
import org.junit.runner.JUnitCore;

public class FilterFactoriesExamples {
    // Parse and apply a filter specification
    public static void useFilterSpec() {
        Request request = Request.aClass(MyTest.class);

        try {
            // Format: "full.package.FilterFactoryClass=arguments"
            String filterSpec = "com.example.NamePatternFilterFactory=integration";
            Filter filter = FilterFactories.createFilterFromFilterSpec(request, filterSpec);

            request = request.filterWith(filter);
            new JUnitCore().run(request);
        } catch (FilterFactory.FilterNotCreatedException e) {
            System.err.println("Failed to create filter: " + e.getMessage());
        }
    }

    // Create filter from factory class directly
    public static void useFactoryClass() {
        Request request = Request.aClass(MyTest.class);

        try {
            FilterFactoryParams params = new FilterFactoryParams(
                request.getRunner().getDescription(),
                "Fast"  // Arguments for the factory
            );

            Filter filter = FilterFactories.createFilter(
                AnnotationFilterFactory.class,
                params
            );

            request = request.filterWith(filter);
            new JUnitCore().run(request);
        } catch (FilterFactory.FilterNotCreatedException e) {
            System.err.println("Failed to create filter: " + e.getMessage());
        }
    }

    // Create filter without arguments
    public static void useFilterWithoutArgs() {
        Request request = Request.aClass(MyTest.class);

        try {
            String filterSpec = "com.example.FastTestFilterFactory";
            Filter filter = FilterFactories.createFilterFromFilterSpec(request, filterSpec);

            request = request.filterWith(filter);
            new JUnitCore().run(request);
        } catch (FilterFactory.FilterNotCreatedException e) {
            System.err.println("Failed to create filter: " + e.getMessage());
        }
    }
}

/**
 * Failure information
 */
public class Failure implements Serializable {
    public Failure(Description description, Throwable thrownException);

    public Description getDescription();
    public Throwable getException();
    public String getMessage();
    public String getTestHeader();
    public String getTrace();
    public String getTrimmedTrace();
}

/**
 * Thrown when a filter removes all tests from a runner
 */
public class NoTestsRemainException extends Exception {
}

/**
 * Thrown when an ordering does something invalid (like remove or add children)
 * @since 4.13
 */
public class InvalidOrderingException extends Exception {
    public InvalidOrderingException();
    public InvalidOrderingException(String message);
    public InvalidOrderingException(String message, Throwable cause);
}

/**
 * Represents an object that can describe itself
 */
public interface Describable {
    Description getDescription();
}

/**
 * Strategy for computing runners and suites
 */
public class Computer {
    /**
     * Create a serial computer (runs tests sequentially)
     * @return Computer that runs tests one at a time
     */
    public static Computer serial();

    /**
     * Get runner for a test suite
     * @param parent - Parent runner
     * @param classes - Test classes
     * @return Runner for the suite
     */
    public Runner getSuite(RunnerBuilder parent, Class<?>[] classes) throws InitializationError;

    /**
     * Get runner for a single test class
     * @param testClass - Test class
     * @return Runner for the class
     */
    protected Runner getRunner(RunnerBuilder builder, Class<?> testClass) throws Throwable;
}

/**
 * Computer for running tests in parallel. Extends Computer to provide concurrent execution.
 * Part of org.junit.experimental package.
 */
public class ParallelComputer extends Computer {
    /**
     * Constructor for ParallelComputer
     * @param classes - true to parallelize classes, false otherwise
     * @param methods - true to parallelize methods, false otherwise
     */
    public ParallelComputer(boolean classes, boolean methods);

    /**
     * Create a computer that runs test classes in parallel
     * @return Computer that parallelizes classes
     */
    public static Computer classes();

    /**
     * Create a computer that runs test methods in parallel
     * @return Computer that parallelizes methods
     */
    public static Computer methods();
}

/**
 * Reorders tests. An Ordering can reverse the order of tests, sort the order or shuffle the order.
 * Generally used through Request.orderWith() rather than directly.
 * @since 4.13
 */
public abstract class Ordering {
    /**
     * Creates an Ordering that shuffles items using the given Random instance
     * @param random - Random instance for shuffling
     * @return Ordering that shuffles
     */
    public static Ordering shuffledBy(Random random);

    /**
     * Creates an Ordering from the given factory class
     * @param factoryClass - Factory class to create the ordering
     * @param annotatedTestClass - Test class annotated with @OrderWith
     * @return Created ordering
     * @throws InvalidOrderingException if the instance could not be created
     */
    public static Ordering definedBy(
            Class<? extends Ordering.Factory> factoryClass,
            Description annotatedTestClass) throws InvalidOrderingException;

    /**
     * Creates an Ordering from the given factory
     * @param factory - Factory to use
     * @param annotatedTestClass - Test class annotated with @OrderWith
     * @return Created ordering
     * @throws InvalidOrderingException if the instance could not be created
     */
    public static Ordering definedBy(
            Ordering.Factory factory,
            Description annotatedTestClass) throws InvalidOrderingException;

    /**
     * Order the tests in target using this ordering
     * @param target - Target to order (typically Orderable)
     * @throws InvalidOrderingException if ordering does something invalid
     */
    public void apply(Object target) throws InvalidOrderingException;

    /**
     * Implemented by sub-classes to order the descriptions
     * @param descriptions - Descriptions to order
     * @return descriptions in order
     */
    protected abstract List<Description> orderItems(Collection<Description> descriptions);

    /** Context about the ordering being applied */
    public static class Context {
        /**
         * Gets the description for the top-level target being ordered
         * @return Description of target
         */
        public Description getTarget();
    }

    /**
     * Factory for creating Ordering instances
     * For use with @OrderWith, needs public no-arg constructor
     */
    public interface Factory {
        /**
         * Creates an Ordering instance using the given context
         * @param context - Context for creating ordering
         * @return Created ordering
         */
        Ordering create(Context context);
    }
}

/**
 * Orders tests. Used internally by Ordering to apply ordering logic.
 * @since 4.13
 */
public final class Orderer {
    /**
     * Orders the descriptions
     * @param descriptions - Descriptions to order
     * @return descriptions in order
     * @throws InvalidOrderingException if ordering is invalid
     */
    public List<Description> order(Collection<Description> descriptions)
            throws InvalidOrderingException;

    /**
     * Order the tests in target
     * @param target - Target to order
     * @throws InvalidOrderingException if ordering is invalid
     */
    public void apply(Object target) throws InvalidOrderingException;
}

/**
 * Parameters passed to FilterFactory for creating filters.
 * Contains the top-level test description and string arguments from filter specification.
 */
public final class FilterFactoryParams {
    /**
     * Creates filter factory parameters
     * @param topLevelDescription - Description of all tests being filtered
     * @param args - String arguments for the filter factory
     * @throws NullPointerException if either parameter is null
     */
    public FilterFactoryParams(Description topLevelDescription, String args);

    /**
     * Get the string arguments passed to the filter factory
     * @return Arguments string (may be empty, never null)
     */
    public String getArgs();

    /**
     * Get the description of all tests being filtered
     * @return Top-level description
     */
    public Description getTopLevelDescription();
}