PlatformTestStorage

Kotlin |Java

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`	`addOutputProperties(Map<String, Serializable> properties)` Adds the given properties.
`abstract String`	`getInputArg(String argName)` Returns the value of a given argument name.
`abstract Map<String, String>`	`getInputArgs()` Returns the name/value map of all test arguments or an empty map if no arguments are defined.
`abstract Uri`	`getInputFileUri(@NonNull String pathname)` Provides a Uri to a test file dependency.
`abstract Uri`	`getOutputFileUri(@NonNull String pathname)` Provides a Uri to a test output file.
`abstract Map<String, Serializable>`	`getOutputProperties()` Returns a map of all the output test properties.
`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.
`abstract InputStream`	`openInputFile(String pathname)` Provides an InputStream to a test file dependency.
`abstract OutputStream`	`openOutputFile(String pathname)` 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
`getInputArg`	`getInputArg`

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

Returns
`Uri`	a content Uri to the test file dependency. Note: temporary API - will be renamed to getInputFileUri in future

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