gotestout

Documentation

Overview

Package gotestout renders go test -json streams using laslig output primitives and the library's normal terminal styling behavior.

The package focuses on parsing and rendering the event stream itself. It does not execute commands or own process lifecycle. Callers are expected to wire exec.Command, Mage, or another runner to an io.Reader that yields go test events. Options allow compact or detailed views, one transient live activity block with auto/on/off modes for styled human output, and grouped failed- test, skipped-test, package-error, or captured-output sections that callers can disable when they want a tighter summary. In JSON mode, Render re-emits the raw go test events while still returning summary counts, and it skips the grouped human/plain summary blocks and transient activity block. This makes the package a good fit for Mage targets such as `mage test`, ordinary Go CLI commands, and small Go helpers invoked from tools such as `make`, `just`, or `task`.

Index

• type Action
  • func (a Action) IsTerminal() bool
• type ActivityMode
  • func (m ActivityMode) Valid() bool
• type ActivityOptions
• type Event
  • func Parse(in io.Reader) ([]Event, error)
  • func (e Event) MarshalJSON() ([]byte, error)
  • func (e Event) PackageEvent() bool
• type Options
• type Renderer
  • func NewRenderer(out io.Writer, options Options) *Renderer
  • func (r *Renderer) Finish() error
  • func (r *Renderer) Summary() Summary
  • func (r *Renderer) WriteEvent(event Event) error
• type Section
• type Summary
  • func Render(out io.Writer, in io.Reader, options Options) (Summary, error)
  • func (s Summary) HasFailures() bool
  • func (s Summary) TotalPackages() int
  • func (s Summary) TotalTests() int
• type View

Examples

• Render
• Render (Json)

Types

type Action

type Action string

Action identifies the type of one go test -json event.

const (
	// ActionStart identifies a package start event.
	ActionStart Action = "start"
	// ActionRun identifies a test start event.
	ActionRun Action = "run"
	// ActionPause identifies a paused test event.
	ActionPause Action = "pause"
	// ActionCont identifies a resumed test event.
	ActionCont Action = "cont"
	// ActionPass identifies a passing package or test event.
	ActionPass Action = "pass"
	// ActionBench identifies a benchmark event.
	ActionBench Action = "bench"
	// ActionFail identifies a failing package or test event.
	ActionFail Action = "fail"
	// ActionOutput identifies an output line event.
	ActionOutput Action = "output"
	// ActionSkip identifies a skipped package or test event.
	ActionSkip Action = "skip"
	// ActionBuildOutput identifies a build-output event.
	ActionBuildOutput Action = "build-output"
	// ActionAttr identifies an attribute event.
	ActionAttr Action = "attr"
)

func (Action) IsTerminal

func (a Action) IsTerminal() bool

IsTerminal reports whether the action completes a package or test.

type ActivityMode

type ActivityMode string

ActivityMode controls whether gotestout renders one live activity block while a test stream is still running.

const (
	// ActivityAuto enables the activity block only for styled human terminal
	// output where transient redraws are appropriate.
	ActivityAuto ActivityMode = "auto"
	// ActivityOn forces the activity block for styled human output even when
	// the writer is not a terminal, which is useful for demos and tests.
	ActivityOn ActivityMode = "on"
	// ActivityOff disables the activity block completely.
	ActivityOff ActivityMode = "off"
)

func (ActivityMode) Valid

func (m ActivityMode) Valid() bool

Valid reports whether the activity mode is one supported built-in value.

type ActivityOptions

type ActivityOptions struct {
	// Mode selects whether the activity block is enabled automatically, forced on for
	// styled human output, or disabled entirely. The default is auto.
	Mode ActivityMode
	// SpinnerStyle selects the built-in spinner frame set used when the block
	// is visible. The default is laslig.DefaultSpinnerStyle().
	SpinnerStyle laslig.SpinnerStyle
	// Delay waits this long before showing the block, which helps avoid
	// flicker on very short test runs. The default is 750ms.
	Delay time.Duration
	// Text overrides the leading activity label. The default is
	// "Running go test -json".
	Text string
}

ActivityOptions configures the optional live activity block shown while a go test stream is still running.

The block is transient in styled human output and is suppressed entirely in plain, unstyled human, and JSON modes.

type Event

type Event struct {
	Time        time.Time `json:"Time,omitempty"`
	Action      Action    `json:"Action"`
	Package     string    `json:"Package,omitempty"`
	Test        string    `json:"Test,omitempty"`
	Elapsed     float64   `json:"Elapsed,omitempty"`
	Output      string    `json:"Output,omitempty"`
	FailedBuild string    `json:"FailedBuild,omitempty"`
	Key         string    `json:"Key,omitempty"`
	Value       string    `json:"Value,omitempty"`
}

Event is one object emitted by go test -json.

func Parse

func Parse(in io.Reader) ([]Event, error)

Parse decodes a full stream into memory.

