TestStorage

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

@NonNull
public void addOutputProperties(
    @NonNull Map<@NonNull String, @NonNull 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

@NonNull
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

@NonNull
public Map<@NonNull String, @NonNull String> getInputArgs()

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

getInputFileUri

@NonNull
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

@NonNull
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

@NonNull
public Map<@NonNull String, @NonNull Serializable> getOutputProperties()

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

openInputFile

@NonNull
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

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

openOutputFile

@NonNull
public OutputStream openOutputFile(@NonNull String pathname, @NonNull 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.
`@NonNull 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.