1 files changed, 41 insertions, 5 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaTestRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaTestRule.java
index e9d44bebe8..c3c5b7558c 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaTestRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/java/BazelJavaTestRule.java
@@ -17,6 +17,7 @@ package com.google.devtools.build.lib.bazel.rules.java;
 import static com.google.devtools.build.lib.packages.Attribute.attr;
 import static com.google.devtools.build.lib.packages.BuildType.LABEL;
 import static com.google.devtools.build.lib.packages.BuildType.TRISTATE;
+import static com.google.devtools.build.lib.syntax.Type.BOOLEAN;
 import static com.google.devtools.build.lib.syntax.Type.STRING;
 
 import com.google.devtools.build.lib.analysis.BaseRuleClasses;
@@ -50,9 +51,45 @@ public final class BazelJavaTestRule implements RuleDefinition {
     return builder
         .requiresConfigurationFragments(JavaConfiguration.class, Jvm.class)
         .setImplicitOutputsFunction(BazelJavaRuleClasses.JAVA_BINARY_IMPLICIT_OUTPUTS)
-        .override(attr("main_class", STRING).value(JUNIT4_RUNNER))
         .override(attr("stamp", TRISTATE).value(TriState.NO))
+        .override(attr("use_testrunner", BOOLEAN).value(true))
         .override(attr(":java_launcher", LABEL).value(JavaSemantics.JAVA_LAUNCHER))
+        // TODO(dmarting): remove once we drop the legacy bazel java_test behavior.
+        .override(attr("main_class", STRING).value(JUNIT4_RUNNER))
+        /* <!-- #BLAZE_RULE(java_test).ATTRIBUTE(test_class) -->
+        The Java class to be loaded by the test runner.<br/>
+        ${SYNOPSIS}
+        <p>
+          By default, if this argument is not defined then the legacy mode is used and the
+          test arguments are used instead. Set the <code>--nolegacy_bazel_java_test</code> flag
+          to not fallback on the first argument.
+        </p>
+        <p>
+          This attribute specifies the name of a Java class to be run by
+          this test. It is rare to need to set this. If this argument is omitted, the Java class
+          whose name corresponds to the <code>name</code> of this
+          <code>java_test</code> rule will be used.
+        </p>
+        <p>
+          For JUnit3, the test class needs to either be a subclass of
+          <code>junit.framework.TestCase</code> or it needs to have a public
+          static <code>suite()</code> method that returns a
+          <code>junit.framework.Test</code> (or a subclass of <code>Test</code>).
+          For JUnit4, the class needs to be annotated with
+          <code>org.junit.runner.RunWith</code>.
+        </p>
+        <p>
+          This attribute allows several <code>java_test</code> rules to
+          share the same <code>Test</code>
+          (<code>TestCase</code>, <code>TestSuite</code>, ...).  Typically
+          additional information is passed to it
+          (e.g. via <code>jvm_flags=['-Dkey=value']</code>) so that its
+          behavior differs in each case, such as running a different
+          subset of the tests.  This attribute also enables the use of
+          Java tests outside the <code>javatests</code> tree.
+        </p>
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
+        .add(attr("test_class", STRING))
         .build();
   }
 
@@ -81,10 +118,9 @@ ${IMPLICIT_OUTPUTS}
 ${ATTRIBUTE_DEFINITION}
 
 <p>
-See the section on <a href="#java_binary_args">java_binary()</a> arguments, with the <i>caveat</i>
-that there is no <code>main_class</code> argument. This rule also supports all
-<a href="common-definitions.html#common-attributes-tests">attributes common to all test rules
-(*_test)</a>.
+See the section on <a href="#java_binary_args">java_binary()</a> arguments. This rule also
+supports all <a href="common-definitions.html#common-attributes-tests">attributes common
+to all test rules (*_test)</a>.
 </p>
 
 <h4 id="java_test_examples">Examples</h4>