1# assertions 2-- 3 import "github.com/smartystreets/assertions" 4 5Package assertions contains the implementations for all assertions which are 6referenced in goconvey's `convey` package 7(github.com/smartystreets/goconvey/convey) for use with the So(...) method. They 8can also be used in traditional Go test functions and even in applicaitons. 9 10## Usage 11 12#### func GoConveyMode 13 14```go 15func GoConveyMode(yes bool) 16``` 17GoConveyMode provides control over JSON serialization of failures. When using 18the assertions in this package from the convey package JSON results are very 19helpful and can be rendered in a DIFF view. In that case, this function will be 20called with a true value to enable the JSON serialization. By default, the 21assertions in this package will not serializer a JSON result, making standalone 22ussage more convenient. 23 24#### func ShouldAlmostEqual 25 26```go 27func ShouldAlmostEqual(actual interface{}, expected ...interface{}) string 28``` 29ShouldAlmostEqual makes sure that two parameters are close enough to being 30equal. The acceptable delta may be specified with a third argument, or a very 31small default delta will be used. 32 33#### func ShouldBeBetween 34 35```go 36func ShouldBeBetween(actual interface{}, expected ...interface{}) string 37``` 38ShouldBeBetween receives exactly three parameters: an actual value, a lower 39bound, and an upper bound. It ensures that the actual value is between both 40bounds (but not equal to either of them). 41 42#### func ShouldBeBetweenOrEqual 43 44```go 45func ShouldBeBetweenOrEqual(actual interface{}, expected ...interface{}) string 46``` 47ShouldBeBetweenOrEqual receives exactly three parameters: an actual value, a 48lower bound, and an upper bound. It ensures that the actual value is between 49both bounds or equal to one of them. 50 51#### func ShouldBeBlank 52 53```go 54func ShouldBeBlank(actual interface{}, expected ...interface{}) string 55``` 56ShouldBeBlank receives exactly 1 string parameter and ensures that it is equal 57to "". 58 59#### func ShouldBeChronological 60 61```go 62func ShouldBeChronological(actual interface{}, expected ...interface{}) string 63``` 64ShouldBeChronological receives a []time.Time slice and asserts that the are in 65chronological order starting with the first time.Time as the earliest. 66 67#### func ShouldBeEmpty 68 69```go 70func ShouldBeEmpty(actual interface{}, expected ...interface{}) string 71``` 72ShouldBeEmpty receives a single parameter (actual) and determines whether or not 73calling len(actual) would return `0`. It obeys the rules specified by the len 74function for determining length: http://golang.org/pkg/builtin/#len 75 76#### func ShouldBeFalse 77 78```go 79func ShouldBeFalse(actual interface{}, expected ...interface{}) string 80``` 81ShouldBeFalse receives a single parameter and ensures that it is false. 82 83#### func ShouldBeGreaterThan 84 85```go 86func ShouldBeGreaterThan(actual interface{}, expected ...interface{}) string 87``` 88ShouldBeGreaterThan receives exactly two parameters and ensures that the first 89is greater than the second. 90 91#### func ShouldBeGreaterThanOrEqualTo 92 93```go 94func ShouldBeGreaterThanOrEqualTo(actual interface{}, expected ...interface{}) string 95``` 96ShouldBeGreaterThanOrEqualTo receives exactly two parameters and ensures that 97the first is greater than or equal to the second. 98 99#### func ShouldBeIn 100 101```go 102func ShouldBeIn(actual interface{}, expected ...interface{}) string 103``` 104ShouldBeIn receives at least 2 parameters. The first is a proposed member of the 105collection that is passed in either as the second parameter, or of the 106collection that is comprised of all the remaining parameters. This assertion 107ensures that the proposed member is in the collection (using ShouldEqual). 108 109#### func ShouldBeLessThan 110 111```go 112func ShouldBeLessThan(actual interface{}, expected ...interface{}) string 113``` 114ShouldBeLessThan receives exactly two parameters and ensures that the first is 115less than the second. 116 117#### func ShouldBeLessThanOrEqualTo 118 119```go 120func ShouldBeLessThanOrEqualTo(actual interface{}, expected ...interface{}) string 121``` 122ShouldBeLessThan receives exactly two parameters and ensures that the first is 123less than or equal to the second. 124 125#### func ShouldBeNil 126 127```go 128func ShouldBeNil(actual interface{}, expected ...interface{}) string 129``` 130ShouldBeNil receives a single parameter and ensures that it is nil. 131 132#### func ShouldBeTrue 133 134```go 135func ShouldBeTrue(actual interface{}, expected ...interface{}) string 136``` 137ShouldBeTrue receives a single parameter and ensures that it is true. 138 139#### func ShouldBeZeroValue 140 141```go 142func ShouldBeZeroValue(actual interface{}, expected ...interface{}) string 143``` 144ShouldBeZeroValue receives a single parameter and ensures that it is the Go 145equivalent of the default value, or "zero" value. 146 147#### func ShouldContain 148 149```go 150func ShouldContain(actual interface{}, expected ...interface{}) string 151``` 152ShouldContain receives exactly two parameters. The first is a slice and the 153second is a proposed member. Membership is determined using ShouldEqual. 154 155#### func ShouldContainKey 156 157```go 158func ShouldContainKey(actual interface{}, expected ...interface{}) string 159``` 160ShouldContainKey receives exactly two parameters. The first is a map and the 161second is a proposed key. Keys are compared with a simple '=='. 162 163#### func ShouldContainSubstring 164 165```go 166func ShouldContainSubstring(actual interface{}, expected ...interface{}) string 167``` 168ShouldContainSubstring receives exactly 2 string parameters and ensures that the 169first contains the second as a substring. 170 171#### func ShouldEndWith 172 173```go 174func ShouldEndWith(actual interface{}, expected ...interface{}) string 175``` 176ShouldEndWith receives exactly 2 string parameters and ensures that the first 177ends with the second. 178 179#### func ShouldEqual 180 181```go 182func ShouldEqual(actual interface{}, expected ...interface{}) string 183``` 184ShouldEqual receives exactly two parameters and does an equality check. 185 186#### func ShouldEqualTrimSpace 187 188```go 189func ShouldEqualTrimSpace(actual interface{}, expected ...interface{}) string 190``` 191ShouldEqualTrimSpace receives exactly 2 string parameters and ensures that the 192first is equal to the second after removing all leading and trailing whitespace 193using strings.TrimSpace(first). 194 195#### func ShouldEqualWithout 196 197```go 198func ShouldEqualWithout(actual interface{}, expected ...interface{}) string 199``` 200ShouldEqualWithout receives exactly 3 string parameters and ensures that the 201first is equal to the second after removing all instances of the third from the 202first using strings.Replace(first, third, "", -1). 203 204#### func ShouldHappenAfter 205 206```go 207func ShouldHappenAfter(actual interface{}, expected ...interface{}) string 208``` 209ShouldHappenAfter receives exactly 2 time.Time arguments and asserts that the 210first happens after the second. 211 212#### func ShouldHappenBefore 213 214```go 215func ShouldHappenBefore(actual interface{}, expected ...interface{}) string 216``` 217ShouldHappenBefore receives exactly 2 time.Time arguments and asserts that the 218first happens before the second. 219 220#### func ShouldHappenBetween 221 222```go 223func ShouldHappenBetween(actual interface{}, expected ...interface{}) string 224``` 225ShouldHappenBetween receives exactly 3 time.Time arguments and asserts that the 226first happens between (not on) the second and third. 227 228#### func ShouldHappenOnOrAfter 229 230```go 231func ShouldHappenOnOrAfter(actual interface{}, expected ...interface{}) string 232``` 233ShouldHappenOnOrAfter receives exactly 2 time.Time arguments and asserts that 234the first happens on or after the second. 235 236#### func ShouldHappenOnOrBefore 237 238```go 239func ShouldHappenOnOrBefore(actual interface{}, expected ...interface{}) string 240``` 241ShouldHappenOnOrBefore receives exactly 2 time.Time arguments and asserts that 242the first happens on or before the second. 243 244#### func ShouldHappenOnOrBetween 245 246```go 247func ShouldHappenOnOrBetween(actual interface{}, expected ...interface{}) string 248``` 249ShouldHappenOnOrBetween receives exactly 3 time.Time arguments and asserts that 250the first happens between or on the second and third. 251 252#### func ShouldHappenWithin 253 254```go 255func ShouldHappenWithin(actual interface{}, expected ...interface{}) string 256``` 257ShouldHappenWithin receives a time.Time, a time.Duration, and a time.Time (3 258arguments) and asserts that the first time.Time happens within or on the 259duration specified relative to the other time.Time. 260 261#### func ShouldHaveLength 262 263```go 264func ShouldHaveLength(actual interface{}, expected ...interface{}) string 265``` 266ShouldHaveLength receives a collection and a positive integer and asserts that 267the length of the collection is equal to the integer provided. 268 269#### func ShouldHaveSameTypeAs 270 271```go 272func ShouldHaveSameTypeAs(actual interface{}, expected ...interface{}) string 273``` 274ShouldHaveSameTypeAs receives exactly two parameters and compares their 275underlying types for equality. 276 277#### func ShouldImplement 278 279```go 280func ShouldImplement(actual interface{}, expectedList ...interface{}) string 281``` 282ShouldImplement receives exactly two parameters and ensures that the first 283implements the interface type of the second. 284 285#### func ShouldNotAlmostEqual 286 287```go 288func ShouldNotAlmostEqual(actual interface{}, expected ...interface{}) string 289``` 290ShouldNotAlmostEqual is the inverse of ShouldAlmostEqual 291 292#### func ShouldNotBeBetween 293 294```go 295func ShouldNotBeBetween(actual interface{}, expected ...interface{}) string 296``` 297ShouldNotBeBetween receives exactly three parameters: an actual value, a lower 298bound, and an upper bound. It ensures that the actual value is NOT between both 299bounds. 300 301#### func ShouldNotBeBetweenOrEqual 302 303```go 304func ShouldNotBeBetweenOrEqual(actual interface{}, expected ...interface{}) string 305``` 306ShouldNotBeBetweenOrEqual receives exactly three parameters: an actual value, a 307lower bound, and an upper bound. It ensures that the actual value is nopt 308between the bounds nor equal to either of them. 309 310#### func ShouldNotBeBlank 311 312```go 313func ShouldNotBeBlank(actual interface{}, expected ...interface{}) string 314``` 315ShouldNotBeBlank receives exactly 1 string parameter and ensures that it is 316equal to "". 317 318#### func ShouldNotBeEmpty 319 320```go 321func ShouldNotBeEmpty(actual interface{}, expected ...interface{}) string 322``` 323ShouldNotBeEmpty receives a single parameter (actual) and determines whether or 324not calling len(actual) would return a value greater than zero. It obeys the 325rules specified by the `len` function for determining length: 326http://golang.org/pkg/builtin/#len 327 328#### func ShouldNotBeIn 329 330```go 331func ShouldNotBeIn(actual interface{}, expected ...interface{}) string 332``` 333ShouldNotBeIn receives at least 2 parameters. The first is a proposed member of 334the collection that is passed in either as the second parameter, or of the 335collection that is comprised of all the remaining parameters. This assertion 336ensures that the proposed member is NOT in the collection (using ShouldEqual). 337 338#### func ShouldNotBeNil 339 340```go 341func ShouldNotBeNil(actual interface{}, expected ...interface{}) string 342``` 343ShouldNotBeNil receives a single parameter and ensures that it is not nil. 344 345#### func ShouldNotContain 346 347```go 348func ShouldNotContain(actual interface{}, expected ...interface{}) string 349``` 350ShouldNotContain receives exactly two parameters. The first is a slice and the 351second is a proposed member. Membership is determinied using ShouldEqual. 352 353#### func ShouldNotContainKey 354 355```go 356func ShouldNotContainKey(actual interface{}, expected ...interface{}) string 357``` 358ShouldNotContainKey receives exactly two parameters. The first is a map and the 359second is a proposed absent key. Keys are compared with a simple '=='. 360 361#### func ShouldNotContainSubstring 362 363```go 364func ShouldNotContainSubstring(actual interface{}, expected ...interface{}) string 365``` 366ShouldNotContainSubstring receives exactly 2 string parameters and ensures that 367the first does NOT contain the second as a substring. 368 369#### func ShouldNotEndWith 370 371```go 372func ShouldNotEndWith(actual interface{}, expected ...interface{}) string 373``` 374ShouldEndWith receives exactly 2 string parameters and ensures that the first 375does not end with the second. 376 377#### func ShouldNotEqual 378 379```go 380func ShouldNotEqual(actual interface{}, expected ...interface{}) string 381``` 382ShouldNotEqual receives exactly two parameters and does an inequality check. 383 384#### func ShouldNotHappenOnOrBetween 385 386```go 387func ShouldNotHappenOnOrBetween(actual interface{}, expected ...interface{}) string 388``` 389ShouldNotHappenOnOrBetween receives exactly 3 time.Time arguments and asserts 390that the first does NOT happen between or on the second or third. 391 392#### func ShouldNotHappenWithin 393 394```go 395func ShouldNotHappenWithin(actual interface{}, expected ...interface{}) string 396``` 397ShouldNotHappenWithin receives a time.Time, a time.Duration, and a time.Time (3 398arguments) and asserts that the first time.Time does NOT happen within or on the 399duration specified relative to the other time.Time. 400 401#### func ShouldNotHaveSameTypeAs 402 403```go 404func ShouldNotHaveSameTypeAs(actual interface{}, expected ...interface{}) string 405``` 406ShouldNotHaveSameTypeAs receives exactly two parameters and compares their 407underlying types for inequality. 408 409#### func ShouldNotImplement 410 411```go 412func ShouldNotImplement(actual interface{}, expectedList ...interface{}) string 413``` 414ShouldNotImplement receives exactly two parameters and ensures that the first 415does NOT implement the interface type of the second. 416 417#### func ShouldNotPanic 418 419```go 420func ShouldNotPanic(actual interface{}, expected ...interface{}) (message string) 421``` 422ShouldNotPanic receives a void, niladic function and expects to execute the 423function without any panic. 424 425#### func ShouldNotPanicWith 426 427```go 428func ShouldNotPanicWith(actual interface{}, expected ...interface{}) (message string) 429``` 430ShouldNotPanicWith receives a void, niladic function and expects to recover a 431panic whose content differs from the second argument. 432 433#### func ShouldNotPointTo 434 435```go 436func ShouldNotPointTo(actual interface{}, expected ...interface{}) string 437``` 438ShouldNotPointTo receives exactly two parameters and checks to see that they 439point to different addresess. 440 441#### func ShouldNotResemble 442 443```go 444func ShouldNotResemble(actual interface{}, expected ...interface{}) string 445``` 446ShouldNotResemble receives exactly two parameters and does an inverse deep equal 447check (see reflect.DeepEqual) 448 449#### func ShouldNotStartWith 450 451```go 452func ShouldNotStartWith(actual interface{}, expected ...interface{}) string 453``` 454ShouldNotStartWith receives exactly 2 string parameters and ensures that the 455first does not start with the second. 456 457#### func ShouldPanic 458 459```go 460func ShouldPanic(actual interface{}, expected ...interface{}) (message string) 461``` 462ShouldPanic receives a void, niladic function and expects to recover a panic. 463 464#### func ShouldPanicWith 465 466```go 467func ShouldPanicWith(actual interface{}, expected ...interface{}) (message string) 468``` 469ShouldPanicWith receives a void, niladic function and expects to recover a panic 470with the second argument as the content. 471 472#### func ShouldPointTo 473 474```go 475func ShouldPointTo(actual interface{}, expected ...interface{}) string 476``` 477ShouldPointTo receives exactly two parameters and checks to see that they point 478to the same address. 479 480#### func ShouldResemble 481 482```go 483func ShouldResemble(actual interface{}, expected ...interface{}) string 484``` 485ShouldResemble receives exactly two parameters and does a deep equal check (see 486reflect.DeepEqual) 487 488#### func ShouldStartWith 489 490```go 491func ShouldStartWith(actual interface{}, expected ...interface{}) string 492``` 493ShouldStartWith receives exactly 2 string parameters and ensures that the first 494starts with the second. 495 496#### func So 497 498```go 499func So(actual interface{}, assert assertion, expected ...interface{}) (bool, string) 500``` 501So is a convenience function (as opposed to an inconvenience function?) for 502running assertions on arbitrary arguments in any context, be it for testing or 503even application logging. It allows you to perform assertion-like behavior (and 504get nicely formatted messages detailing discrepancies) but without the program 505blowing up or panicking. All that is required is to import this package and call 506`So` with one of the assertions exported by this package as the second 507parameter. The first return parameter is a boolean indicating if the assertion 508was true. The second return parameter is the well-formatted message showing why 509an assertion was incorrect, or blank if the assertion was correct. 510 511Example: 512 513 if ok, message := So(x, ShouldBeGreaterThan, y); !ok { 514 log.Println(message) 515 } 516 517#### type Assertion 518 519```go 520type Assertion struct { 521} 522``` 523 524 525#### func New 526 527```go 528func New(t testingT) *Assertion 529``` 530New swallows the *testing.T struct and prints failed assertions using t.Error. 531Example: assertions.New(t).So(1, should.Equal, 1) 532 533#### func (*Assertion) Failed 534 535```go 536func (this *Assertion) Failed() bool 537``` 538Failed reports whether any calls to So (on this Assertion instance) have failed. 539 540#### func (*Assertion) So 541 542```go 543func (this *Assertion) So(actual interface{}, assert assertion, expected ...interface{}) bool 544``` 545So calls the standalone So function and additionally, calls t.Error in failure 546scenarios. 547 548#### type Serializer 549 550```go 551type Serializer interface { 552 // contains filtered or unexported methods 553} 554``` 555