From 2d29e774c70eb29acde2afe125975e94c75b398a Mon Sep 17 00:00:00 2001 From: Samuel Nelson Date: Tue, 15 Oct 2013 11:35:37 -0600 Subject: [PATCH] Updated documentation with some information about testing suites --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++ doc.go | 2 ++ suite/doc.go | 49 ++++++++++++++++++++++++++++++++++++++++----- suite/suite_test.go | 31 ++++++++++++++++++++++++++-- 4 files changed, 119 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 49d416f..e38d110 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,50 @@ An example test function that tests a piece of code that relies on an external o For more information on how to write mock code, check out the [API documentation for the `mock` package](http://go.pkgdoc.org/github.com/stretchr/testify/mock). +`suite` package +--------------- + +The `suite` package provides functionality that you might be used to from more common object oriented languages. With it, you can build a testing suite as a struct, build setup/teardown methods and testing methods on your struct, and run them with 'go test' as per normal. + +An example suite is shown below: + + // Basic imports + import ( + "testing" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/suite" + ) + + // Define the suite, and absorb the built-in basic suite + // functionality from testify - including a T() method which + // returns the current testing context + type ExampleTestSuite struct { + suite.Suite + VariableThatShouldStartAtFive int + } + + // Make sure that VariableThatShouldStartAtFive is set to five + // before each test + func (suite *ExampleTestSuite) SetupTest() { + suite.VariableThatShouldStartAtFive = 5 + } + + // All methods that begin with "Test" are run as tests within a + // suite. + func (suite *ExampleTestSuite) TestExample() { + assert.Equal(suite.T(), suite.VariableThatShouldStartAtFive, 5) + } + + // In order for 'go test' to run this suite, we need to create + // a normal test function and pass our suite to suite.Run + func TestExampleTestSuite(t *testing.T) { + suite.Run(t, new(ExampleTestSuite)) + } + +For a more complete example, using all of the functionality provided by the suite package, look at our [example testing suite](https://github.com/stretchr/testify/blob/master/suite/suite_test.go) + +Also, check out our [API documentation for the `suite` package](http://go.pkgdoc.org/github.com/stretchr/testify/suite). + ------ Installation diff --git a/doc.go b/doc.go index cc96578..12f5d38 100644 --- a/doc.go +++ b/doc.go @@ -7,6 +7,8 @@ // The http package contains tools to make it easier to test http activity using the Go testing system. // // The mock package provides a system by which it is possible to mock your objects and verify calls are happening as expected. +// +// The suite package provides a basic structure for using structs as testing suites, and methods on those structs as tests. It includes setup/teardown functionality in the way of interfaces. package testify import ( diff --git a/suite/doc.go b/suite/doc.go index b915d17..f478b04 100644 --- a/suite/doc.go +++ b/suite/doc.go @@ -1,6 +1,45 @@ -// A full testing suite, to expand upon the features of Go's built-in -// testing tool. Most importantly, this package provides interfaces -// and structs for creating suites of related tests, and putting -// related functionality into methods that will be run before and/or -// after the whole suite or each individual test. +// The suite package contains logic for creating testing suite structs +// and running the methods on those structs as tests. The most useful +// piece of this package is that you can create setup/teardown methods +// on your testing suites, which will run before/after the whole suite +// or individual tests (depending on which interface(s) you +// implement). +// +// Once you've built your testing suite, you need to run the suite +// inside any function that matches the identity that "go test" is +// already looking for (i.e. func(*testing.T)). +// +// A crude example: +// // Basic imports +// import ( +// "testing" +// "github.com/stretchr/testify/assert" +// "github.com/stretchr/testify/suite" +// ) +// +// // Define the suite, and absorb the built-in basic suite +// // functionality from testify - including a T() method which +// // returns the current testing context +// type ExampleTestSuite struct { +// suite.Suite +// VariableThatShouldStartAtFive int +// } +// +// // Make sure that VariableThatShouldStartAtFive is set to five +// // before each test +// func (suite *ExampleTestSuite) SetupTest() { +// suite.VariableThatShouldStartAtFive = 5 +// } +// +// // All methods that begin with "Test" are run as tests within a +// // suite. +// func (suite *ExampleTestSuite) TestExample() { +// assert.Equal(suite.T(), suite.VariableThatShouldStartAtFive, 5) +// } +// +// // In order for 'go test' to run this suite, we need to create +// // a normal test function and pass our suite to suite.Run +// func TestExampleTestSuite(t *testing.T) { +// suite.Run(t, new(ExampleTestSuite)) +// } package suite diff --git a/suite/suite_test.go b/suite/suite_test.go index 30450ed..05e0163 100644 --- a/suite/suite_test.go +++ b/suite/suite_test.go @@ -6,9 +6,16 @@ import ( ) // This suite is intended to store values to make sure that only -// testing-suite-related methods are run. +// testing-suite-related methods are run. It's also a fully +// functional example of a testing suite, using setup/teardown methods +// and a helper method that is ignored by testify. To make this look +// more like a real world example, all tests in the suite perform some +// type of assertion. type SuiteTester struct { + // Include our basic suite logic. Suite + + // Keep counts of how many times each method is run. SetupSuiteRunCount int TearDownSuiteRunCount int SetupTestRunCount int @@ -18,35 +25,55 @@ type SuiteTester struct { NonTestMethodRunCount int } +// The SetupSuite method will be run by testify once, at the very +// start of the testing suite, before any tests are run. func (suite *SuiteTester) SetupSuite() { suite.SetupSuiteRunCount++ } +// The TearDownSuite method will be run by testify once, at the very +// end of the testing suite, after all tests have been run. func (suite *SuiteTester) TearDownSuite() { suite.TearDownSuiteRunCount++ } +// The SetupTest method will be run before every test in the suite. func (suite *SuiteTester) SetupTest() { suite.SetupTestRunCount++ } +// The TearDownTest method will be run after every test in the suite. func (suite *SuiteTester) TearDownTest() { suite.TearDownTestRunCount++ } +// Every method in a testing suite that begins with "Test" will be run +// as a test. TestOne is an example of a test. For the purposes of +// this example, we've included assertions in the tests, since most +// tests will issue assertions. func (suite *SuiteTester) TestOne() { + beforeCount := suite.TestOneRunCount suite.TestOneRunCount++ + assert.Equal(suite.T(), suite.TestOneRunCount, beforeCount + 1) } +// TestTwo is another example of a test. func (suite *SuiteTester) TestTwo() { + beforeCount := suite.TestTwoRunCount suite.TestTwoRunCount++ + assert.NotEqual(suite.T(), suite.TestTwoRunCount, beforeCount) } +// NonTestMethod does not begin with "Test", so it will not be run by +// testify as a test in the suite. This is useful for creating helper +// methods for your tests. func (suite *SuiteTester) NonTestMethod() { suite.NonTestMethodRunCount++ } -func TestSuiteLogic(t *testing.T) { +// Make sure that the Run function runs all of the expected methods +// within a testing suite. +func TestRunSuite(t *testing.T) { suiteTester := new(SuiteTester) Run(t, suiteTester)