Updated documentation with some information about testing suites

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

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 (

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

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)