tstat

README

TStat

Tstat provides information on Go test suites and functionality to make it easier to query for information on code coverage or test cases.

For tests, it leverages the JSON output provides by go test when running with the -json flag. See here for more info.

For coverage, it leverages the cover profiles for statements and function coverage provided by the cover tool. See cover for more info.

Usage

Coverage

	stats, err := tstat.Cover("testdata/prog/cover.out", tstat.WithRootModule("github.com/nickfiggins/tstat"))
	if err != nil {
		log.Fatalln(err)
	}
	fmt.Printf("total coverage: %#v%%\n", stats.Percent)
	pkg := stats.Packages[0]
	fmt.Printf("package: %s coverage: %#v%%\n", pkg.Name, pkg.Percent)
	fileCov := pkg.Files[0]
	for _, fn := range fileCov.Functions {
		fmt.Printf("function: %s coverage: %v%%\n", fn.Name, fn.Percent)
	}
	// Output:
	// total coverage: 25%
	// package: github.com/nickfiggins/tstat/testdata/prog coverage: 25%
	// function: add coverage: 100%
	// function: isOdd coverage: 0%

Tests

	stats, err := tstat.Tests("testdata/bigtest.json")
	if err != nil {
		log.Fatalln(err)
	}

	fmt.Println(stats.Count(), stats.Failed(), stats.Duration().String())
	pkg, _ := stats.Package("github.com/nickfiggins/tstat")
	test, _ := pkg.Test("Test_CoverageStats")
	fmt.Println(test.Count(), test.Failed(), test.Skipped(), test.Package)

	sub, _ := test.Test("happy") // subtest Test_CoverageStats/happy
	if !sub.Failed() {
		fmt.Printf("%v passed\n", sub.FullName)
	}
	// Output: 50 false 473.097ms
	// 3 false false github.com/nickfiggins/tstat
	// Test_CoverageStats/happy passed

Documentation

Overview

Package tstat provides utilities for parsing information from Go test runs or code coverage.

Index

• type CoverOpt
  • func WithRootModule(module string) CoverOpt
• type Coverage
  • func Cover(coverProfile string, opts ...CoverOpt) (Coverage, error)
  • func CoverFromReaders(coverProfile io.Reader, fnProfile io.Reader, opts ...CoverOpt) (Coverage, error)
  • func (c *Coverage) Package(name string) (*PackageCoverage, bool)
• type CoverageParser
  • func NewCoverageParser(opts ...CoverOpt) *CoverageParser
  • func (p *CoverageParser) Stats(coverProfile, fnProfile io.Reader) (Coverage, error)
• type FileCoverage
• type FunctionCoverage
• type PackageCoverage
  • func (pc *PackageCoverage) File(name string) (*FileCoverage, bool)
  • func (pc *PackageCoverage) Functions() []FunctionCoverage
• type PackageRun
  • func (pr *PackageRun) Count() int
  • func (pr *PackageRun) Duration() time.Duration
  • func (pr *PackageRun) Failed() bool
  • func (pr *PackageRun) Failures() []*Test
  • func (pr *PackageRun) Test(name string) (*Test, bool)
• type Test
  • func (t *Test) Count() int
  • func (t *Test) Failed() bool
  • func (t *Test) Skipped() bool
  • func (t *Test) Test(name string) (*Test, bool)
• type TestParser
  • func NewTestParser() *TestParser
  • func (p *TestParser) Stats(outJSON io.Reader) (TestRun, error)
• type TestRun
  • func Tests(outFile string) (TestRun, error)
  • func TestsFromReader(outJSON io.Reader) (TestRun, error)
  • func (tr *TestRun) Count() int
  • func (tr *TestRun) Duration() time.Duration
  • func (tr *TestRun) Failed() bool
  • func (tr *TestRun) Package(name string) (PackageRun, bool)
  • func (tr *TestRun) Packages() []PackageRun

Examples

• Cover
• Tests

Types

type CoverOpt

type CoverOpt func(*CoverageParser)

