1Testify - Thou Shalt Write Tests 2================================ 3 4ℹ️ We are working on testify v2 and would love to hear what you'd like to see in it, have your say here: https://cutt.ly/testify 5 6[![Build Status](https://travis-ci.org/stretchr/testify.svg)](https://travis-ci.org/stretchr/testify) [![Go Report Card](https://goreportcard.com/badge/github.com/stretchr/testify)](https://goreportcard.com/report/github.com/stretchr/testify) [![PkgGoDev](https://pkg.go.dev/badge/github.com/stretchr/testify)](https://pkg.go.dev/github.com/stretchr/testify) 7 8Go code (golang) set of packages that provide many tools for testifying that your code will behave as you intend. 9 10Features include: 11 12 * [Easy assertions](#assert-package) 13 * [Mocking](#mock-package) 14 * [Testing suite interfaces and functions](#suite-package) 15 16Get started: 17 18 * Install testify with [one line of code](#installation), or [update it with another](#staying-up-to-date) 19 * For an introduction to writing test code in Go, see http://golang.org/doc/code.html#Testing 20 * Check out the API Documentation http://godoc.org/github.com/stretchr/testify 21 * To make your testing life easier, check out our other project, [gorc](http://github.com/stretchr/gorc) 22 * A little about [Test-Driven Development (TDD)](http://en.wikipedia.org/wiki/Test-driven_development) 23 24 25 26[`assert`](http://godoc.org/github.com/stretchr/testify/assert "API documentation") package 27------------------------------------------------------------------------------------------- 28 29The `assert` package provides some helpful methods that allow you to write better test code in Go. 30 31 * Prints friendly, easy to read failure descriptions 32 * Allows for very readable code 33 * Optionally annotate each assertion with a message 34 35See it in action: 36 37```go 38package yours 39 40import ( 41 "testing" 42 "github.com/stretchr/testify/assert" 43) 44 45func TestSomething(t *testing.T) { 46 47 // assert equality 48 assert.Equal(t, 123, 123, "they should be equal") 49 50 // assert inequality 51 assert.NotEqual(t, 123, 456, "they should not be equal") 52 53 // assert for nil (good for errors) 54 assert.Nil(t, object) 55 56 // assert for not nil (good when you expect something) 57 if assert.NotNil(t, object) { 58 59 // now we know that object isn't nil, we are safe to make 60 // further assertions without causing any errors 61 assert.Equal(t, "Something", object.Value) 62 63 } 64 65} 66``` 67 68 * Every assert func takes the `testing.T` object as the first argument. This is how it writes the errors out through the normal `go test` capabilities. 69 * Every assert func returns a bool indicating whether the assertion was successful or not, this is useful for if you want to go on making further assertions under certain conditions. 70 71if you assert many times, use the below: 72 73```go 74package yours 75 76import ( 77 "testing" 78 "github.com/stretchr/testify/assert" 79) 80 81func TestSomething(t *testing.T) { 82 assert := assert.New(t) 83 84 // assert equality 85 assert.Equal(123, 123, "they should be equal") 86 87 // assert inequality 88 assert.NotEqual(123, 456, "they should not be equal") 89 90 // assert for nil (good for errors) 91 assert.Nil(object) 92 93 // assert for not nil (good when you expect something) 94 if assert.NotNil(object) { 95 96 // now we know that object isn't nil, we are safe to make 97 // further assertions without causing any errors 98 assert.Equal("Something", object.Value) 99 } 100} 101``` 102 103[`require`](http://godoc.org/github.com/stretchr/testify/require "API documentation") package 104--------------------------------------------------------------------------------------------- 105 106The `require` package provides same global functions as the `assert` package, but instead of returning a boolean result they terminate current test. 107 108See [t.FailNow](http://golang.org/pkg/testing/#T.FailNow) for details. 109 110[`mock`](http://godoc.org/github.com/stretchr/testify/mock "API documentation") package 111---------------------------------------------------------------------------------------- 112 113The `mock` package provides a mechanism for easily writing mock objects that can be used in place of real objects when writing test code. 114 115An example test function that tests a piece of code that relies on an external object `testObj`, can setup expectations (testify) and assert that they indeed happened: 116 117```go 118package yours 119 120import ( 121 "testing" 122 "github.com/stretchr/testify/mock" 123) 124 125/* 126 Test objects 127*/ 128 129// MyMockedObject is a mocked object that implements an interface 130// that describes an object that the code I am testing relies on. 131type MyMockedObject struct{ 132 mock.Mock 133} 134 135// DoSomething is a method on MyMockedObject that implements some interface 136// and just records the activity, and returns what the Mock object tells it to. 137// 138// In the real object, this method would do something useful, but since this 139// is a mocked object - we're just going to stub it out. 140// 141// NOTE: This method is not being tested here, code that uses this object is. 142func (m *MyMockedObject) DoSomething(number int) (bool, error) { 143 144 args := m.Called(number) 145 return args.Bool(0), args.Error(1) 146 147} 148 149/* 150 Actual test functions 151*/ 152 153// TestSomething is an example of how to use our test object to 154// make assertions about some target code we are testing. 155func TestSomething(t *testing.T) { 156 157 // create an instance of our test object 158 testObj := new(MyMockedObject) 159 160 // setup expectations 161 testObj.On("DoSomething", 123).Return(true, nil) 162 163 // call the code we are testing 164 targetFuncThatDoesSomethingWithObj(testObj) 165 166 // assert that the expectations were met 167 testObj.AssertExpectations(t) 168 169 170} 171 172// TestSomethingWithPlaceholder is a second example of how to use our test object to 173// make assertions about some target code we are testing. 174// This time using a placeholder. Placeholders might be used when the 175// data being passed in is normally dynamically generated and cannot be 176// predicted beforehand (eg. containing hashes that are time sensitive) 177func TestSomethingWithPlaceholder(t *testing.T) { 178 179 // create an instance of our test object 180 testObj := new(MyMockedObject) 181 182 // setup expectations with a placeholder in the argument list 183 testObj.On("DoSomething", mock.Anything).Return(true, nil) 184 185 // call the code we are testing 186 targetFuncThatDoesSomethingWithObj(testObj) 187 188 // assert that the expectations were met 189 testObj.AssertExpectations(t) 190 191 192} 193``` 194 195For more information on how to write mock code, check out the [API documentation for the `mock` package](http://godoc.org/github.com/stretchr/testify/mock). 196 197You can use the [mockery tool](http://github.com/vektra/mockery) to autogenerate the mock code against an interface as well, making using mocks much quicker. 198 199[`suite`](http://godoc.org/github.com/stretchr/testify/suite "API documentation") package 200----------------------------------------------------------------------------------------- 201 202The `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. 203 204An example suite is shown below: 205 206```go 207// Basic imports 208import ( 209 "testing" 210 "github.com/stretchr/testify/assert" 211 "github.com/stretchr/testify/suite" 212) 213 214// Define the suite, and absorb the built-in basic suite 215// functionality from testify - including a T() method which 216// returns the current testing context 217type ExampleTestSuite struct { 218 suite.Suite 219 VariableThatShouldStartAtFive int 220} 221 222// Make sure that VariableThatShouldStartAtFive is set to five 223// before each test 224func (suite *ExampleTestSuite) SetupTest() { 225 suite.VariableThatShouldStartAtFive = 5 226} 227 228// All methods that begin with "Test" are run as tests within a 229// suite. 230func (suite *ExampleTestSuite) TestExample() { 231 assert.Equal(suite.T(), 5, suite.VariableThatShouldStartAtFive) 232} 233 234// In order for 'go test' to run this suite, we need to create 235// a normal test function and pass our suite to suite.Run 236func TestExampleTestSuite(t *testing.T) { 237 suite.Run(t, new(ExampleTestSuite)) 238} 239``` 240 241For 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) 242 243For more information on writing suites, check out the [API documentation for the `suite` package](http://godoc.org/github.com/stretchr/testify/suite). 244 245`Suite` object has assertion methods: 246 247```go 248// Basic imports 249import ( 250 "testing" 251 "github.com/stretchr/testify/suite" 252) 253 254// Define the suite, and absorb the built-in basic suite 255// functionality from testify - including assertion methods. 256type ExampleTestSuite struct { 257 suite.Suite 258 VariableThatShouldStartAtFive int 259} 260 261// Make sure that VariableThatShouldStartAtFive is set to five 262// before each test 263func (suite *ExampleTestSuite) SetupTest() { 264 suite.VariableThatShouldStartAtFive = 5 265} 266 267// All methods that begin with "Test" are run as tests within a 268// suite. 269func (suite *ExampleTestSuite) TestExample() { 270 suite.Equal(suite.VariableThatShouldStartAtFive, 5) 271} 272 273// In order for 'go test' to run this suite, we need to create 274// a normal test function and pass our suite to suite.Run 275func TestExampleTestSuite(t *testing.T) { 276 suite.Run(t, new(ExampleTestSuite)) 277} 278``` 279 280------ 281 282Installation 283============ 284 285To install Testify, use `go get`: 286 287 go get github.com/stretchr/testify 288 289This will then make the following packages available to you: 290 291 github.com/stretchr/testify/assert 292 github.com/stretchr/testify/require 293 github.com/stretchr/testify/mock 294 github.com/stretchr/testify/suite 295 github.com/stretchr/testify/http (deprecated) 296 297Import the `testify/assert` package into your code using this template: 298 299```go 300package yours 301 302import ( 303 "testing" 304 "github.com/stretchr/testify/assert" 305) 306 307func TestSomething(t *testing.T) { 308 309 assert.True(t, true, "True is true!") 310 311} 312``` 313 314------ 315 316Staying up to date 317================== 318 319To update Testify to the latest version, use `go get -u github.com/stretchr/testify`. 320 321------ 322 323Supported go versions 324================== 325 326We support the two major Go versions, which are 1.13 and 1.14 at the moment. 327 328------ 329 330Contributing 331============ 332 333Please feel free to submit issues, fork the repository and send pull requests! 334 335When submitting an issue, we ask that you please include a complete test function that demonstrates the issue. Extra credit for those using Testify to write the test code that demonstrates it. 336 337Code generation is used. Look for `CODE GENERATED AUTOMATICALLY` at the top of some files. Run `go generate ./...` to update generated files. 338 339We also chat on the [Gophers Slack](https://gophers.slack.com) group in the `#testify` and `#testify-dev` channels. 340 341------ 342 343License 344======= 345 346This project is licensed under the terms of the MIT license. 347