tree f602548b4f4632250bce8bc61a08560a4cbc9927
parent a629f70fb14cfe62d7616fb6bef7836675b15f92
author Adam Sadovsky <asadovsky@gmail.com> 1449887062 -0800
committer Adam Sadovsky <asadovsky@gmail.com> 1449887062 -0800

lib: v23test

v23test aims to replace x/ref/{v23tests,modules}.

v23test differs from the existing packages in terms of both
API/behavior and implementation. The key differences are
outlined below.

API/behavior changes
----------------------------------------
- Shell can be used both for tests (e.g. -v23.tests style
tests) and for tools that run commands (e.g. dmrun,
servicerunner). If Shell is initialized with a testing.T,
Shell method errors trigger test failure; otherwise, errors
trigger panic. (These failures/panics can be disabled, but
we expect them to almost always be enabled.)
- By default, stdout and stderr from child processes are
streamed to the parent's respective output streams, as well
as to temporary files on disk. (This behavior is
configurable.)
- Improved function registration: registered functions now
accept typed parameters, so developers need not convert
arguments to/from strings when invoking registered
functions.
- New Main() method allows for "main-like" functions to be
registered and invoked with command-line flags. These
invocations behave identically to binary invocations, but
allow for the "main-like" functions to be compiled into the
parent process's binary, eliminating the need for expensive
JiriBuildGoPkg compilations at runtime.
- Simplified credentials management via ForkContext and
ForkCredentials methods.

Testing-specific API/behavior changes
----------------------------------------
- For tests, avoids the need for "go generate", thereby
avoiding extra process overhead and eliminating the need for
code generation. Test packages simply include a TestMain of
the form:
func TestMain(m *testing.M) {
os.Exit(v23test.Run(m.Run))
}
Developers avoid having to learn a new "framework" (V23Test)
and avoid adding "go generate" to their test development
workflow.
- Keeps the Shell separate from the *testing.T; developers
can interact directly with the *testing.T, just as they do
in other tests, and interact with the Shell when they wish
to perform Shell operations.
- Tests can be enabled/disabled independent of whether the
-v23.tests flag was specified.

Implementation
----------------------------------------
- Simpler, cleaner layering:
* gosh.Shell allows for spawning, managing, waiting on, and
terminating subprocesses, and is oblivious to Vanadium.
* v23test.Shell is a lightweight wrapper around gosh.Shell
that provides Vanadium-specific functionality such as
JiriBuildGoPkg, StartRootMountTable, credentials management,
etc.
- Does not use v.io/x/ref/lib/exec for subprocess
management. This library will continue to be used by device
manager (where it's needed, according to Bogdan), but it is
not needed by other clients of v23tests/modules. In
particular, secret-sharing via anonymous pipes is not
necessary for our integration tests (also, note that it's
not actually secure on all platforms), and existing tests
rely on other mechanisms to wait for subprocesses to report
that they are ready, e.g. we use the 'expect' package to
wait for the mount table to report its endpoint.

MultiPart: 1/2

Change-Id: I418270262f142c0f2cea0b5bb34b923bf4ece4f5