README

Instructions

Install the package with:

go get gopkg.in/check.v1

Import it with:

import "gopkg.in/check.v1"

and use check as the package name inside the code.

For more details, visit the project page:

and the API documentation:

Documentation

Overview

    Package check is a rich testing extension for Go's testing package.

    For details about the project, see:

    http://labix.org/gocheck
    

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func List

    func List(suite interface{}, runConf *RunConf) []string

      List returns the names of the test functions in the given suite that will be run with the provided run configuration.

      func ListAll

      func ListAll(runConf *RunConf) []string

        ListAll returns the names of all the test functions registered with the Suite function that will be run with the provided run configuration.

        func Suite

        func Suite(suite interface{}) interface{}

          Suite registers the given value as a test suite to be run. Any methods starting with the Test prefix in the given value will be considered as a test method.

          func TestingT

          func TestingT(testingT *testing.T)

            TestingT runs all test suites registered with the Suite function, printing results to stdout, and reporting any failures back to the "testing" package.

            Types

            type C

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

            func (*C) Assert

            func (c *C) Assert(obtained interface{}, checker Checker, args ...interface{})

              Assert ensures that the first value matches the expected value according to the provided checker. If they do not match, an error is logged, the test is marked as failed, and the test execution stops.

              Some checkers may not need the expected argument (e.g. IsNil).

              Extra arguments provided to the function are logged next to the reported problem when the matching fails.

              func (*C) Check

              func (c *C) Check(obtained interface{}, checker Checker, args ...interface{}) bool

                Check verifies if the first value matches the expected value according to the provided checker. If they do not match, an error is logged, the test is marked as failed, and the test execution continues.

                Some checkers may not need the expected argument (e.g. IsNil).

                Extra arguments provided to the function are logged next to the reported problem when the matching fails.

                func (*C) Error

                func (c *C) Error(args ...interface{})

                  Error logs an error into the test error output and marks the test as failed. The provided arguments are assembled together into a string with fmt.Sprint.

                  func (*C) Errorf

                  func (c *C) Errorf(format string, args ...interface{})

                    Errorf logs an error into the test error output and marks the test as failed. The provided arguments are assembled together into a string with fmt.Sprintf.

                    func (*C) ExpectFailure

                    func (c *C) ExpectFailure(reason string)

                      ExpectFailure informs that the running test is knowingly broken for the provided reason. If the test does not fail, an error will be reported to raise attention to this fact. This method is useful to temporarily disable tests which cover well known problems until a better time to fix the problem is found, without forgetting about the fact that a failure still exists.

                      func (*C) Fail

                      func (c *C) Fail()

                        Fail marks the currently running test as failed.

                        Something ought to have been previously logged so the developer can tell what went wrong. The higher level helper functions will fail the test and do the logging properly.

                        func (*C) FailNow

                        func (c *C) FailNow()

                          FailNow marks the currently running test as failed and stops running it. Something ought to have been previously logged so the developer can tell what went wrong. The higher level helper functions will fail the test and do the logging properly.

                          func (*C) Failed

                          func (c *C) Failed() bool

                            Failed returns whether the currently running test has already failed.

                            func (*C) Fatal

                            func (c *C) Fatal(args ...interface{})

                              Fatal logs an error into the test error output, marks the test as failed, and stops the test execution. The provided arguments are assembled together into a string with fmt.Sprint.

                              func (*C) Fatalf

                              func (c *C) Fatalf(format string, args ...interface{})

                                Fatlaf logs an error into the test error output, marks the test as failed, and stops the test execution. The provided arguments are assembled together into a string with fmt.Sprintf.

                                func (*C) GetTestLog

                                func (c *C) GetTestLog() string

                                  GetTestLog returns the current test error output.

                                  func (*C) Log

                                  func (c *C) Log(args ...interface{})

                                    Log logs some information into the test error output. The provided arguments are assembled together into a string with fmt.Sprint.

                                    func (*C) Logf

                                    func (c *C) Logf(format string, args ...interface{})

                                      Log logs some information into the test error output. The provided arguments are assembled together into a string with fmt.Sprintf.

                                      func (*C) MkDir

                                      func (c *C) MkDir() string

                                        Create a new temporary directory which is automatically removed after the suite finishes running.

                                        func (*C) Output

                                        func (c *C) Output(calldepth int, s string) error

                                          Output enables *C to be used as a logger in functions that require only the minimum interface of *log.Logger.

                                          func (*C) ResetTimer

                                          func (c *C) ResetTimer()

                                            ResetTimer sets the elapsed benchmark time to zero. It does not affect whether the timer is running.

                                            func (*C) SetBytes

                                            func (c *C) SetBytes(n int64)

                                              SetBytes informs the number of bytes that the benchmark processes on each iteration. If this is called in a benchmark it will also report MB/s.

                                              func (*C) Skip

                                              func (c *C) Skip(reason string)

                                                Skip skips the running test for the provided reason. If run from within SetUpTest, the individual test being set up will be skipped, and if run from within SetUpSuite, the whole suite is skipped.

                                                func (*C) StartTimer

                                                func (c *C) StartTimer()

                                                  StartTimer starts timing a test. This function is called automatically before a benchmark starts, but it can also used to resume timing after a call to StopTimer.

                                                  func (*C) StopTimer

                                                  func (c *C) StopTimer()

                                                    StopTimer stops timing a test. This can be used to pause the timer while performing complex initialization that you don't want to measure.

                                                    func (*C) Succeed

                                                    func (c *C) Succeed()

                                                      Succeed marks the currently running test as succeeded, undoing any previous failures.

                                                      func (*C) SucceedNow

                                                      func (c *C) SucceedNow()

                                                        SucceedNow marks the currently running test as succeeded, undoing any previous failures, and stops running the test.

                                                        func (*C) TestName

                                                        func (c *C) TestName() string

                                                          TestName returns the current test name in the form "SuiteName.TestName"

                                                          type Checker

                                                          type Checker interface {
                                                          	Info() *CheckerInfo
                                                          	Check(params []interface{}, names []string) (result bool, error string)
                                                          }

                                                            The Checker interface must be provided by checkers used with the Assert and Check verification methods.

                                                            var DeepEquals Checker = &deepEqualsChecker{
                                                            	&CheckerInfo{Name: "DeepEquals", Params: []string{"obtained", "expected"}},
                                                            }

                                                              The DeepEquals checker verifies that the obtained value is deep-equal to the expected value. The check will work correctly even when facing slices, interfaces, and values of different types (which always fail the test).

                                                              For example:

                                                              c.Assert(value, DeepEquals, 42)
                                                              c.Assert(array, DeepEquals, []string{"hi", "there"})
                                                              
                                                              var Equals Checker = &equalsChecker{
                                                              	&CheckerInfo{Name: "Equals", Params: []string{"obtained", "expected"}},
                                                              }

                                                                The Equals checker verifies that the obtained value is equal to the expected value, according to usual Go semantics for ==.

                                                                For example:

                                                                c.Assert(value, Equals, 42)
                                                                
                                                                var ErrorMatches Checker = errorMatchesChecker{
                                                                	&CheckerInfo{Name: "ErrorMatches", Params: []string{"value", "regex"}},
                                                                }

                                                                  The ErrorMatches checker verifies that the error value is non nil and matches the regular expression provided.

                                                                  For example:

                                                                  c.Assert(err, ErrorMatches, "perm.*denied")
                                                                  
                                                                  var FitsTypeOf Checker = &fitsTypeChecker{
                                                                  	&CheckerInfo{Name: "FitsTypeOf", Params: []string{"obtained", "sample"}},
                                                                  }

                                                                    The FitsTypeOf checker verifies that the obtained value is assignable to a variable with the same type as the provided sample value.

                                                                    For example:

                                                                    c.Assert(value, FitsTypeOf, int64(0))
                                                                    c.Assert(value, FitsTypeOf, os.Error(nil))
                                                                    
                                                                    var HasLen Checker = &hasLenChecker{
                                                                    	&CheckerInfo{Name: "HasLen", Params: []string{"obtained", "n"}},
                                                                    }

                                                                      The HasLen checker verifies that the obtained value has the provided length. In many cases this is superior to using Equals in conjuction with the len function because in case the check fails the value itself will be printed, instead of its length, providing more details for figuring the problem.

                                                                      For example:

                                                                      c.Assert(list, HasLen, 5)
                                                                      
                                                                      var Implements Checker = &implementsChecker{
                                                                      	&CheckerInfo{Name: "Implements", Params: []string{"obtained", "ifaceptr"}},
                                                                      }

                                                                        The Implements checker verifies that the obtained value implements the interface specified via a pointer to an interface variable.

                                                                        For example:

                                                                        var e os.Error
                                                                        c.Assert(err, Implements, &e)
                                                                        
                                                                        var IsNil Checker = &isNilChecker{
                                                                        	&CheckerInfo{Name: "IsNil", Params: []string{"value"}},
                                                                        }

                                                                          The IsNil checker tests whether the obtained value is nil.

                                                                          For example:

                                                                          c.Assert(err, IsNil)
                                                                          
                                                                          var Matches Checker = &matchesChecker{
                                                                          	&CheckerInfo{Name: "Matches", Params: []string{"value", "regex"}},
                                                                          }

                                                                            The Matches checker verifies that the string provided as the obtained value (or the string resulting from obtained.String()) matches the regular expression provided.

                                                                            For example:

                                                                            c.Assert(err, Matches, "perm.*denied")
                                                                            
                                                                            var NotNil Checker = &notNilChecker{
                                                                            	&CheckerInfo{Name: "NotNil", Params: []string{"value"}},
                                                                            }

                                                                              The NotNil checker verifies that the obtained value is not nil.

                                                                              For example:

                                                                              c.Assert(iface, NotNil)
                                                                              

                                                                              This is an alias for Not(IsNil), made available since it's a fairly common check.

                                                                              var PanicMatches Checker = &panicMatchesChecker{
                                                                              	&CheckerInfo{Name: "PanicMatches", Params: []string{"function", "expected"}},
                                                                              }

                                                                                The PanicMatches checker verifies that calling the provided zero-argument function will cause a panic with an error value matching the regular expression provided.

                                                                                For example:

                                                                                c.Assert(func() { f(1, 2) }, PanicMatches, `open.*: no such file or directory`).
                                                                                
                                                                                var Panics Checker = &panicsChecker{
                                                                                	&CheckerInfo{Name: "Panics", Params: []string{"function", "expected"}},
                                                                                }

                                                                                  The Panics checker verifies that calling the provided zero-argument function will cause a panic which is deep-equal to the provided value.

                                                                                  For example:

                                                                                  c.Assert(func() { f(1, 2) }, Panics, &SomeErrorType{"BOOM"}).
                                                                                  

                                                                                  func Not

                                                                                  func Not(checker Checker) Checker

                                                                                    The Not checker inverts the logic of the provided checker. The resulting checker will succeed where the original one failed, and vice-versa.

                                                                                    For example:

                                                                                    c.Assert(a, Not(Equals), b)
                                                                                    

                                                                                    type CheckerInfo

                                                                                    type CheckerInfo struct {
                                                                                    	Name   string
                                                                                    	Params []string
                                                                                    }

                                                                                      See the Checker interface.

                                                                                      func (*CheckerInfo) Info

                                                                                      func (info *CheckerInfo) Info() *CheckerInfo

                                                                                      type CommentInterface

                                                                                      type CommentInterface interface {
                                                                                      	CheckCommentString() string
                                                                                      }

                                                                                        CommentInterface must be implemented by types that attach extra information to failed checks. See the Commentf function for details.

                                                                                        func Commentf

                                                                                        func Commentf(format string, args ...interface{}) CommentInterface

                                                                                          Commentf returns an infomational value to use with Assert or Check calls. If the checker test fails, the provided arguments will be passed to fmt.Sprintf, and will be presented next to the logged failure.

                                                                                          For example:

                                                                                          c.Assert(v, Equals, 42, Commentf("Iteration #%d failed.", i))
                                                                                          

                                                                                          Note that if the comment is constant, a better option is to simply use a normal comment right above or next to the line, as it will also get printed with any errors:

                                                                                          c.Assert(l, Equals, 8192) // Ensure buffer size is correct (bug #123)
                                                                                          

                                                                                          type Result

                                                                                          type Result struct {
                                                                                          	Succeeded        int
                                                                                          	Failed           int
                                                                                          	Skipped          int
                                                                                          	Panicked         int
                                                                                          	FixturePanicked  int
                                                                                          	ExpectedFailures int
                                                                                          	Missed           int    // Not even tried to run, related to a panic in the fixture.
                                                                                          	RunError         error  // Houston, we've got a problem.
                                                                                          	WorkDir          string // If KeepWorkDir is true
                                                                                          }

                                                                                          func Run

                                                                                          func Run(suite interface{}, runConf *RunConf) *Result

                                                                                            Run runs the provided test suite using the provided run configuration.

                                                                                            func RunAll

                                                                                            func RunAll(runConf *RunConf) *Result

                                                                                              RunAll runs all test suites registered with the Suite function, using the provided run configuration.

                                                                                              func (*Result) Add

                                                                                              func (r *Result) Add(other *Result)

                                                                                              func (*Result) Passed

                                                                                              func (r *Result) Passed() bool

                                                                                              func (*Result) String

                                                                                              func (r *Result) String() string

                                                                                              type RunConf

                                                                                              type RunConf struct {
                                                                                              	Output        io.Writer
                                                                                              	Stream        bool
                                                                                              	Verbose       bool
                                                                                              	Filter        string
                                                                                              	Benchmark     bool
                                                                                              	BenchmarkTime time.Duration // Defaults to 1 second
                                                                                              	BenchmarkMem  bool
                                                                                              	KeepWorkDir   bool
                                                                                              }