gogiven

An alternative BDD spec framework for go. Builds on "go test" tool and builds on the go testing package.

Inspired by YATSPEC. Another similar idea is JGiven, although both are Java based.

Check out the HTML output generator used as a default here: generator/htmlspec - using go's own template/html package.

Feel free to contact me and help improve the code base or let me know if you have any issues or questions!

To contribute, please read this first.

Introduction
Example One - GoGivens in practice
Example Two - Table Tests
Example Three - Skipping Tests
Example Four - Without a Given
Content Generation
List of pre-written output generators

Introduction

Go Givens is a lightweight BDD framework for producing test specifications directly from the code you write.

Go Givens parses your test file and produces a human-readable output in a specified directory, containing all the tests, captured data and other related information regarding your test such as success or failure.

Go Givens was inspired by YATSPEC, a BDD framework employed extensively by Sky Network Services (part of Sky, a UK tv company). As mentioned above, another similar product is JGiven.

Why?

Capturing your test method as test output is the only real way to show it's intention. You can refactor a test, and have the output update accordingly when the test runs. Unlike other go BDD frameworks, you can use function names to declare intent, and refactoring the function will affect the test. E.g.


//Hello, spec world!
func TestMyTest(...){
	Given(testing, someData()). // This is a test
	When(fooBarBaz()).
	Then(baz())
}

.. will be rendered as (but in html, or json, or whatever):

My Test
Hello, spec world!

Specification

Given testing some data noting that this is a test
When foo bar baz
Then baz

Test data (set by the func someData in the example above) can be captured in a map of interesting givens, and as the test progresses, the actuals can be captured in a map of captured inputs and outputs.

Interesting whats?

Interesting givens are data points that you want to use in your tests that are important for it to function correctly. "Given" data is then used by your application to fulfil some sort of request or process.

Interesting givens are generated as output along side your test output in a table so interested parties can examine them.

Captured Whos??

Captured inputs and outputs are data points that are registered by either your system under test (stubs, mocks etc) or the output from your system its self.

Captured inputs and outputs are logged along side your test, for each test, so that interested parties can view them.

That's all great, but still.. WHY would I want to log this stuff??

In BDD, a system's inputs and outputs are important to the business. Capturing the relationships between your data and the way the system handles can be demonstrated to your client. For example, your system could call a 3rd party, and you might want to model the interaction with stubs.

GoGivens gives you a standardised way of rendering captured data alongside your tests so you don't have to worry about it.

Rendered how?

The test framework parses your test file, and grabs the content. It strips all non-interesting parts out and leaves the Given/When/Then format in plain text ready for a GoGivensOutputGenerator to process the text. Interesting givens and Captured inputs and outputs are maps, which are rendered alongside your test givens as table data -- interesting givens are tablulated, and captured IO is listed.

A complete example of how to write a GoGivensOutputGenerator is given in generator/htmlspec - written in Go.

Example One - GoGivens in Practice

import (
	"fmt"
	"os"
	"testing"
	"github.com/corbym/gocrest/is"
	. "github.com/corbym/gocrest/then"
	"github.com/corbym/gogiven"
	"github.com/corbym/gogiven/base"
	"github.com/corbym/gogiven/testdata"
)

func TestMain(testmain *testing.M) {
	runOutput := testmain.Run()
	gogiven.GenerateTestOutput() // You only need TestMain + GenerateTestOutput() if you want to produce HTML output.
	os.Exit(runOutput)
}

// TestGreetingService_PersonalisesGreeting verifies that the greeting service
// generates a personalised message for a registered user.
func TestGreetingService_PersonalisesGreeting(t *testing.T) {
	gogiven.Given(t, aRegisteredUserNamed("Alice")).
		When(aGreetingIsRequested).
		Then(func(t base.TestingT, captured testdata.CapturedIO, givens testdata.InterestingGivens) {
			// the greeting should address the user by their registered name
			AssertThat(t, captured["greeting"], is.EqualTo("Hello, Alice!"))
		})
}

func aRegisteredUserNamed(name string) func(givens testdata.InterestingGivens) {
	return func(givens testdata.InterestingGivens) {
		givens["userName"] = name
	}
}

func aGreetingIsRequested(captured testdata.CapturedIO, givens testdata.InterestingGivens) {
	name := givens["userName"].(string)
	captured["greeting"] = fmt.Sprintf("Hello, %s!", name)
}

Note you do not have to use "gocrest" assertions, you can still call all of testing.T's functions to fail the test or you can use any go testing assertion package compatible with testing.T.

When run, the above will produce an HTML output:

Example Html

Example Two - Table Tests

Table tests work the same way as normal go table tests. GoGivens will then mark which test failed, if they do, in your test output.

Example:

import (
	"fmt"
	"testing"
	"github.com/corbym/gocrest/has"
	. "github.com/corbym/gocrest/then"
	"github.com/corbym/gogiven"
	"github.com/corbym/gogiven/base"
	"github.com/corbym/gogiven/testdata"
)

// TestGreetingService_PersonalisesGreeting_ForManyUsers tests that the greeting service
// produces the correct personalised greeting for a range of user names.
//
// Each test case verifies that the greeting contains exactly the expected number of characters.
func TestGreetingService_PersonalisesGreeting_ForManyUsers(t *testing.T) {
	type greetingTestCase struct {
		userName       string
		expectedLength int
	}
	var testCases = []greetingTestCase{
		{userName: "Li", expectedLength: 10},   // "Hello, Li!"
		{userName: "Alice", expectedLength: 13}, // "Hello, Alice!"
	}
	for _, tc := range testCases {
		t.Run(tc.userName, func(tt *testing.T) {
			weAreTesting := base.NewTestMetaData(t.Name())
			gogiven.Given(weAreTesting, aRegisteredUserNamed(tc.userName)).
				When(aGreetingIsRequested).
				Then(func(t base.TestingT, captured testdata.CapturedIO, stored testdata.InterestingGivens) {
					// the greeting length should match the length of the formatted output
					AssertThat(t, captured["greeting"], has.Length(tc.expectedLength))
				})
		})
	}
}

