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