x.ref/test: improved documentation and testing.
Change-Id: I12598ee69f82e4af4c16cd3322329ed0768b6d06
diff --git a/test/doc.go b/test/doc.go
index a2bbe20..82b585d 100644
--- a/test/doc.go
+++ b/test/doc.go
@@ -1,9 +1,10 @@
-// Package testutil provides initalization for unit and integration tests.
+// Package test provides initalization for unit and integration tests.
//
-// Configures logging, random number generators and other global state.
+// Init configures logging, random number generators and other global state.
// Typical usage in _test.go files:
//
// import "v.io/x/ref/test"
+//
// func TestMain(m *testing.M) {
// test.Init()
// os.Exit(m.Run())
@@ -17,4 +18,43 @@
// defer shutdown()
// ...
// }
+//
+// This package also defines flags for enabling and controlling
+// the v23 integration tests in package v23tests:
+// --v23.tests - run the integration tests
+// --v23.tests.shell-on-fail - drop into a debug shell if the test fails.
+//
+// Typical usage is:
+// $ v23 go test . --v23.tests
+//
+// Note that, like all flags not recognised by the go testing package, the
+// v23.tests flags must follow the package spec.
+//
+// The sub-directories of this package provide either functionality that
+// can be used within traditional go tests, or support for the v23 integration
+// test framework. The v23 command is able to generate boilerplate code
+// to support these tests. In summary, v23 test generate will generate
+// go files to be checked in that include appropriate TestMain functions,
+// registration calls for modules commands and wrapper functions for v23test
+// tests. More detailed documentation is available via:
+//
+// $ v23 test generate --help
+//
+// Vanadium tests often need to run subprocesses to provide either common
+// services that they depend (e.g. a mount table) and/or services that are
+// specific to the tests. The modules and v23tests subdirectories contain
+// packages that simplify this process.
+//
+// The subdirectories are:
+// benchmark - support for writing benchmarks.
+// testutil - utility functions used in tests.
+// security - security related utility functions used in tests.
+// timekeeper - an implementation of the timekeeper interface for use within
+// tests.
+// modules - support for running subprocesses using a single binary
+// v23tests - support for integration tests, including compiling and running
+// arbirtrary go code and pre-existing system commands.
+// expect - support for testing the contents of input streams. The methods
+// provided are embedded in the types used by modules and v23tests
+// so this package is generally not used directly.
package test