The above test will still fail the test function as far as Go is concerned, but the test output will note that the iteration failed like this:

Ranged Example Html

Note that comments are now rendered. Test function comments appear as part of the spec, and inline comments appear as "Noting that ..". In the above, the comment // the greeting length... would become "Noting that the greeting length should match the length of the formatted output".

More Examples

Full Index of all tests generated by GoGiven build
Skipped test
Without a Given

Example Three - Skipping Tests

Use SkippingThisOneIf to conditionally skip a test case within a table test, or SkippingThisOne to unconditionally skip:

// TestGreetingService_PersonalisesGreeting_SkipsUnknownLocale tests that the service
// skips producing a greeting for locales that are not yet supported.
func TestGreetingService_PersonalisesGreeting_SkipsUnknownLocale(t *testing.T) {
	type localeTestCase struct {
		userName string
		locale   string
	}
	var testCases = []localeTestCase{
		{userName: "Alice", locale: "en-US"},
		{userName: "Marie", locale: "fr-FR"},
	}
	for _, tc := range testCases {
		t.Run(tc.locale, func(t *testing.T) {
			gogiven.Given(t, aRegisteredUserNamed(tc.userName), withLocale(tc.locale)).
				SkippingThisOneIf(localeIsNotEnglish(tc.locale), "locale %s is not yet supported", tc.locale).
				When(aGreetingIsRequested).
				Then(func(t base.TestingT, captured testdata.CapturedIO, givens testdata.InterestingGivens) {
					AssertThat(t, captured["greeting"], is.EqualTo("Hello, Alice!"))
				})
		})
	}
}

func withLocale(locale string) func(givens testdata.InterestingGivens) {
	return func(givens testdata.InterestingGivens) {
		givens["locale"] = locale
	}
}

func localeIsNotEnglish(locale string) func(...interface{}) bool {
	return func(...interface{}) bool {
		return !strings.HasPrefix(locale, "en")
	}
}

Skipped test cases are still recorded in the test output, marked as skipped rather than failed.

Example Four - Without a Given

When there is no meaningful setup, you can start directly with When:

// TestGreetingService_ReturnsDefaultGreeting verifies that the service returns a
// default greeting message when no user context is provided.
func TestGreetingService_ReturnsDefaultGreeting(t *testing.T) {
	gogiven.When(t, aDefaultGreetingIsRequested).
		Then(func(t base.TestingT, captured testdata.CapturedIO, givens testdata.InterestingGivens) {
			AssertThat(t, captured["greeting"], is.EqualTo("Hello, World!"))
		})
}

func aDefaultGreetingIsRequested(captured testdata.CapturedIO, givens testdata.InterestingGivens) {
	captured["greeting"] = "Hello, World!"
}

Content Generation

Gogivens comes defaultly configured with an html generator (htmlspec.NewHTMLOutputGenerator) that is consumed by a file generator (generator.FileOutputGenerator) (see the godoc for more information). The content generator implements the following interface:

type GoGivensOutputGenerator interface {
	Generate(data PageData) (output io.Reader)
	// GenerateIndex generates the index from all the tests
	GenerateIndex(indexData []IndexData) (output io.Reader)
	// ContentType is text/html, application/json or other mime type
	ContentType() string
}

The generated content (output io.Reader) is then consumed by an OutputListener:

type OutputListener interface {
	Notify(testFilePath string, contentType string, output io.Reader)
}

If you want your own output listener just create your own and replace and/or append to the default listeners in your TestMain:

GoGiven's html spec now generates an index file, which is always stored along side the test html output.

func TestMain(testmain *testing.M) {
	gogiven.OutputListeners = []generator.OutputListener{new(MyFooListener)}
	// or alternately (or inclusively!)
	gogiven.OutputListeners = append(OutputListeners, new(MyBarListener))
	runOutput := testmain.Run()
	gogiven.GenerateTestOutput() // generates the output after the test is finished.
	os.Exit(runOutput)
}

Setting the test file output (for the `generator.FileOutputGenerator`)

You can add the environment variable GOGIVENS_OUTPUT_DIR to your env properties that points to a directory you want goGivens to report the test output to.

Default is the os's tmp directory.

List of Pre-written Ouput Generators

GoGiven comes with the following output generators:

HTML Spec: generator/htmlspec - generates the output used in the test example.
JSON Spec: generator/jsonspec - generates the output in JSON format.

📚 gogiven - Awesome Go Library for Testing

Detailed Description of gogiven

gogiven

Table of Contents

Introduction

Why?

Interesting whats?

Captured Whos??

That's all great, but still.. WHY would I want to log this stuff??

Rendered how?

Example One - GoGivens in Practice

Example Two - Table Tests

More Examples

Example Three - Skipping Tests

Example Four - Without a Given

Content Generation

Setting the test file output (for the `generator.FileOutputGenerator`)

List of Pre-written Ouput Generators

📚 gogiven - Awesome Go Library for Testing

Detailed Description of gogiven

gogiven

Table of Contents

Introduction

Why?

Interesting whats?

Captured Whos??

That's all great, but still.. WHY would I want to log this stuff??

Rendered how?

Example One - GoGivens in Practice

Example Two - Table Tests

More Examples

Example Three - Skipping Tests

Example Four - Without a Given

Content Generation

Setting the test file output (for the generator.FileOutputGenerator)

List of Pre-written Ouput Generators

Setting the test file output (for the `generator.FileOutputGenerator`)