Rule documentation for android_instrumentation_test

RELNOTES[NEW]: New Android device test rule: android_instrumentation_test.

PiperOrigin-RevId: 186067215

2 files changed, 86 insertions, 2 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidInstrumentationTestRule.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidInstrumentationTestRule.java
index c33d060953..d35ee6eba9 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidInstrumentationTestRule.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidInstrumentationTestRule.java
@@ -32,12 +32,23 @@ public class AndroidInstrumentationTestRule implements RuleDefinition {
   @Override
   public RuleClass build(Builder builder, RuleDefinitionEnvironment environment) {
     return builder
-        .setUndocumented()
+        /* <!-- #BLAZE_RULE(android_instrumentation_test).ATTRIBUTE(test_app) -->
+         The <a href="${link android_binary}">android_binary</a> target containing the test classes.
+         The <code>android_binary</code> target must specify which target it is testing through
+         its <a href="${link android_binary.instruments}"><code>instruments</code></a> attribute.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(
             attr("test_app", LABEL)
                 .mandatory()
                 .allowedFileTypes(FileTypeSet.NO_FILE)
                 .allowedRuleClasses("android_binary"))
+        /* <!-- #BLAZE_RULE(android_instrumentation_test).ATTRIBUTE(target_device) -->
+        <p>The <a href="${link android_device}">android_device</a> the test should run on.</p>
+        <p>To run the test on an emulator that is already running or on a physical device, use
+        these arguments:
+        <code>--test_output=streamed --test_arg=--device_broker_type=LOCAL_ADB_SERVER
+        --test_arg=--device_serial_number=$device_identifier</code></p>
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(
             attr("target_device", LABEL)
                 .mandatory()
@@ -45,12 +56,16 @@ public class AndroidInstrumentationTestRule implements RuleDefinition {
                 .cfg(HostTransition.INSTANCE)
                 .allowedFileTypes(FileTypeSet.NO_FILE)
                 .mandatoryProviders(AndroidDeviceBrokerInfo.PROVIDER.id()))
+        /* <!-- #BLAZE_RULE(android_instrumentation_test).ATTRIBUTE(support_apks) -->
+        Other APKs to install on the device before the instrumentation test starts.
+        <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(
             attr("support_apks", LABEL_LIST)
                 .allowedFileTypes(AndroidRuleClasses.APK)
                 .allowedRuleClasses("android_binary"))
         .add(
             attr("fixtures", LABEL_LIST)
+                .undocumented("Undocumented until the fixtures rules are documented")
                 .allowedFileTypes(FileTypeSet.NO_FILE)
                 .allowedRuleClasses(
                     "android_device_script_fixture", "android_host_service_fixture"))
@@ -77,3 +92,66 @@ public class AndroidInstrumentationTestRule implements RuleDefinition {
         .build();
   }
 }
+
+/*<!-- #BLAZE_RULE (NAME = android_instrumentation_test, TYPE = TEST, FAMILY = Android) -->
+
+<p>
+  An <code>android_instrumentation_test</code> rule runs Android instrumentation tests. It will
+  start an emulator, install the application being tested, the test application, and
+  any other needed applications, and run the tests defined in the test package.
+</p>
+<p>
+  The <a href="${link android_instrumentation_test.test_app}>test_app</a> attribute specifies the
+  <code>android_binary<code> which contains the test. This <code>android_binary</code> in turn
+  specifies the <code>android_binary</code> application under test through its
+  <a href="${link android_binary.instruments">instruments</a> attribute.
+</p>
+
+<h4 id="android_instrumentation_test_examples">Example</h4>
+
+<pre class="code">
+# java/com/samples/hello_world/BUILD
+
+android_library(
+    name = "hello_world_lib",
+    srcs = ["Lib.java"],
+    manifest = "LibraryManifest.xml",
+    resource_files = glob(["res/**"]),
+)
+
+# The app under test
+android_binary(
+    name = "hello_world_app",
+    manifest = "AndroidManifest.xml",
+    deps = [":hello_world_lib"],
+)
+</pre>
+
+<pre class="code">
+# javatests/com/samples/hello_world/BUILD
+
+android_library(
+    name = "hello_world_test_lib",
+    srcs = ["Tests.java"],
+    deps = [
+      "//java/com/samples/hello_world:hello_world_lib",
+      ...  # test dependencies such as Espresso and Mockito
+    ],
+)
+
+# The test app
+android_binary(
+    name = "hello_world_test_app",
+    instruments = "//java/com/samples/hello_world:hello_world_app",
+    manifest = "AndroidManifest.xml",
+    deps = ["hello_world_test_lib"],
+)
+
+android_instrumentation_test(
+    name = "hello_world_uiinstrumentation_tests",
+    target_device = ":some_target_device",
+    test_app = ":hello_world_test_app",
+)
+</pre>
+
+<!-- #END_BLAZE_RULE -->*/
diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidRuleClasses.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidRuleClasses.java
index 81615d0857..cfec36c636 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidRuleClasses.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidRuleClasses.java
@@ -1022,9 +1022,15 @@ public final class AndroidRuleClasses {
                   .cfg(HostTransition.INSTANCE)
                   .exec()
                   .value(env.getToolsLabel("//tools/android:resource_extractor")))
+          /* <!-- #BLAZE_RULE(android_binary).ATTRIBUTE(instruments) -->
+          <p>The <code>android_binary</code> target to instrument.</p>
+          <p>If this attribute is set, this <code>android_binary</code> will be treated as a test
+          application for instrumentation tests. An <code>android_instrumentation_test</code>
+          target can then specify this target in its
+           <a href="${link android_instrumentation_test.test_app}">test_app</a> attribute.
+          <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
           .add(
               attr("instruments", LABEL)
-                  .undocumented("blocked by android_instrumentation_test")
                   .allowedRuleClasses("android_binary")
                   .allowedFileTypes(NO_FILE))
           .add(