ShellProcess
public final class ShellProcess implements AutoCloseable
Represents a process that is running sh as a shell user.
Opposite to Shell this class doesn't handle the concept of command, rather it allows to read and write in the process streams, i.e. stdin, stdout, stderr. For example, using ShellProcess, it's possible to write a file in shell space like /data/local/tmp launching cp /dev/stdin /data/local/tmp/myfile:
ShellProcess.create().use {
// Writing a file
it.write("cp /dev/stdin /data/local/tmp/myfile")
it.stdin.write(myByteByffer)
// Reading a file
it.write("cat /data/local/tmp/somefile")
assert(it.stdout.bufferedReader().readLine() == "This is a test")
}For the vast majority of commands used for testing, Shell process is a better candidate and automatically captures the full command output, as opposed to ShellProcess that doesn't distinguish where a command ends and another starts.
Note that this class is not thread safe due to internal state changes, although streams can be read or written by another thread, as long as it's always the same. For example it's possible to read ShellProcess.stdOut from another thread, as long as this doesn't change later.
ShellProcess should be used only when access to streams is required, like in the above example.
Summary
Public methods |
|
|---|---|
void |
close()Closes the current process. |
static final @NonNull ShellProcess |
create(Creates a new |
final @NonNull InputStream |
An |
final @NonNull OutputStream |
getStdIn()An |
final @NonNull InputStream |
An |
final boolean |
isClosed()Returns whether the process is closed. |
final void |
Writes a string in the process standard input. |
Public methods
close
public void close()
Closes the current process. Internally this simply sends the shell process the exit command. This means that the process is not immediately terminated, but gracefully shutdown finishing prior commands execution. Once a shell process is closed, further calls to close don't have any effect, as the androidx.test.shell.ShellProcess.stdIn will be closed after the first one.
create
public static final @NonNull ShellProcess create(
int baseTcpPort,
int stdOutBufferSize,
int stdErrBufferSize,
int connectToNativeProcessTimeoutMs,
boolean nativeLogs
)
Creates a new ShellProcess.
Shell process connects to an internal native utility via tcp. The given base port and the two following ones are used.
| Parameters | |
|---|---|
int baseTcpPort |
a base tcp port to use to communicate with the native utility. Note that the given port and the 2 following ones are used. |
int stdOutBufferSize |
the size of the circular buffer where to store the stdout of the running shell process. |
int stdErrBufferSize |
the size of the circular buffer where to store the stderr of the running shell process. |
int connectToNativeProcessTimeoutMs |
timeout in ms to connect to the native process. |
boolean nativeLogs |
whether the native cli process should print Android logs. The tag used on logcat is |
| Returns | |
|---|---|
@NonNull ShellProcess |
a running shell process, ready to accept commands. |
| Throws | |
|---|---|
java.io.IOException |
if the underlying native utility does not start. |
getStdErr
public final @NonNull InputStream getStdErr()
An InputStream for the process standard error. Note that this is a circular buffer and is capped by the given stdOutBufferSize. When the buffer is full, the kernel has an an additional 64Kb of buffer. When also that is full, the shell process may stop until some buffer becomes a available. If a large output is expected but it's not important to capture it, a shell command may be launched piping in /dev/null.
For example:
cat large_file 2> /dev/null
getStdIn
public final @NonNull OutputStream getStdIn()
An OutputStream for the process standard output.
getStdOut
public final @NonNull InputStream getStdOut()
An InputStream for the process standard output. Note that this is a circular buffer and is capped by the given stdOutBufferSize. When the buffer is full, the kernel has an an additional 64Kb of buffer. When also that is full, the shell process may stop until some buffer becomes a available. If a large output is expected but it's not important to capture it, a shell command may be launched piping in /dev/null.
For example:
cat large_file /dev/null
isClosed
public final boolean isClosed()
Returns whether the process is closed.