PlatformTestStorage

public interface PlatformTestStorage

An interface representing on-device I/O operations in an Android test.

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.

Typically users will retrieve the appropriate implementation via getInstance.

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.

Summary

Public methods
abstract void

Adds the given properties.
abstract String

Returns the value of a given argument name.
abstract Map<String, String>

Returns the name/value map of all test arguments or an empty map if no arguments are defined.
abstract Uri

Provides a Uri to a test file dependency.
abstract Uri

Provides a Uri to a test output file.
abstract Map<String, Serializable>

Returns a map of all the output test properties.
abstract boolean

Returns true if pathname corresponds to a file or directory that is in a directory where the storage implementation stores files.
abstract InputStream

Provides an InputStream to a test file dependency.
abstract OutputStream

Provides an OutputStream to a test output file.
abstract OutputStream
openOutputFile(String pathname, boolean append)

Provides an OutputStream to a test output file.

Public methods

addOutputProperties

abstract void addOutputProperties(Map<String, Serializable> properties)

Adds the given properties.

Adding a property with the same name would append new values and overwrite the old values if keys already exist.

This API is unsupported in gradle environments.

getInputArg

abstract String getInputArg(String argName)

Returns the value of a given argument name.

In bazel/blaze environments, this corresponds to flags passed in the 'args' attribute of the android_instrumentation_test or android_local_test build rule.

This API is currently unsupported in gradle environments. It is recommended to use getArguments as an alternative.

Parameters
String argName

the argument name. Should not be null.

getInputArgs

abstract Map<String, String> getInputArgs()

Returns the name/value map of all test arguments or an empty map if no arguments are defined.

See also
{@link

getInputFileUri

abstract Uri getInputFileUri(@NonNull String pathname)

Provides a Uri to a test file dependency.

In most of the cases, you would use openInputFile for opening up an 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.

Parameters
@NonNull String pathname

path to the test file dependency. Should not be null. This is a relative path 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.
Returns
Uri

a content Uri to the test file dependency.

Note: temporary API - will be renamed to getInputFileUri in future

getOutputFileUri

abstract Uri getOutputFileUri(@NonNull String pathname)

Provides a Uri to a test output file.

In most of the cases, you would use openOutputFile for opening up an 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.

Parameters
@NonNull String pathname

path to the test output file. Should not be null. This is a relative path to 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.

getOutputProperties

abstract Map<String, Serializable> getOutputProperties()

Returns a map of all the output test properties. If no properties exist, an empty map will be returned.

isTestStorageFilePath

abstract boolean isTestStorageFilePath(@NonNull String pathname)

Returns true if pathname corresponds to a file or directory that is in a directory where the storage implementation stores files.

Parameters
@NonNull String 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.

openInputFile

abstract InputStream openInputFile(String pathname)

Provides an InputStream to a test file dependency.

In bazel/blaze environments, this corresponds to files passed in the 'data' attribute of the android_instrumentation_test or android_local_test build rule.

This API is currently not supported in gradle environments.

Parameters
String pathname

the path to the test file dependency, relative to the root where the storage implementation stores input files. Should not be null.
Returns
InputStream

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
java.io.FileNotFoundException

if pathname does not exist

openOutputFile

abstract OutputStream openOutputFile(String pathname)

Provides an OutputStream to a test output file. Will overwrite any data written to the same pathname in the same test run.

Supported test runners will pull the files from the device once the test completes.

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

Parameters
String pathname

relative path to the test output file. Should not be null.
Returns
OutputStream

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
java.io.FileNotFoundException

if pathname does not exist

openOutputFile

abstract OutputStream openOutputFile(String pathname, boolean append)

Provides an OutputStream to a test output file.

This API is identical to openOutputFile with the additional feature of allowing appending or overwriting test data.

Parameters
String pathname

path to the test output file. Should not be null.
boolean append

if true, then the lines will be added to the end of the file rather than overwriting.
Returns
OutputStream

an OutputStream to the given output file.
Throws
java.io.FileNotFoundException

if pathname does not exist