sweet

README

sweet

Sweet is a pluggable test runner capable of hooking into standard Go tests. It attempts to provide access to the standard Go test tool as close as possible while adding support for test suites and plugins that can hook into test results to add additional functionality.

Using Sweet

To use Sweet as your test runner you need to add the TestMain function from the Go testing package. This will allow Sweet to run code before and after the actual tests run. Inside the TestMain function you'll want to call the sweet.Run function to both set up the Sweet configuration as well as run the tests:

package mypackage

import (
    "testing"
    "github.com/aphistic/sweet"
)


func TestMain(m *testing.M) {
    sweet.Run(m, func(s *sweet.S) {
        // Configuration goes here
    })
}

Defining a Suite

A test suite in Sweet is just a normal Go struct with methods named similar to standard go test names (beginning with Test). Creating a suite named FailSuite with a single test that always fails and then running it with Sweet looks like the following code:

package mypackage

import (
    "testing"
    "github.com/aphistic/sweet"
)


func TestMain(m *testing.M) {
    sweet.Run(m, func(s *sweet.S) {
        s.AddSuite(&FailSuite{})
        // Add any additional suites the same way
    })
}

type FailSuite struct {}

func (s *FailSuite) TestAlwaysFails(t sweet.T) {
    t.Fail()
}

Using a Plugin

Sweet supports plugins to add functionality that isn't typically available with the standard Go testing tools. One such example is sweet-junit, a plugin that generates a junit.xml file for each package it's used in. To add to the previous examples, this is how you'd add the sweet-junit plugin to your tests:

package mypackage

import (
    "testing"
    "github.com/aphistic/sweet"
    junit "github.com/aphistic/sweet-junit"
)


func TestMain(m *testing.M) {
    sweet.Run(m, func(s *sweet.S) {
        s.RegisterPlugin(junit.NewPlugin())

        s.AddSuite(&FailSuite{})
        // Add any additional suites the same way
    })
}

type FailSuite struct {}

func (s *FailSuite) TestAlwaysFails(t sweet.T) {
    t.Fail()
}

Using an External Matcher

Sweet was designed with the capability to use external matchers in mind. You can write standard Go unit tests but you can also hook a different matcher library in and use that.

So far the only matcher that Sweet has been tested with and has hooks for is the Gomega library.

To use Gomega in the above example, you would do:

package mypackage

import (
    "testing"

    . "github.com/onsi/gomega"

    "github.com/aphistic/sweet"
    junit "github.com/aphistic/sweet-junit"
)


func TestMain(m *testing.M) {
    RegisterFailHandler(sweet.GomegaFail)

    sweet.Run(m, func(s *sweet.S) {
        s.RegisterPlugin(junit.NewPlugin())

        s.AddSuite(&FailSuite{})
        // Add any additional suites the same way
    })
}

type FailSuite struct {}

func (s *FailSuite) TestAlwaysFails(t sweet.T) {
    t.Fail()
}

Documentation

Index

• func GomegaFail(message string, callerSkip ...int)
• func Run(m *testing.M, f func(s *S))
• type Plugin
• type PluginOption
• type PluginOptions
• type S
  • func (s *S) AddSuite(suite interface{})
  • func (s *S) RegisterPlugin(plugin Plugin)
  • func (s *S) SetUpAllTests(f func(t T)) func(t T)
  • func (s *S) TearDownAllTests(f func(t T)) func(t T)
• type SuiteFinishedStats
• type SweetUtil
• type T
• type TestFailedFrame
• type TestFailedStats
• type TestPassedStats
• type TestSkippedStats

Functions

func GomegaFail

func GomegaFail(message string, callerSkip ...int)

GomegaFail is a utility function provided to hook into the Gomega matcher library. To use this it's easiest to do the following in your set up:

func TestMain(m *testing.M) {
    RegisterFailHandler(sweet.GomegaFail)

    sweet.Run(m, func(s *sweet.S) {
        // ... Suite set up ...
    })
}

func Run

func Run(m *testing.M, f func(s *S))

Types

type Plugin

type Plugin interface {
	Name() string
	Options() *PluginOptions
	SetOption(name, value string)

	Starting()
	SuiteStarting(suite string)
	TestStarting(suite, test string)
	TestPassed(suite, test string, stats *TestPassedStats)
	TestFailed(suite, test string, stats *TestFailedStats)
	TestSkipped(suite, test string, stats *TestSkippedStats)
	SuiteFinished(suite string, stats *SuiteFinishedStats)
	Finished()
}

type PluginOption

type PluginOption struct {
	Help    string
	Default string
}

type PluginOptions

type PluginOptions struct {
	Prefix  string
	Options map[string]*PluginOption
}

type S

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

func (*S) AddSuite

func (s *S) AddSuite(suite interface{})

func (*S) RegisterPlugin

func (s *S) RegisterPlugin(plugin Plugin)

func (*S) SetUpAllTests

func (s *S) SetUpAllTests(f func(t T)) func(t T)

func (*S) TearDownAllTests

func (s *S) TearDownAllTests(f func(t T)) func(t T)

type SuiteFinishedStats

type SuiteFinishedStats struct {
	Time time.Duration
}

type SweetUtil

type SweetUtil interface {
	ListFiles(path string) []string
	LoadFile(path string) []byte
}

type T

type T interface {
	Error(args ...interface{})
	Errorf(format string, args ...interface{})
	Fail()
	FailNow()
	Failed() bool
	Fatal(args ...interface{})
	Fatalf(format string, args ...interface{})
	Log(args ...interface{})
	Logf(format string, args ...interface{})
	Name() string
	Parallel()
	Run(name string, f func(t T)) bool
	Skip(args ...interface{})
	SkipNow()
	Skipf(format string, args ...interface{})
	Skipped() bool

	Sweet() SweetUtil
}

type TestFailedFrame

type TestFailedFrame struct {
	File string
	Line int
}

type TestFailedStats

type TestFailedStats struct {
	Name    string
	Time    time.Duration
	Message string
	Frames  []*TestFailedFrame
}

type TestPassedStats

type TestPassedStats struct {
	Time time.Duration
}

type TestSkippedStats

type TestSkippedStats struct {
	Time time.Duration
}