Documentation

Overview

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

Example

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())

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

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

      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.

        Types

        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

            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

                              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) 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 sum of the elapsed time for all tests in the package.

                                              func (*Package) LastFailedByName

                                              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

                                                  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()
                                                          }

                                                            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
                                                              	SummarizeFailed
                                                              	SummarizeErrors
                                                              	SummarizeOutput
                                                              	SummarizeAll = SummarizeSkipped | SummarizeFailed | SummarizeErrors | SummarizeOutput
                                                              )

                                                                nolint: golint

                                                                func NewSummary

                                                                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

                                                                  func (s Summary) Includes(other Summary) bool

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

                                                                    func (Summary) String

                                                                    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

                                                                      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

                                                                                type TestName string

                                                                                func (TestName) IsSubTest

                                                                                func (n TestName) IsSubTest() bool

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

                                                                                  func (TestName) Name

                                                                                  func (n TestName) Name() string

                                                                                  func (TestName) Split

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