Test storage API cleanup.

Make API changes as discussed in review:
- Make PlatformTestStorage public
- Make the default implementation FileTestStorage instead of a no-op
- Modify FileTestStorage implementation to:
   - read input files from disk instead of assets
   - remove support for reading from absolute paths, as that contradicts the PlatformTestStorage spec
- Add more documentation on usage across build environments
- Make TestStorage a restricted-to-androidx.test usage API

PiperOrigin-RevId: 627524599

Author: brettchabot

runner/monitor/CHANGELOG.md

@@ -12,10 +12,7 @@
 
 **API Changes**
 * Make DeviceController an public API from ExperimentalTestApi
-* Upstream TestStorage.isTestStoragePath to PlatformTestStorage
-* Upstream TestStorage.getInputFileUri and getOutputFileUri  to PlatformTestStorage
-* Change PlatformTestStorage methods to throw FileNotFoundException instead of 
-  IOException
+* Move PlatformTestStorage to a public API
 * Add internal ControlledLooper#isDrawCallbacksSupported.
 
 **Breaking API Changes**

runner/monitor/java/androidx/test/api/current_internal.txt

@@ -213,6 +213,29 @@ package androidx.test.platform.concurrent {
 
 }
 
+package androidx.test.platform.io {
+
+  @RestrictTo(androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP) public final class FileTestStorage implements androidx.test.platform.io.PlatformTestStorage {
+    ctor public FileTestStorage();
+    method public void addOutputProperties(java.util.Map<java.lang.String!,java.io.Serializable!>!);
+    method public String! getInputArg(String!);
+    method public java.util.Map<java.lang.String!,java.lang.String!>! getInputArgs();
+    method public android.net.Uri! getInputFileUri(String);
+    method public android.net.Uri! getOutputFileUri(String);
+    method public java.util.Map<java.lang.String!,java.io.Serializable!>! getOutputProperties();
+    method public boolean isTestStorageFilePath(String);
+    method public java.io.InputStream! openInputFile(String!) throws java.io.FileNotFoundException;
+    method public java.io.OutputStream! openOutputFile(String!) throws java.io.FileNotFoundException;
+    method public java.io.OutputStream! openOutputFile(String!, boolean) throws java.io.FileNotFoundException;
+  }
+
+  public interface PlatformTestStorage {
+    method @RestrictTo(androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP) public default java.io.InputStream! openInternalInputFile(String!) throws java.io.FileNotFoundException;
+    method @RestrictTo(androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP) public default java.io.OutputStream! openInternalOutputFile(String!) throws java.io.FileNotFoundException;
+  }
+
+}
+
 package androidx.test.platform.tracing {
 
   @RestrictTo(androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP) public interface Tracer {

runner/monitor/java/androidx/test/api/current_public.txt

@@ -63,6 +63,28 @@ package androidx.test.platform.graphics {
 
 }
 
+package androidx.test.platform.io {
+
+  public interface PlatformTestStorage {
+    method public void addOutputProperties(java.util.Map<java.lang.String!,java.io.Serializable!>!);
+    method public String! getInputArg(String!);
+    method public java.util.Map<java.lang.String!,java.lang.String!>! getInputArgs();
+    method public android.net.Uri! getInputFileUri(String);
+    method public android.net.Uri! getOutputFileUri(String);
+    method public java.util.Map<java.lang.String!,java.io.Serializable!>! getOutputProperties();
+    method public boolean isTestStorageFilePath(String);
+    method public java.io.InputStream! openInputFile(String!) throws java.io.FileNotFoundException;
+    method public java.io.OutputStream! openOutputFile(String!) throws java.io.FileNotFoundException;
+    method public java.io.OutputStream! openOutputFile(String!, boolean) throws java.io.FileNotFoundException;
+  }
+
+  public final class PlatformTestStorageRegistry {
+    method public static androidx.test.platform.io.PlatformTestStorage! getInstance();
+    method public static void registerInstance(androidx.test.platform.io.PlatformTestStorage!);
+  }
+
+}
+
 package androidx.test.platform.ui {
 
   public class InjectEventSecurityException extends java.lang.Exception implements androidx.test.platform.TestFrameworkException {

runner/monitor/java/androidx/test/platform/io/FileTestStorage.java

@@ -19,13 +19,13 @@
 import android.os.Bundle;
 import android.util.Log;
 import androidx.annotation.NonNull;
-import androidx.test.annotation.ExperimentalTestApi;
+import androidx.annotation.RestrictTo;
+import androidx.annotation.RestrictTo.Scope;
 import androidx.test.platform.app.InstrumentationRegistry;
 import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileNotFoundException;
 import java.io.FileOutputStream;
-import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.io.Serializable;
@@ -34,41 +34,35 @@
 import java.util.Map;
 
 /**
- * A class that reads/writes the runner data using the raw file system.
+ * An implementation of {@link PlatformTestStorage} that reads and writes test data to the test
+ * process's local storage.
  *
- * <p>This API is experimental and is subject to change or removal in future releases.
+ * <p>Typically the test runner infrastructure will configure where test data is stored and
+ * retrieved from by passing 'additionalTestOutputDir' and 'testInputDir' instrumentation arguments.
+ * If these arguments are not provided, the implementation will choose an appropriate location based
+ * on android API level that minimizes the need for any extra permissions. See TestDirCalculator.
+ *
+ * @hide
  */
-@ExperimentalTestApi
+@RestrictTo(Scope.LIBRARY_GROUP)
 public final class FileTestStorage implements PlatformTestStorage {
 
   private static final String TAG = FileTestStorage.class.getSimpleName();
-  private final OutputDirCalculator outputDirCalculator;
+  private final TestDirCalculator testDirCalculator;
 
   public FileTestStorage() {
-    outputDirCalculator = new OutputDirCalculator();
+    testDirCalculator = new TestDirCalculator();
   }
 
   /**
    * Provides an InputStream to a test file dependency.
    *
-   * @param pathname path to the test file dependency. Should not be null. Can be either a relative
-   *     or absolute path. If relative, the implementation will read the input file from the test
-   *     apk's asset directory
+   * @param pathname relative path to the test file dependency. Should not be null.
    */
   @Override
   public InputStream openInputFile(String pathname) throws FileNotFoundException {
-    File inputFile = new File(pathname);
-    if (inputFile.isAbsolute()) {
-      return new FileInputStream(inputFile);
-    }
-    try {
-      return InstrumentationRegistry.getInstrumentation().getContext().getAssets().open(pathname);
-    } catch (IOException e) {
-      FileNotFoundException fe =
-          new FileNotFoundException(String.format("failed to open %s from apk assets", pathname));
-      fe.initCause(e);
-      throw fe;
-    }
+    File inputFile = new File(testDirCalculator.getInputDir(), pathname);
+    return new FileInputStream(inputFile);
   }
 
   /**
@@ -85,11 +79,14 @@ public OutputStream openOutputFile(String pathname) throws FileNotFoundException
 
   @Override
   public OutputStream openOutputFile(String pathname, boolean append) throws FileNotFoundException {
-    File outputFile = new File(pathname);
-    if (!outputFile.isAbsolute()) {
-      outputFile = new File(outputDirCalculator.getOutputDir(), pathname);
-    }
+    File outputFile = new File(testDirCalculator.getOutputDir(), pathname);
     Log.d("FileTestStorage", "openOutputFile from " + outputFile.getAbsolutePath());
+    if (!outputFile.getParentFile().exists()) {
+      if (!outputFile.getParentFile().mkdirs()) {
+        throw new FileNotFoundException(
+            "Failed to create output dir " + outputFile.getParentFile().getAbsolutePath());
+      }
+    }
     return new FileOutputStream(outputFile, append);
   }
 
@@ -153,21 +150,19 @@ public OutputStream openInternalOutputFile(String pathname) throws FileNotFoundE
 
   @Override
   public Uri getInputFileUri(@NonNull String pathname) {
-    throw new UnsupportedOperationException();
+    File inputFile = new File(testDirCalculator.getInputDir(), pathname);
+    return Uri.fromFile(inputFile);
   }
 
   @Override
   public Uri getOutputFileUri(@NonNull String pathname) {
-    File outputFile = new File(pathname);
-    if (!outputFile.isAbsolute()) {
-      outputFile = new File(outputDirCalculator.getOutputDir(), pathname);
-    }
+    File outputFile = new File(testDirCalculator.getOutputDir(), pathname);
     return Uri.fromFile(outputFile);
   }
 
   @Override
   public boolean isTestStorageFilePath(@NonNull String pathname) {
-    String outputDir = outputDirCalculator.getOutputDir().getAbsolutePath();
+    String outputDir = testDirCalculator.getOutputDir().getAbsolutePath();
     return pathname.startsWith(outputDir);
   }
 }

runner/monitor/java/androidx/test/platform/io/PlatformTestStorage.java

@@ -17,61 +17,89 @@
 
 import android.net.Uri;
 import androidx.annotation.NonNull;
-import androidx.test.annotation.ExperimentalTestApi;
+import androidx.annotation.RestrictTo;
+import androidx.annotation.RestrictTo.Scope;
+import androidx.test.platform.app.InstrumentationRegistry;
 import java.io.FileNotFoundException;
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.io.Serializable;
 import java.util.Map;
 
 /**
- * An interface represents on-device I/O operations in an Android test.
+ * An interface representing on-device I/O operations in an Android test.
  *
- * <p>This is a low level API, typically used by higher level test frameworks. It is generally not
- * recommended for direct use by most tests.
+ * <p>This API allows users to retrieve test data specified in the build configuration, and write
+ * output test data that can be automatically collected by the test runner infrastructure, if the
+ * environment supports it.
  *
- * <p>Use a concrete implementation class of this interface if you need to read/write files in your
- * tests. For example, in an Android Instrumentation test, use {@code
- * androidx.test.services.storage.TestStorage} when the test services is installed on the device.
+ * <p>Typically users will retrieve the appropriate implementation via {@link
+ * PlatformTestStorageRegistry#getInstance()}.
  *
- * <p>This API is experimental and is subject to change or removal in future releases.
+ * <p>Implementers would need to also implement the appropriate test runner support for pushing and
+ * pulling the test data to and from the device from the build environment.
  */
-@ExperimentalTestApi
 public interface PlatformTestStorage {
 
   /**
    * Provides an InputStream to a test file dependency.
    *
-   * @param pathname path to the test file dependency. Should not be null.
-   * @return an InputStream to the given test file.
+   * <p>In bazel/blaze environments, this corresponds to files passed in the 'data' attribute of the
+   * android_instrumentation_test or android_local_test build rule.
+   *
+   * <p>This API is currently not supported in gradle environments.
+   *
+   * @param pathname the path to the test file dependency, relative to the root where the storage
+   *     implementation stores input files. Should not be null.
+   * @return a potentially unbuffered InputStream to the given test file. Users will typically want
+   *     to buffer the input in memory when reading from this stream.
    * @throws FileNotFoundException if pathname does not exist
    */
   InputStream openInputFile(String pathname) throws FileNotFoundException;
 
   /**
    * Returns the value of a given argument name.
    *
+   * <p>In bazel/blaze environments, this corresponds to flags passed in the 'args' attribute of the
+   * android_instrumentation_test or android_local_test build rule.
+   *
+   * <p>This API is currently unsupported in gradle environments. It is recommended to use {@link
+   * InstrumentationRegistry#getArguments()} as an alternative.
+   *
    * @param argName the argument name. Should not be null.
    */
   String getInputArg(String argName);
 
   /**
    * Returns the name/value map of all test arguments or an empty map if no arguments are defined.
+   *
+   * @see {@link #getInputArg(String)}
    */
   Map<String, String> getInputArgs();
 
   /**
-   * Provides an OutputStream to a test output file.
+   * Provides an OutputStream to a test output file. Will overwrite any data written to the same
+   * pathname in the same test run.
    *
-   * @param pathname path to the test output file. Should not be null.
-   * @return an OutputStream to the given output file.
+   * <p>Supported test runners will pull the files from the device once the test completes.
+   *
+   * <p>In gradle android instrumentation test environments, the files will typically be stored in
+   * path_to_your_project/module_name/build/outputs/managed_device_android_test_additional_output
+   * <br>
+   *
+   * @param pathname relative path to the test output file. Should not be null.
+   * @return a potentially unbuffered OutputStream to the given output file. Users will typically
+   *     want to buffer the output in memory when writing to this stream.
    * @throws FileNotFoundException if pathname does not exist
    */
   OutputStream openOutputFile(String pathname) throws FileNotFoundException;
 
   /**
    * Provides an OutputStream to a test output file.
    *
+   * <p>This API is identical to {@link #openOutputFile(String)} with the additional feature of
+   * allowing appending or overwriting test data.
+   *
    * @param pathname path to the test output file. Should not be null.
    * @param append if true, then the lines will be added to the end of the file rather than
    *     overwriting.
@@ -85,6 +113,8 @@ public interface PlatformTestStorage {
    *
    * <p>Adding a property with the same name would append new values and overwrite the old values if
    * keys already exist.
+   *
+   * <p>This API is unsupported in gradle environments. <br>
    */
   void addOutputProperties(Map<String, Serializable> properties);
 
@@ -100,7 +130,9 @@ public interface PlatformTestStorage {
    * @param pathname path to the internal file. Should not be null.
    * @return an InputStream to the given test file.
    * @throws FileNotFoundException if pathname does not exist
+   * @hide
    */
+  @RestrictTo(Scope.LIBRARY_GROUP)
   default InputStream openInternalInputFile(String pathname) throws FileNotFoundException {
     return openInputFile(pathname);
   }
@@ -111,7 +143,9 @@ default InputStream openInternalInputFile(String pathname) throws FileNotFoundEx
    * @param pathname path to the internal file. Should not be null.
    * @return an OutputStream to the given output file.
    * @throws FileNotFoundException if pathname does not exist
+   * @hide
    */
+  @RestrictTo(Scope.LIBRARY_GROUP)
   default OutputStream openInternalOutputFile(String pathname) throws FileNotFoundException {
     return openOutputFile(pathname);
   }
@@ -123,11 +157,9 @@ default OutputStream openInternalOutputFile(String pathname) throws FileNotFound
    * InputStream to the input file content immediately. Only use this method if you would like to
    * store the file Uri and use it for I/O operations later.
    *
-   * <p><b>Note:</b> temporary API - will be renamed to getInpFileUri in future
-   *
    * @param pathname path to the test file dependency. Should not be null. This is a relative path
-   *     to where the storage service stores the input files. For example, if the storage service
-   *     stores the input files under "/sdcard/test_input_files", with a pathname
+   *     to where the storage implementation stores the input files. For example, if the storage
+   *     service stores the input files under "/sdcard/test_input_files", with a pathname
    *     "/path/to/my_input.txt", the file will end up at
    *     "/sdcard/test_input_files/path/to/my_input.txt" on device.
    * @return a content Uri to the test file dependency.
@@ -142,19 +174,17 @@ default OutputStream openInternalOutputFile(String pathname) throws FileNotFound
    * OutputStream to the output file content immediately. Only use this method if you would like to
    * store the file Uri and use it for I/O operations later.
    *
-   * <p><b>Note:</b> temporary API - will be renamed to getOutputFileUri in future
-   *
    * @param pathname path to the test output file. Should not be null. This is a relative path to
-   *     where the storage service stores the output files. For example, if the storage service
-   *     stores the output files under "/sdcard/test_output_files", with a pathname
+   *     where the storage implementation stores the output files. For example, if the storage
+   *     service stores the output files under "/sdcard/test_output_files", with a pathname
    *     "/path/to/my_output.txt", the file will end up at
    *     "/sdcard/test_output_files/path/to/my_output.txt" on device.
    */
   Uri getOutputFileUri(@NonNull String pathname);
 
   /**
    * Returns true if {@code pathname} corresponds to a file or directory that is in a directory
-   * where the storage stores files.
+   * where the storage implementation stores files.
    *
    * @param pathname path to a file or directory. Should not be null. This is an absolute path to a
    *     file that may be a part of the storage service.