PlatformTestStorage


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 functions

Unit

Adds the given properties.

String!
getInputArg(argName: String!)

Returns the value of a given argument name.

(Mutable)Map<String!, String!>!

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

Uri!

Provides a Uri to a test file dependency.

Uri!

Provides a Uri to a test output file.

(Mutable)Map<String!, Serializable!>!

Returns a map of all the output test properties.

Boolean

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

InputStream!
openInputFile(pathname: String!)

Provides an InputStream to a test file dependency.

OutputStream!
openOutputFile(pathname: String!)

Provides an OutputStream to a test output file.

OutputStream!
openOutputFile(pathname: String!, append: Boolean)

Provides an OutputStream to a test output file.

Public functions

addOutputProperties

fun addOutputProperties(properties: (Mutable)Map<String!, Serializable!>!): Unit

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

fun getInputArg(argName: String!): String!

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
argName: String!

the argument name. Should not be null.

getInputArgs

fun getInputArgs(): (Mutable)Map<String!, String!>!

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

See also
{@link

getInputFileUri

fun getInputFileUri(pathname: String): Uri!

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
pathname: String

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

fun getOutputFileUri(pathname: String): Uri!

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
pathname: String

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

fun getOutputProperties(): (Mutable)Map<String!, Serializable!>!

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

isTestStorageFilePath

fun isTestStorageFilePath(pathname: String): Boolean

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

Parameters
pathname: String

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

fun openInputFile(pathname: String!): InputStream!

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
pathname: String!

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

fun openOutputFile(pathname: String!): OutputStream!

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
pathname: String!

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

fun openOutputFile(pathname: String!, append: Boolean): OutputStream!

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
pathname: String!

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

append: Boolean

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