Source code
package org.junit.runners.model;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import org.junit.internal.runners.ErrorReportingRunner;
import org.junit.runner.Runner;
/**
* A RunnerBuilder is a strategy for constructing runners for classes.
*
* Only writers of custom runners should use <code>RunnerBuilder</code>s. A custom runner class with a constructor taking
* a <code>RunnerBuilder</code> parameter will be passed the instance of <code>RunnerBuilder</code> used to build that runner itself.
* For example,
* imagine a custom runner that builds suites based on a list of classes in a text file:
*
* <pre>
* \@RunWith(TextFileSuite.class)
* \@SuiteSpecFile("mysuite.txt")
* class MySuite {}
* </pre>
*
* The implementation of TextFileSuite might include:
*
* <pre>
* public TextFileSuite(Class testClass, RunnerBuilder builder) {
* // ...
* for (String className : readClassNames())
* addRunner(builder.runnerForClass(Class.forName(className)));
* // ...
* }
* </pre>
*
* @see org.junit.runners.Suite
* @since 4.5
*/
public abstract class RunnerBuilder {
private final Set<Class<?>> parents = new HashSet<Class<?>>();
/**
* Override to calculate the correct runner for a test class at runtime.
*
* @param testClass class to be run
* @return a Runner
* @throws Throwable if a runner cannot be constructed
*/
public abstract Runner runnerForClass(Class<?> testClass) throws Throwable;
/**
* Always returns a runner, even if it is just one that prints an error instead of running tests.
*
* @param testClass class to be run
* @return a Runner
*/
public Runner safeRunnerForClass(Class<?> testClass) {
try {
return runnerForClass(testClass);
} catch (Throwable e) {
return new ErrorReportingRunner(testClass, e);
}
}
Class<?> addParent(Class<?> parent) throws InitializationError {
if (!parents.add(parent)) {
throw new InitializationError(String.format("class '%s' (possibly indirectly) contains itself as a SuiteClass", parent.getName()));
}
return parent;
}
void removeParent(Class<?> klass) {
parents.remove(klass);
}
/**
* Constructs and returns a list of Runners, one for each child class in
* {@code children}. Care is taken to avoid infinite recursion:
* this builder will throw an exception if it is requested for another
* runner for {@code parent} before this call completes.
*/
public List<Runner> runners(Class<?> parent, Class<?>[] children)
throws InitializationError {
addParent(parent);
try {
return runners(children);
} finally {
removeParent(parent);
}
}
public List<Runner> runners(Class<?> parent, List<Class<?>> children)
throws InitializationError {
return runners(parent, children.toArray(new Class<?>[0]));
}
private List<Runner> runners(Class<?>[] children) {
ArrayList<Runner> runners = new ArrayList<Runner>();
for (Class<?> each : children) {
Runner childRunner = safeRunnerForClass(each);
if (childRunner != null) {
runners.add(childRunner);
}
}
return runners;
}
}
Run 1
This JUnit RunnerBuilder class demonstrates strong readability. The structure is logical, with clear separation of public API methods, protected internals, and a private helper. Nesting is minimal — a try/finally and a simple loop are the only nested blocks. Method names like safeRunnerForClass, addParent, and removeParent clearly convey intent. The code is concise without sacrificing clarity, using early returns and collection methods effectively. Action granularity is generally good, with one logical step per line. The reading flow is natural: fields, abstract method, safe wrapper, parent-tracking methods, then public runners methods followed by the private implementation. Javadoc is helpful but not excessive. Minor deductions include the slightly dense error message formatting and the overloaded runners methods requiring readers to track which version is called, but overall this is very readable production code.
Run 2
The code is well-structured with clear separation of public API and private helpers. Javadoc explains intent thoroughly. Nesting is minimal (one try/finally, one loop, one conditional). Action granularity is appropriate, with one logical operation per line. The recursive parent-tracking logic is concise and the flow is natural: public methods delegate to private helpers cleanly. Minor deductions: the overloaded runners methods create slight indirection, and the private runners(Class<?>[]) method could be named more explicitly (e.g., buildRunners). Overall, highly readable with strong clarity of intent.
Run 3
The code is well-structured and highly readable. It follows a logical organization, with clear separation between public API methods, helper methods, and private implementation. Nesting is minimal; the only nested block is a try-finally in the 'runners' method, which is appropriate for resource cleanup. Intent is clear from method names and Javadoc comments, especially for 'safeRunnerForClass' and 'runners'. The code is concise—no unnecessary verbosity—and each method performs a single, focused action. Action granularity is good, with one meaningful operation per line in most cases. Reading flow is natural: the class starts with a field, then abstract method, then public methods flowing from high-level to lower-level helpers. The only minor issue is the duplicate 'runners' overloads and use of raw array types, which slightly increases complexity, but overall the code is clean, maintainable, and easy to follow.
Run 1
Code Structure: Well-organized, focused methods separate runner construction, error handling, and recursion tracking. Nesting: Shallow control flow; only the loop's null check adds nesting. Clarity of intent: Descriptive method names and useful documentation explain the strategy and cycle prevention, though names like 'each' and 'klass' are less precise. The claim that safeRunnerForClass always returns a runner conflicts with the later null check. Code length: Implementation is concise, although the introductory documentation is lengthy and the exception statement could be wrapped. Action granularity: Most lines perform one action; addParent combines set insertion and a condition, slightly increasing interpretation effort. Reading flow: Consistent formatting and straightforward delegation make execution easy to follow, with try/finally clearly expressing cleanup.
Run 2
Code Structure: Well-organized, focused methods separate runner construction, error handling, recursion prevention, and collection processing. Nesting: Shallow overall; only the loop with a null check adds modest nesting. Clarity of intent: Descriptive method names and useful Javadoc explain the strategy and recursion safeguards. However, 'parents', 'klass', and 'each' could be more specific, and the claim that safeRunnerForClass always returns a runner conflicts with the later null check. Code length: Implementation is concise, though introductory documentation is lengthy and one exception-construction line is overly long. Action granularity: Most lines perform one clear action; combining set insertion with a conditional slightly obscures the state change. Reading flow: Methods follow a natural progression, overloads delegate cleanly, and try/finally makes cleanup easy to follow.
Run 3
Code Structure: Small, focused methods logically separate runner construction, error handling, and recursion protection. Nesting: Shallow overall; only the collection loop contains a nested conditional. Clarity of intent: Descriptive method names and documentation make the strategy clear, though 'parents', 'klass', and 'each' are less precise, and the promise that safeRunnerForClass always returns a runner conflicts with the later null check. Code length: Implementation is concise; introductory documentation is lengthy but useful, while one exception-construction line is overly long. Action granularity: Most lines perform one action, although addParent combines set mutation with a conditional check. Reading flow: Consistent formatting and delegation provide a natural progression, with try/finally clearly communicating cleanup.