Version: v1.8.1 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: May 8, 2022 License: Apache-2.0 Imports: 24 Imported by: 12



Package testjson scans test2json output and builds up a summary of the events. Events are passed to a formatter for output.


This example reads the test2json output from os.Stdin. It sends every event to the handler, builds an Execution from the output, then it prints the number of tests run.

exec, err := testjson.ScanTestOutput(testjson.ScanConfig{
    // Stdout is a reader that provides the test2json output stream.
    Stdout: os.Stdin,
    // Handler receives TestEvents and error lines.
    Handler: eventHandler,
if err != nil {
    return fmt.Errorf("failed to scan testjson: %w", err)
fmt.Println("Ran %d tests", exec.Total())



This section is empty.


This section is empty.


func FormatDurationAsSeconds

func FormatDurationAsSeconds(d time.Duration, precision int) string

FormatDurationAsSeconds formats a time.Duration as a float with an s suffix.

func PrintSummary

func PrintSummary(out io.Writer, execution *Execution, opts Summary)

PrintSummary of a test Execution. Prints a section for each summary type followed by a DONE line to out.

func RelativePackagePath added in v0.4.0

func RelativePackagePath(pkgpath string) string

RelativePackagePath attempts to remove a common prefix from a package path. The common prefix is determined either by looking at the GOPATH or reading the package value from go.mod file. If the pkgpath does not match the common prefix it will be returned unmodified. If the pkgpath matches the common prefix exactly then '.' will be returned.


type Action

type Action string

Action of TestEvent

const (
	ActionRun    Action = "run"
	ActionPause  Action = "pause"
	ActionCont   Action = "cont"
	ActionPass   Action = "pass"
	ActionBench  Action = "bench"
	ActionFail   Action = "fail"
	ActionOutput Action = "output"
	ActionSkip   Action = "skip"

nolint: unused

func (Action) IsTerminal added in v1.6.4

func (a Action) IsTerminal() bool

IsTerminal returns true if the Action is one of: pass, fail, skip.

type EventFormatter

type EventFormatter interface {
	Format(event TestEvent, output *Execution) error

EventFormatter is a function which handles an event and returns a string to output for the event.

func NewEventFormatter

func NewEventFormatter(out io.Writer, format string) EventFormatter

NewEventFormatter returns a formatter for printing events.

type EventHandler

type EventHandler interface {
	// Event is called for every TestEvent, with the current value of Execution.
	// It may return an error to stop scanning.
	Event(event TestEvent, execution *Execution) error
	// Err is called for every line from the Stderr reader and may return an
	// error to stop scanning.
	Err(text string) error

EventHandler is called by ScanTestOutput for each event and write to stderr.

type Execution

type Execution struct {
	// contains filtered or unexported fields

Execution of one or more test packages

func ScanTestOutput

func ScanTestOutput(config ScanConfig) (*Execution, error)

ScanTestOutput reads lines from config.Stdout and config.Stderr, populates an Execution, calls the Handler for each event, and returns the Execution.

If config.Handler is nil, a default no-op handler will be used.

func (*Execution) Elapsed

func (e *Execution) Elapsed() time.Duration

Elapsed returns the time elapsed since the execution started.

func (*Execution) Errors

func (e *Execution) Errors() []string

Errors returns a list of all the errors.

func (*Execution) Failed

func (e *Execution) Failed() []TestCase

Failed returns a list of all the failed test cases.

func (*Execution) HasPanic added in v1.6.4

func (e *Execution) HasPanic() bool

HasPanic returns true if at least one package had output that looked like a panic.

func (*Execution) OutputLines

func (e *Execution) OutputLines(tc TestCase) []string

OutputLines returns the full test output for a test as an slice of lines. This function is a convenient wrapper around Package.OutputLines() to support the hiding of output in the summary.

See Package.OutLines() for more details.

func (*Execution) Package

func (e *Execution) Package(name string) *Package

Package returns the Package by name.

func (*Execution) Packages

func (e *Execution) Packages() []string

Packages returns a sorted list of all package names.

func (*Execution) Skipped

func (e *Execution) Skipped() []TestCase

Skipped returns a list of all the skipped test cases.

func (*Execution) Started added in v1.7.0

func (e *Execution) Started() time.Time

func (*Execution) Total

func (e *Execution) Total() int

Total returns a count of all test cases.

type Package

type Package struct {
	Total int

	Failed  []TestCase
	Skipped []TestCase
	Passed  []TestCase
	// contains filtered or unexported fields

Package is the set of TestEvents for a single go package

func (*Package) Elapsed

func (p *Package) Elapsed() time.Duration

Elapsed returns the elapsed time of the package, as reported by the pass or fail event for the package.

func (*Package) LastFailedByName added in v0.5.0

func (p *Package) LastFailedByName(name string) TestCase

LastFailedByName returns the most recent test with name in the list of Failed tests. If no TestCase is found with that name, an empty TestCase is returned.

LastFailedByName may be used by formatters to find the TestCase.ID for the current failing TestEvent. It is very likely the last TestCase in Failed, but this method provides a little more safety if that ever changes.

func (*Package) Output

func (p *Package) Output(id int) string

Output returns the full test output for a test.

Unlike OutputLines() it does not return lines from subtests in some cases.

func (*Package) OutputLines added in v0.4.2

func (p *Package) OutputLines(tc TestCase) []string

OutputLines returns the full test output for a test as a slice of strings.

As a workaround for test output being attributed to the wrong subtest, if:

- the TestCase is a root TestCase (not a subtest), and
- the TestCase has no subtest failures;

then all output for every subtest under the root test is returned. See https://github.com/golang/go/issues/29755.

func (*Package) Result

func (p *Package) Result() Action

Result returns if the package passed, failed, or was skipped because there were no tests.

func (*Package) TestCases

func (p *Package) TestCases() []TestCase

TestCases returns all the test cases.

func (*Package) TestMainFailed

func (p *Package) TestMainFailed() bool

TestMainFailed returns true if the package failed, but there were no tests. This may occur if the package init() or TestMain exited non-zero.

type ScanConfig

type ScanConfig struct {
	// RunID is a unique identifier for the run. It may be set to the pid of the
	// process, or some other identifier. It will stored as the TestCase.RunID.
	RunID int
	// Stdout is a reader that yields the test2json output stream.
	Stdout io.Reader
	// Stderr is a reader that yields stderr from the 'go test' process. Often
	// it contains build errors, or panics. Stderr may be nil.
	Stderr io.Reader
	// Handler is a set of callbacks for receiving TestEvents and stderr text.
	Handler EventHandler
	// Execution to populate while scanning. If nil a new one will be created
	// and returned from ScanTestOutput.
	Execution *Execution
	// Stop is called when ScanTestOutput fails during a scan.
	Stop func()
	// IgnoreNonJSONOutputLines causes ScanTestOutput to ignore non-JSON lines received from
	// the Stdout reader. Instead of causing an error, the lines will be sent to Handler.Err.
	IgnoreNonJSONOutputLines bool

ScanConfig used by ScanTestOutput.

type Summary

type Summary int

Summary enumerates the sections which can be printed by PrintSummary

const (
	SummarizeNone    Summary = 0
	SummarizeSkipped Summary = (1 << iota) / 2
	SummarizeAll = SummarizeSkipped | SummarizeFailed | SummarizeErrors | SummarizeOutput

nolint: golint

func NewSummary added in v0.3.3

func NewSummary(value string) (Summary, bool)

NewSummary returns a new Summary from a string value. If the string does not match any known values returns false for the second value.

func (Summary) Includes added in v0.3.3

func (s Summary) Includes(other Summary) bool

Includes returns true if Summary includes all the values set by other.

func (Summary) String added in v0.3.3

func (s Summary) String() string

type TestCase

type TestCase struct {
	// ID is unique ID for each test case. A test run may include multiple instances
	// of the same Package and Name if -count is used, or if the input comes from
	// multiple runs. The ID can be used to uniquely reference an instance of a
	// test case.
	ID      int
	Package string
	Test    TestName
	Elapsed time.Duration
	// RunID from the ScanConfig which produced this test case.
	RunID int

	// Time when the test was run.
	Time time.Time
	// contains filtered or unexported fields

TestCase stores the name and elapsed time for a test case.

func FilterFailedUnique added in v0.5.2

func FilterFailedUnique(tcs []TestCase) []TestCase

FilterFailedUnique filters a slice of failed TestCases by removing root test case that have failed subtests.

type TestEvent

type TestEvent struct {
	// Time encoded as an RFC3339-format string
	Time    time.Time
	Action  Action
	Package string
	Test    string
	// Elapsed time in seconds
	Elapsed float64
	// Output of test or benchmark
	Output string

	// RunID from the ScanConfig which produced this test event.
	RunID int
	// contains filtered or unexported fields

TestEvent is a structure output by go tool test2json and go test -json.

func (TestEvent) Bytes

func (e TestEvent) Bytes() []byte

Bytes returns the serialized JSON bytes that were parsed to create the event.

func (TestEvent) ElapsedFormatted

func (e TestEvent) ElapsedFormatted() string

ElapsedFormatted returns Elapsed formatted in the go test format, ex (0.00s).

func (TestEvent) PackageEvent

func (e TestEvent) PackageEvent() bool

PackageEvent returns true if the event is a package start or end event

type TestName added in v0.6.0

type TestName string

func (TestName) IsSubTest added in v0.6.0

func (n TestName) IsSubTest() bool

IsSubTest returns true if the name indicates the test is a subtest run using t.Run().

func (TestName) Name added in v0.6.0

func (n TestName) Name() string

func (TestName) Split added in v0.6.0

func (n TestName) Split() (root string, sub string)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL