Test2json converts go test output to a machine-readable JSON stream.
Usage:
go tool test2json [-p pkg] [-t] [./pkg.test -test.v=test2json]
Test2json runs the given test command and converts its output to JSON; with no command specified, test2json expects test output on standard input. It writes a corresponding stream of JSON events to standard output. There is no unnecessary input or output buffering, so that the JSON stream can be read for “live updates” of test status.
The -p flag sets the package reported in each test event.
The -t flag requests that time stamps be added to each test event.
The test should be invoked with -test.v=test2json. Using only -test.v (or -test.v=true) is permissible but produces lower fidelity results.
Note that "go test -json" takes care of invoking test2json correctly, so "go tool test2json" is only needed when a test binary is being run separately from "go test". Use "go test -json" whenever possible.
Note also that test2json is only intended for converting a single test binary's output. To convert the output of a "go test" command that runs multiple packages, again use "go test -json".
The JSON stream is a newline-separated sequence of TestEvent objects corresponding to the Go struct:
type TestEvent struct {
Time time.Time // encodes as an RFC3339-format string
Action string
Package string
Test string
Elapsed float64 // seconds
Output string
}
The Time field holds the time the event happened. It is conventionally omitted for cached test results.
The Action field is one of a fixed set of action descriptions:
start - the test binary is about to be executed run - the test has started running pause - the test has been paused cont - the test has continued running pass - the test passed bench - the benchmark printed log output but did not fail fail - the test or benchmark failed output - the test printed output skip - the test was skipped or the package contained no tests
Every JSON stream begins with a "start" event.
The Package field, if present, specifies the package being tested. When the go command runs parallel tests in -json mode, events from different tests are interlaced; the Package field allows readers to separate them.
The Test field, if present, specifies the test, example, or benchmark function that caused the event. Events for the overall package test do not set Test.
The Elapsed field is set for "pass" and "fail" events. It gives the time elapsed for the specific test or the overall package test that passed or failed.
The Output field is set for Action == "output" and is a portion of the test's output (standard output and standard error merged together). The output is unmodified except that invalid UTF-8 output from a test is coerced into valid UTF-8 by use of replacement characters. With that one exception, the concatenation of the Output fields of all output events is the exact output of the test execution.
When a benchmark runs, it typically produces a single line of output giving timing results. That line is reported in an event with Action == "output" and no Test field. If a benchmark logs output or reports a failure (for example, by using b.Log or b.Error), that extra output is reported as a sequence of events with Test set to the benchmark name, terminated by a final event with Action == "bench" or "fail". Benchmarks have no events with Action == "pause".