TestStorage

Artifact: androidx.test.services:storage

Kotlin |Java

@ExperimentalTestApi
public final class TestStorage implements PlatformTestStorage

Provides convenient I/O operations for reading/writing testing relevant files, properties in a test.

Summary

Public constructors
`TestStorage()` Default constructor.
`TestStorage(@NonNull ContentResolver contentResolver)` Constructor.

Public methods
`void`	`addOutputProperties(Map<String, Serializable> properties)` Adds the given properties.
`String`	`getInputArg(@NonNull String argName)` Returns the value of a given argument name.
`Map<String, String>`	`getInputArgs()` Returns the name/value map of all test arguments or an empty map if no arguments are defined.
`static Uri`	`getInputFileUri(@NonNull String pathname)` Provides a Uri to a test file dependency.
`static Uri`	`getOutputFileUri(@NonNull String pathname)` Provides a Uri to a test output file.
`Map<String, Serializable>`	`getOutputProperties()` Returns a map of all the output test properties.
`static boolean`	`isTestStorageFilePath(@NonNull String pathname)` Returns true if `pathname` corresponds to a file or directory that is in a directory where the storage service stores files.
`InputStream`	`openInputFile(@NonNull String pathname)` Provides an InputStream to a test file dependency.
`OutputStream`	`openOutputFile(@NonNull String pathname)` Provides an OutputStream to a test output file.
`OutputStream`	`openOutputFile(@NonNull String pathname, boolean append)` Provides an OutputStream to a test output file.

Public constructors

TestStorage

public TestStorage()

Default constructor.

This class is supposed to be used mostly in the Instrumentation process, e.g. in an Android Instrumentation test. Thus by default, we use the content resolver of the app under test as the one to resolve a URI in this storage service.

TestStorage

public TestStorage(@NonNull ContentResolver contentResolver)

Constructor.

Parameters
`@NonNull ContentResolver contentResolver`	the content resolver that shall be used to resolve a URI in the test storage service. Should not be null.

Public methods

addOutputProperties

public 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.

getInputArg

public String getInputArg(@NonNull String argName)

Returns the value of a given argument name.

There should be one and only one argument defined with the given argument name. Otherwise, it will throw a TestStorageException if zero or more than one arguments are found.

We suggest using some naming convention when defining the argument name to avoid possible conflict, e.g. defining "namespaces" for your arguments which helps clarify how the argument is used and also its scope. For example, for arguments used for authentication purposes, you could name the account email argument as something like "google_account.email" and its password as "google_account.password".

Parameters
`@NonNull String argName`	the argument name. Should not be null.

getInputArgs

public Map<String, String> getInputArgs()

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

getInputFileUri

public static 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 service 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.

getOutputFileUri

public static 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 service 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

public Map<String, Serializable> getOutputProperties()

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

isTestStorageFilePath

public static boolean isTestStorageFilePath(@NonNull String pathname)

Returns true if pathname corresponds to a file or directory that is in a directory where the storage service 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

public InputStream openInputFile(@NonNull String pathname)

Provides an InputStream to a test file dependency.

Parameters
`@NonNull String 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 "/path/to/my_input.txt", the file will end up at "/sdcard/test_input_files/path/to/my_input.txt" on device.

Returns
`InputStream`	an InputStream to the given test file.

Throws
`java.io.FileNotFoundException`	if pathname does not exist

openOutputFile

public OutputStream openOutputFile(@NonNull String pathname)

Provides an OutputStream to a test output file.

Parameters
`@NonNull String 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 "/path/to/my_output.txt", the file will end up at "/sdcard/test_output_files/path/to/my_output.txt" on device.

Returns
`OutputStream`	an OutputStream to the given output file.

Throws
`java.io.FileNotFoundException`

openOutputFile

public OutputStream openOutputFile(@NonNull String pathname, boolean append)

Provides an OutputStream to a test output file.

Parameters
`@NonNull String 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 "/path/to/my_output.txt", the file will end up at "/sdcard/test_output_files/path/to/my_output.txt" on device.
`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`