func (Event) MarshalJSON

func (e Event) MarshalJSON() ([]byte, error)

MarshalJSON preserves the go test -json event shape by omitting zero-valued timestamps instead of serializing them as the zero time.

func (Event) PackageEvent

func (e Event) PackageEvent() bool

PackageEvent reports whether the event applies to an entire package.

type Options

type Options struct {
	Policy           laslig.Policy
	View             View
	DisabledSections []Section
	Activity         ActivityOptions
}

Options controls how a stream is rendered.

type Renderer

type Renderer struct {
	// contains filtered or unexported fields
}

Renderer consumes go test -json events and renders them to one writer.

func NewRenderer

func NewRenderer(out io.Writer, options Options) *Renderer

NewRenderer constructs one renderer for the provided writer and options.

func (*Renderer) Finish

func (r *Renderer) Finish() error

Finish writes the final summary for human and plain output.

func (*Renderer) Summary

func (r *Renderer) Summary() Summary

Summary returns the counts accumulated so far.

func (*Renderer) WriteEvent

func (r *Renderer) WriteEvent(event Event) error

WriteEvent consumes one parsed event and writes any corresponding output.

type Section

type Section string

Section identifies one optional rendered test-output section.

const (
	// SectionFailedTests identifies the grouped failed-tests summary section.
	SectionFailedTests Section = "failed-tests"
	// SectionSkippedTests identifies the grouped skipped-tests summary section.
	SectionSkippedTests Section = "skipped-tests"
	// SectionPackageErrors identifies the grouped package-errors summary section.
	SectionPackageErrors Section = "package-errors"
	// SectionOutput identifies captured event output lines in detailed views and summaries.
	SectionOutput Section = "output"
)

type Summary

type Summary struct {
	PackagesPassed  int
	PackagesFailed  int
	PackagesSkipped int
	TestsPassed     int
	TestsFailed     int
	TestsSkipped    int
	BuildErrors     int
}

Summary records the terminal outcomes seen in one stream.

func Render

func Render(out io.Writer, in io.Reader, options Options) (Summary, error)

Render parses a stream, renders it, and returns a summary of terminal events.

Example

ExampleRender shows one small plain-text gotestout render.

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/evanmschultz/laslig"
	"github.com/evanmschultz/laslig/gotestout"
)

func main() {
	stream := strings.NewReader(`{"Action":"pass","Package":"example/pkg","Test":"TestRender","Elapsed":0.01}
{"Action":"pass","Package":"example/pkg","Elapsed":0.01}
`)

	summary, _ := gotestout.Render(os.Stdout, stream, gotestout.Options{
		Policy: laslig.Policy{
			Format: laslig.FormatPlain,
			Style:  laslig.StyleNever,
		},
	})

	fmt.Printf("tests=%d packages=%d failures=%t\n", summary.TotalTests(), summary.TotalPackages(), summary.HasFailures())

}

Output:
[PKG PASS] example/pkg (0.01s)

Test summary
  tests: 1
  passed: 1
  failed: 0
  skipped: 0
  packages: 1
  pkg passed: 1
  pkg failed: 0
  pkg skipped: 0

[SUCCESS] All tests passed
  1 test passed across 1 package.
tests=1 packages=1 failures=false

Example (Json)

ExampleRender_json shows that JSON mode re-emits raw go test events while still returning summary counts to the caller.

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/evanmschultz/laslig"
	"github.com/evanmschultz/laslig/gotestout"
)

func main() {
	stream := strings.NewReader(`{"Action":"pass","Package":"example/pkg","Test":"TestRender","Elapsed":0.01}
{"Action":"pass","Package":"example/pkg","Elapsed":0.01}
`)

	summary, _ := gotestout.Render(os.Stdout, stream, gotestout.Options{
		Policy: laslig.Policy{
			Format: laslig.FormatJSON,
		},
	})

	fmt.Printf("tests=%d packages=%d failures=%t\n", summary.TotalTests(), summary.TotalPackages(), summary.HasFailures())

}

Output:
{"Action":"pass","Package":"example/pkg","Test":"TestRender","Elapsed":0.01}
{"Action":"pass","Package":"example/pkg","Elapsed":0.01}
tests=1 packages=1 failures=false

func (Summary) HasFailures

func (s Summary) HasFailures() bool

HasFailures reports whether the stream contained any failures or build errors.

func (Summary) TotalPackages

func (s Summary) TotalPackages() int

TotalPackages returns the total number of terminal package outcomes.

func (Summary) TotalTests

func (s Summary) TotalTests() int

TotalTests returns the total number of terminal test outcomes.

type View

type View string

View selects the human/plain rendering density.

const (
	// ViewCompact renders terminal results plus failure output and a final summary.
	ViewCompact View = "compact"
	// ViewDetailed also renders useful output for passing and skipped tests.
	ViewDetailed View = "detailed"
)