CoverOpt is a functional option for configuring a CoverageParser.

func WithRootModule

func WithRootModule(module string) CoverOpt

WithRootModule sets the root module to trim from the file names in the coverage profile.

type Coverage

type Coverage struct {
	Percent  float64            // Percent is the total percent of statements covered.
	Packages []*PackageCoverage // Packages is the coverage of each package.
}

Coverage is the coverage statistics parsed from a single test profile.

func Cover

func Cover(coverProfile string, opts ...CoverOpt) (Coverage, error)

Cover parses the coverage and function profiles and returns a statistics based on the profiles read. The corresponding function profile will be generated automatically. If you want to provide an existing function profile, use CoverFromReaders. The cover profile must be a valid coverage profile generated by `go test -coverprofile=cover.out`.

Example

package main

import (
	"fmt"
	"log"

	"github.com/nickfiggins/tstat"
)

func main() {
	stats, err := tstat.Cover("testdata/prog/cover.out", tstat.WithRootModule("github.com/nickfiggins/tstat"))
	if err != nil {
		log.Fatalln(err)
	}
	fmt.Printf("total coverage: %#v%%\n", stats.Percent)
	pkg := stats.Packages[0]
	fmt.Printf("package: %s coverage: %#v%%\n", pkg.Name, pkg.Percent)
	fileCov := pkg.Files[0]
	for _, fn := range fileCov.Functions {
		fmt.Printf("function: %s coverage: %v%%\n", fn.Name, fn.Percent)
	}
}

Output:

total coverage: 25%
package: github.com/nickfiggins/tstat/testdata/prog coverage: 25%
function: add coverage: 100%
function: isOdd coverage: 0%

func CoverFromReaders

func CoverFromReaders(coverProfile io.Reader, fnProfile io.Reader, opts ...CoverOpt) (Coverage, error)

CoverFromReaders parses the coverage and function profiles and returns a statistics based on the profiles read. If you want to generate the function profile automatically, use Cover instead.

func (*Coverage) Package

func (c *Coverage) Package(name string) (*PackageCoverage, bool)

Package returns the coverage of a single package in the run. It's a convenience method for finding a file in the list of file coverages.

type CoverageParser

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

CoverageParser is a parser for coverage profiles that can be configured to read from files or io.Readers. If only a cover profile is provided, the corresponding function profile will be generated automatically. If a function profile is provided, it will be used instead of generating one - which is useful when parsing profiles that aren't part of the current project.

func NewCoverageParser

func NewCoverageParser(opts ...CoverOpt) *CoverageParser

NewCoverageParser returns a new CoverageParser with the given options.

func (*CoverageParser) Stats

func (p *CoverageParser) Stats(coverProfile, fnProfile io.Reader) (Coverage, error)

Stats parses the coverage and function profiles and returns a statistics based on the profiles read.

type FileCoverage

type FileCoverage struct {
	Name         string             // Name is the name of the file.
	Percent      float64            // Percent is the percent of statements covered.
	Functions    []FunctionCoverage // Functions is the coverage of each function in the file.
	Stmts        int                // Stmts is the total number of statements in the file.
	CoveredStmts int                // CoveredStmts is the number of statements covered in the file.
}

type FunctionCoverage

type FunctionCoverage struct {
	Name     string  // Name is the name of the function.
	Percent  float64 // Percent is the percent of statements covered.
	File     string  // File is the file the function is defined in.
	Line     int     // Line is the line the function is defined on.
	Internal bool    // Internal is true if the function is internal to the package.
}

FunctionCoverage is the coverage of a function.

type PackageCoverage

type PackageCoverage struct {
	Name    string          // Name is the name of the package.
	Percent float64         // Percent is the percentage of statements covered in the package.
	Files   []*FileCoverage // Files is the coverage of each file in the package.
}

PackageCoverage is the coverage of a package.

func (*PackageCoverage) File

func (pc *PackageCoverage) File(name string) (*FileCoverage, bool)

