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