TestStorage

Artifact: androidx.test.services:storage

Kotlin |Java

@ExperimentalTestApi
class TestStorage : PlatformTestStorage

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

Summary

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

Public functions
`Unit`	`addOutputProperties(properties: (Mutable)Map<String!, Serializable!>!)` Adds the given properties.
`String!`	`getInputArg(argName: String)` Returns the value of a given argument name.
`(Mutable)Map<String!, String!>!`	`getInputArgs()` Returns the name/value map of all test arguments or an empty map if no arguments are defined.
`java-static Uri!`	`getInputFileUri(pathname: String)` Provides a Uri to a test file dependency.
`java-static Uri!`	`getOutputFileUri(pathname: String)` Provides a Uri to a test output file.
`(Mutable)Map<String!, Serializable!>!`	`getOutputProperties()` Returns a map of all the output test properties.
`java-static Boolean`	`isTestStorageFilePath(pathname: String)` Returns true if `pathname` corresponds to a file or directory that is in a directory where the storage service 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 constructors

TestStorage

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

TestStorage(contentResolver: ContentResolver)

Constructor.

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

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.

getInputArg

fun getInputArg(argName: String): String!

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

getInputFileUri

java-static 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 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

java-static 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 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

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

java-static fun isTestStorageFilePath(pathname: String): Boolean

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

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

fun openOutputFile(pathname: String): OutputStream!

Provides an OutputStream to a test output file.

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

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

Provides an OutputStream to a test output file.

Parameters
`pathname: String`	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.
`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`