File returns the coverage of a file in the package. It's a convenience method for finding a file in the list of file coverages.

func (*PackageCoverage) Functions

func (pc *PackageCoverage) Functions() []FunctionCoverage

Functions returns all functions in the package.

type PackageRun

type PackageRun struct {
	Tests []*Test
	Seed  int64
	// contains filtered or unexported fields
}

PackageRun represents the results of a package test run. If the package was run with the -shuffle flag,.

func (*PackageRun) Count

func (pr *PackageRun) Count() int

Count returns the total number of tests, including subtests.

func (*PackageRun) Duration

func (pr *PackageRun) Duration() time.Duration

Duration returns the duration of the test run.

func (*PackageRun) Failed

func (pr *PackageRun) Failed() bool

Failed returns true if any of the tests failed.

func (*PackageRun) Failures

func (pr *PackageRun) Failures() []*Test

Failures returns the tests that failed.

func (*PackageRun) Test

func (pr *PackageRun) Test(name string) (*Test, bool)

Test is a single test, which may have subtests.

type Test

type Test struct {
	Subtests []*Test // Subtests is a list of subtests for this test.

	FullName string // FullName is the full name of the test, including subtests.
	Name     string // Name is the name of the test, without the parent test name.
	Package  string // Package is the package that the test belongs to.
	// contains filtered or unexported fields
}

Test is a single test, which may have subtests.

func (*Test) Count

func (t *Test) Count() int

Count returns the total number of tests, including subtests.

func (*Test) Failed

func (t *Test) Failed() bool

Failed returns true if the test failed.

func (*Test) Skipped

func (t *Test) Skipped() bool

Skipped returns true if the test was skipped.

func (*Test) Test

func (t *Test) Test(name string) (*Test, bool)

Test returns the test with the given name. If the test name matches the current test, it will be returned.

type TestParser

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

TestParser is a parser for test output JSON.

func NewTestParser

func NewTestParser() *TestParser

NewTestParser returns a new TestParser.

func (*TestParser) Stats

func (p *TestParser) Stats(outJSON io.Reader) (TestRun, error)

Stats parses the test output and returns a TestRun based on the output read.

type TestRun

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

TestRun represents the results of a test run, which may contain multiple packages.

func Tests

func Tests(outFile string) (TestRun, error)

Tests parses the test output JSON file and returns a TestRun based on the output read.

Example

package main

import (
	"fmt"
	"log"

	"github.com/nickfiggins/tstat"
)

func main() {
	stats, err := tstat.Tests("testdata/bigtest.json")
	if err != nil {
		log.Fatalln(err)
	}

	fmt.Println(stats.Count(), stats.Failed(), stats.Duration().String())
	pkg, _ := stats.Package("github.com/nickfiggins/tstat")
	test, _ := pkg.Test("Test_CoverageStats")
	fmt.Println(test.Count(), test.Failed(), test.Skipped(), test.Package)

	sub, _ := test.Test("happy") // subtest Test_CoverageStats/happy
	if !sub.Failed() {
		fmt.Printf("%v passed\n", sub.FullName)
	}
}

Output:

50 false 473.097ms
3 false false github.com/nickfiggins/tstat
Test_CoverageStats/happy passed

func TestsFromReader

func TestsFromReader(outJSON io.Reader) (TestRun, error)

TestsFromReader parses the test output JSON from a reader and returns a TestRun based on the output read.

func (*TestRun) Count

func (tr *TestRun) Count() int

Count returns the total number of tests, including subtests.

func (*TestRun) Duration

func (tr *TestRun) Duration() time.Duration

func (*TestRun) Failed

func (tr *TestRun) Failed() bool

Failed returns true if any of the tests failed.

func (*TestRun) Package

func (tr *TestRun) Package(name string) (PackageRun, bool)

PackageRun represents the results of a package test run. If the package was run with the -shuffle flag, the Seed field will be populated. Otherwise, it will be 0.

func (*TestRun) Packages

func (tr *TestRun) Packages() []PackageRun

Packages returns the packages that were run.