1 package gomega 2 3 import ( 4 "fmt" 5 "time" 6 7 "github.com/google/go-cmp/cmp" 8 "github.com/onsi/gomega/matchers" 9 "github.com/onsi/gomega/types" 10 ) 11 12 // Equal uses reflect.DeepEqual to compare actual with expected. Equal is strict about 13 // types when performing comparisons. 14 // It is an error for both actual and expected to be nil. Use BeNil() instead. 15 func Equal(expected interface{}) types.GomegaMatcher { 16 return &matchers.EqualMatcher{ 17 Expected: expected, 18 } 19 } 20 21 // BeEquivalentTo is more lax than Equal, allowing equality between different types. 22 // This is done by converting actual to have the type of expected before 23 // attempting equality with reflect.DeepEqual. 24 // It is an error for actual and expected to be nil. Use BeNil() instead. 25 func BeEquivalentTo(expected interface{}) types.GomegaMatcher { 26 return &matchers.BeEquivalentToMatcher{ 27 Expected: expected, 28 } 29 } 30 31 // BeComparableTo uses gocmp.Equal from github.com/google/go-cmp (instead of reflect.DeepEqual) to perform a deep comparison. 32 // You can pass cmp.Option as options. 33 // It is an error for actual and expected to be nil. Use BeNil() instead. 34 func BeComparableTo(expected interface{}, opts ...cmp.Option) types.GomegaMatcher { 35 return &matchers.BeComparableToMatcher{ 36 Expected: expected, 37 Options: opts, 38 } 39 } 40 41 // BeIdenticalTo uses the == operator to compare actual with expected. 42 // BeIdenticalTo is strict about types when performing comparisons. 43 // It is an error for both actual and expected to be nil. Use BeNil() instead. 44 func BeIdenticalTo(expected interface{}) types.GomegaMatcher { 45 return &matchers.BeIdenticalToMatcher{ 46 Expected: expected, 47 } 48 } 49 50 // BeNil succeeds if actual is nil 51 func BeNil() types.GomegaMatcher { 52 return &matchers.BeNilMatcher{} 53 } 54 55 // BeTrue succeeds if actual is true 56 // 57 // In general, it's better to use `BeTrueBecause(reason)` to provide a more useful error message if a true check fails. 58 func BeTrue() types.GomegaMatcher { 59 return &matchers.BeTrueMatcher{} 60 } 61 62 // BeFalse succeeds if actual is false 63 // 64 // In general, it's better to use `BeFalseBecause(reason)` to provide a more useful error message if a false check fails. 65 func BeFalse() types.GomegaMatcher { 66 return &matchers.BeFalseMatcher{} 67 } 68 69 // BeTrueBecause succeeds if actual is true and displays the provided reason if it is false 70 // fmt.Sprintf is used to render the reason 71 func BeTrueBecause(format string, args ...any) types.GomegaMatcher { 72 return &matchers.BeTrueMatcher{Reason: fmt.Sprintf(format, args...)} 73 } 74 75 // BeFalseBecause succeeds if actual is false and displays the provided reason if it is true. 76 // fmt.Sprintf is used to render the reason 77 func BeFalseBecause(format string, args ...any) types.GomegaMatcher { 78 return &matchers.BeFalseMatcher{Reason: fmt.Sprintf(format, args...)} 79 } 80 81 // HaveOccurred succeeds if actual is a non-nil error 82 // The typical Go error checking pattern looks like: 83 // 84 // err := SomethingThatMightFail() 85 // Expect(err).ShouldNot(HaveOccurred()) 86 func HaveOccurred() types.GomegaMatcher { 87 return &matchers.HaveOccurredMatcher{} 88 } 89 90 // Succeed passes if actual is a nil error 91 // Succeed is intended to be used with functions that return a single error value. Instead of 92 // 93 // err := SomethingThatMightFail() 94 // Expect(err).ShouldNot(HaveOccurred()) 95 // 96 // You can write: 97 // 98 // Expect(SomethingThatMightFail()).Should(Succeed()) 99 // 100 // It is a mistake to use Succeed with a function that has multiple return values. Gomega's Ω and Expect 101 // functions automatically trigger failure if any return values after the first return value are non-zero/non-nil. 102 // This means that Ω(MultiReturnFunc()).ShouldNot(Succeed()) can never pass. 103 func Succeed() types.GomegaMatcher { 104 return &matchers.SucceedMatcher{} 105 } 106 107 // MatchError succeeds if actual is a non-nil error that matches the passed in 108 // string, error, function, or matcher. 109 // 110 // These are valid use-cases: 111 // 112 // When passed a string: 113 // 114 // Expect(err).To(MatchError("an error")) 115 // 116 // asserts that err.Error() == "an error" 117 // 118 // When passed an error: 119 // 120 // Expect(err).To(MatchError(SomeError)) 121 // 122 // First checks if errors.Is(err, SomeError). 123 // If that fails then it checks if reflect.DeepEqual(err, SomeError) repeatedly for err and any errors wrapped by err 124 // 125 // When passed a matcher: 126 // 127 // Expect(err).To(MatchError(ContainSubstring("sprocket not found"))) 128 // 129 // the matcher is passed err.Error(). In this case it asserts that err.Error() contains substring "sprocket not found" 130 // 131 // When passed a func(err) bool and a description: 132 // 133 // Expect(err).To(MatchError(os.IsNotExist, "IsNotExist")) 134 // 135 // the function is passed err and matches if the return value is true. The description is required to allow Gomega 136 // to print a useful error message. 137 // 138 // It is an error for err to be nil or an object that does not implement the 139 // Error interface 140 // 141 // The optional second argument is a description of the error function, if used. This is required when passing a function but is ignored in all other cases. 142 func MatchError(expected interface{}, functionErrorDescription ...any) types.GomegaMatcher { 143 return &matchers.MatchErrorMatcher{ 144 Expected: expected, 145 FuncErrDescription: functionErrorDescription, 146 } 147 } 148 149 // BeClosed succeeds if actual is a closed channel. 150 // It is an error to pass a non-channel to BeClosed, it is also an error to pass nil 151 // 152 // In order to check whether or not the channel is closed, Gomega must try to read from the channel 153 // (even in the `ShouldNot(BeClosed())` case). You should keep this in mind if you wish to make subsequent assertions about 154 // values coming down the channel. 155 // 156 // Also, if you are testing that a *buffered* channel is closed you must first read all values out of the channel before 157 // asserting that it is closed (it is not possible to detect that a buffered-channel has been closed until all its buffered values are read). 158 // 159 // Finally, as a corollary: it is an error to check whether or not a send-only channel is closed. 160 func BeClosed() types.GomegaMatcher { 161 return &matchers.BeClosedMatcher{} 162 } 163 164 // Receive succeeds if there is a value to be received on actual. 165 // Actual must be a channel (and cannot be a send-only channel) -- anything else is an error. 166 // 167 // Receive returns immediately and never blocks: 168 // 169 // - If there is nothing on the channel `c` then Expect(c).Should(Receive()) will fail and Ω(c).ShouldNot(Receive()) will pass. 170 // 171 // - If the channel `c` is closed then Expect(c).Should(Receive()) will fail and Ω(c).ShouldNot(Receive()) will pass. 172 // 173 // - If there is something on the channel `c` ready to be read, then Expect(c).Should(Receive()) will pass and Ω(c).ShouldNot(Receive()) will fail. 174 // 175 // If you have a go-routine running in the background that will write to channel `c` you can: 176 // 177 // Eventually(c).Should(Receive()) 178 // 179 // This will timeout if nothing gets sent to `c` (you can modify the timeout interval as you normally do with `Eventually`) 180 // 181 // A similar use-case is to assert that no go-routine writes to a channel (for a period of time). You can do this with `Consistently`: 182 // 183 // Consistently(c).ShouldNot(Receive()) 184 // 185 // You can pass `Receive` a matcher. If you do so, it will match the received object against the matcher. For example: 186 // 187 // Expect(c).Should(Receive(Equal("foo"))) 188 // 189 // When given a matcher, `Receive` will always fail if there is nothing to be received on the channel. 190 // 191 // Passing Receive a matcher is especially useful when paired with Eventually: 192 // 193 // Eventually(c).Should(Receive(ContainSubstring("bar"))) 194 // 195 // will repeatedly attempt to pull values out of `c` until a value matching "bar" is received. 196 // 197 // Furthermore, if you want to have a reference to the value *sent* to the channel you can pass the `Receive` matcher a pointer to a variable of the appropriate type: 198 // 199 // var myThing thing 200 // Eventually(thingChan).Should(Receive(&myThing)) 201 // Expect(myThing.Sprocket).Should(Equal("foo")) 202 // Expect(myThing.IsValid()).Should(BeTrue()) 203 // 204 // Finally, if you want to match the received object as well as get the actual received value into a variable, so you can reason further about the value received, 205 // you can pass a pointer to a variable of the approriate type first, and second a matcher: 206 // 207 // var myThing thing 208 // Eventually(thingChan).Should(Receive(&myThing, ContainSubstring("bar"))) 209 func Receive(args ...interface{}) types.GomegaMatcher { 210 return &matchers.ReceiveMatcher{ 211 Args: args, 212 } 213 } 214 215 // BeSent succeeds if a value can be sent to actual. 216 // Actual must be a channel (and cannot be a receive-only channel) that can sent the type of the value passed into BeSent -- anything else is an error. 217 // In addition, actual must not be closed. 218 // 219 // BeSent never blocks: 220 // 221 // - If the channel `c` is not ready to receive then Expect(c).Should(BeSent("foo")) will fail immediately 222 // - If the channel `c` is eventually ready to receive then Eventually(c).Should(BeSent("foo")) will succeed.. presuming the channel becomes ready to receive before Eventually's timeout 223 // - If the channel `c` is closed then Expect(c).Should(BeSent("foo")) and Ω(c).ShouldNot(BeSent("foo")) will both fail immediately 224 // 225 // Of course, the value is actually sent to the channel. The point of `BeSent` is less to make an assertion about the availability of the channel (which is typically an implementation detail that your test should not be concerned with). 226 // Rather, the point of `BeSent` is to make it possible to easily and expressively write tests that can timeout on blocked channel sends. 227 func BeSent(arg interface{}) types.GomegaMatcher { 228 return &matchers.BeSentMatcher{ 229 Arg: arg, 230 } 231 } 232 233 // MatchRegexp succeeds if actual is a string or stringer that matches the 234 // passed-in regexp. Optional arguments can be provided to construct a regexp 235 // via fmt.Sprintf(). 236 func MatchRegexp(regexp string, args ...interface{}) types.GomegaMatcher { 237 return &matchers.MatchRegexpMatcher{ 238 Regexp: regexp, 239 Args: args, 240 } 241 } 242 243 // ContainSubstring succeeds if actual is a string or stringer that contains the 244 // passed-in substring. Optional arguments can be provided to construct the substring 245 // via fmt.Sprintf(). 246 func ContainSubstring(substr string, args ...interface{}) types.GomegaMatcher { 247 return &matchers.ContainSubstringMatcher{ 248 Substr: substr, 249 Args: args, 250 } 251 } 252 253 // HavePrefix succeeds if actual is a string or stringer that contains the 254 // passed-in string as a prefix. Optional arguments can be provided to construct 255 // via fmt.Sprintf(). 256 func HavePrefix(prefix string, args ...interface{}) types.GomegaMatcher { 257 return &matchers.HavePrefixMatcher{ 258 Prefix: prefix, 259 Args: args, 260 } 261 } 262 263 // HaveSuffix succeeds if actual is a string or stringer that contains the 264 // passed-in string as a suffix. Optional arguments can be provided to construct 265 // via fmt.Sprintf(). 266 func HaveSuffix(suffix string, args ...interface{}) types.GomegaMatcher { 267 return &matchers.HaveSuffixMatcher{ 268 Suffix: suffix, 269 Args: args, 270 } 271 } 272 273 // MatchJSON succeeds if actual is a string or stringer of JSON that matches 274 // the expected JSON. The JSONs are decoded and the resulting objects are compared via 275 // reflect.DeepEqual so things like key-ordering and whitespace shouldn't matter. 276 func MatchJSON(json interface{}) types.GomegaMatcher { 277 return &matchers.MatchJSONMatcher{ 278 JSONToMatch: json, 279 } 280 } 281 282 // MatchXML succeeds if actual is a string or stringer of XML that matches 283 // the expected XML. The XMLs are decoded and the resulting objects are compared via 284 // reflect.DeepEqual so things like whitespaces shouldn't matter. 285 func MatchXML(xml interface{}) types.GomegaMatcher { 286 return &matchers.MatchXMLMatcher{ 287 XMLToMatch: xml, 288 } 289 } 290 291 // MatchYAML succeeds if actual is a string or stringer of YAML that matches 292 // the expected YAML. The YAML's are decoded and the resulting objects are compared via 293 // reflect.DeepEqual so things like key-ordering and whitespace shouldn't matter. 294 func MatchYAML(yaml interface{}) types.GomegaMatcher { 295 return &matchers.MatchYAMLMatcher{ 296 YAMLToMatch: yaml, 297 } 298 } 299 300 // BeEmpty succeeds if actual is empty. Actual must be of type string, array, map, chan, or slice. 301 func BeEmpty() types.GomegaMatcher { 302 return &matchers.BeEmptyMatcher{} 303 } 304 305 // HaveLen succeeds if actual has the passed-in length. Actual must be of type string, array, map, chan, or slice. 306 func HaveLen(count int) types.GomegaMatcher { 307 return &matchers.HaveLenMatcher{ 308 Count: count, 309 } 310 } 311 312 // HaveCap succeeds if actual has the passed-in capacity. Actual must be of type array, chan, or slice. 313 func HaveCap(count int) types.GomegaMatcher { 314 return &matchers.HaveCapMatcher{ 315 Count: count, 316 } 317 } 318 319 // BeZero succeeds if actual is the zero value for its type or if actual is nil. 320 func BeZero() types.GomegaMatcher { 321 return &matchers.BeZeroMatcher{} 322 } 323 324 // ContainElement succeeds if actual contains the passed in element. By default 325 // ContainElement() uses Equal() to perform the match, however a matcher can be 326 // passed in instead: 327 // 328 // Expect([]string{"Foo", "FooBar"}).Should(ContainElement(ContainSubstring("Bar"))) 329 // 330 // Actual must be an array, slice or map. For maps, ContainElement searches 331 // through the map's values. 332 // 333 // If you want to have a copy of the matching element(s) found you can pass a 334 // pointer to a variable of the appropriate type. If the variable isn't a slice 335 // or map, then exactly one match will be expected and returned. If the variable 336 // is a slice or map, then at least one match is expected and all matches will be 337 // stored in the variable. 338 // 339 // var findings []string 340 // Expect([]string{"Foo", "FooBar"}).Should(ContainElement(ContainSubString("Bar", &findings))) 341 func ContainElement(element interface{}, result ...interface{}) types.GomegaMatcher { 342 return &matchers.ContainElementMatcher{ 343 Element: element, 344 Result: result, 345 } 346 } 347 348 // BeElementOf succeeds if actual is contained in the passed in elements. 349 // BeElementOf() always uses Equal() to perform the match. 350 // When the passed in elements are comprised of a single element that is either an Array or Slice, BeElementOf() behaves 351 // as the reverse of ContainElement() that operates with Equal() to perform the match. 352 // 353 // Expect(2).Should(BeElementOf([]int{1, 2})) 354 // Expect(2).Should(BeElementOf([2]int{1, 2})) 355 // 356 // Otherwise, BeElementOf() provides a syntactic sugar for Or(Equal(_), Equal(_), ...): 357 // 358 // Expect(2).Should(BeElementOf(1, 2)) 359 // 360 // Actual must be typed. 361 func BeElementOf(elements ...interface{}) types.GomegaMatcher { 362 return &matchers.BeElementOfMatcher{ 363 Elements: elements, 364 } 365 } 366 367 // BeKeyOf succeeds if actual is contained in the keys of the passed in map. 368 // BeKeyOf() always uses Equal() to perform the match between actual and the map keys. 369 // 370 // Expect("foo").Should(BeKeyOf(map[string]bool{"foo": true, "bar": false})) 371 func BeKeyOf(element interface{}) types.GomegaMatcher { 372 return &matchers.BeKeyOfMatcher{ 373 Map: element, 374 } 375 } 376 377 // ConsistOf succeeds if actual contains precisely the elements passed into the matcher. The ordering of the elements does not matter. 378 // By default ConsistOf() uses Equal() to match the elements, however custom matchers can be passed in instead. Here are some examples: 379 // 380 // Expect([]string{"Foo", "FooBar"}).Should(ConsistOf("FooBar", "Foo")) 381 // Expect([]string{"Foo", "FooBar"}).Should(ConsistOf(ContainSubstring("Bar"), "Foo")) 382 // Expect([]string{"Foo", "FooBar"}).Should(ConsistOf(ContainSubstring("Foo"), ContainSubstring("Foo"))) 383 // 384 // Actual must be an array, slice or map. For maps, ConsistOf matches against the map's values. 385 // 386 // You typically pass variadic arguments to ConsistOf (as in the examples above). However, if you need to pass in a slice you can provided that it 387 // is the only element passed in to ConsistOf: 388 // 389 // Expect([]string{"Foo", "FooBar"}).Should(ConsistOf([]string{"FooBar", "Foo"})) 390 // 391 // Note that Go's type system does not allow you to write this as ConsistOf([]string{"FooBar", "Foo"}...) as []string and []interface{} are different types - hence the need for this special rule. 392 func ConsistOf(elements ...interface{}) types.GomegaMatcher { 393 return &matchers.ConsistOfMatcher{ 394 Elements: elements, 395 } 396 } 397 398 // HaveExactElements succeeds if actual contains elements that precisely match the elemets passed into the matcher. The ordering of the elements does matter. 399 // By default HaveExactElements() uses Equal() to match the elements, however custom matchers can be passed in instead. Here are some examples: 400 // 401 // Expect([]string{"Foo", "FooBar"}).Should(HaveExactElements("Foo", "FooBar")) 402 // Expect([]string{"Foo", "FooBar"}).Should(HaveExactElements("Foo", ContainSubstring("Bar"))) 403 // Expect([]string{"Foo", "FooBar"}).Should(HaveExactElements(ContainSubstring("Foo"), ContainSubstring("Foo"))) 404 // 405 // Actual must be an array or slice. 406 func HaveExactElements(elements ...interface{}) types.GomegaMatcher { 407 return &matchers.HaveExactElementsMatcher{ 408 Elements: elements, 409 } 410 } 411 412 // ContainElements succeeds if actual contains the passed in elements. The ordering of the elements does not matter. 413 // By default ContainElements() uses Equal() to match the elements, however custom matchers can be passed in instead. Here are some examples: 414 // 415 // Expect([]string{"Foo", "FooBar"}).Should(ContainElements("FooBar")) 416 // Expect([]string{"Foo", "FooBar"}).Should(ContainElements(ContainSubstring("Bar"), "Foo")) 417 // 418 // Actual must be an array, slice or map. 419 // For maps, ContainElements searches through the map's values. 420 func ContainElements(elements ...interface{}) types.GomegaMatcher { 421 return &matchers.ContainElementsMatcher{ 422 Elements: elements, 423 } 424 } 425 426 // HaveEach succeeds if actual solely contains elements that match the passed in element. 427 // Please note that if actual is empty, HaveEach always will fail. 428 // By default HaveEach() uses Equal() to perform the match, however a 429 // matcher can be passed in instead: 430 // 431 // Expect([]string{"Foo", "FooBar"}).Should(HaveEach(ContainSubstring("Foo"))) 432 // 433 // Actual must be an array, slice or map. 434 // For maps, HaveEach searches through the map's values. 435 func HaveEach(element interface{}) types.GomegaMatcher { 436 return &matchers.HaveEachMatcher{ 437 Element: element, 438 } 439 } 440 441 // HaveKey succeeds if actual is a map with the passed in key. 442 // By default HaveKey uses Equal() to perform the match, however a 443 // matcher can be passed in instead: 444 // 445 // Expect(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKey(MatchRegexp(`.+Foo$`))) 446 func HaveKey(key interface{}) types.GomegaMatcher { 447 return &matchers.HaveKeyMatcher{ 448 Key: key, 449 } 450 } 451 452 // HaveKeyWithValue succeeds if actual is a map with the passed in key and value. 453 // By default HaveKeyWithValue uses Equal() to perform the match, however a 454 // matcher can be passed in instead: 455 // 456 // Expect(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKeyWithValue("Foo", "Bar")) 457 // Expect(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKeyWithValue(MatchRegexp(`.+Foo$`), "Bar")) 458 func HaveKeyWithValue(key interface{}, value interface{}) types.GomegaMatcher { 459 return &matchers.HaveKeyWithValueMatcher{ 460 Key: key, 461 Value: value, 462 } 463 } 464 465 // HaveField succeeds if actual is a struct and the value at the passed in field 466 // matches the passed in matcher. By default HaveField used Equal() to perform the match, 467 // however a matcher can be passed in in stead. 468 // 469 // The field must be a string that resolves to the name of a field in the struct. Structs can be traversed 470 // using the '.' delimiter. If the field ends with '()' a method named field is assumed to exist on the struct and is invoked. 471 // Such methods must take no arguments and return a single value: 472 // 473 // type Book struct { 474 // Title string 475 // Author Person 476 // } 477 // type Person struct { 478 // FirstName string 479 // LastName string 480 // DOB time.Time 481 // } 482 // Expect(book).To(HaveField("Title", "Les Miserables")) 483 // Expect(book).To(HaveField("Title", ContainSubstring("Les")) 484 // Expect(book).To(HaveField("Author.FirstName", Equal("Victor")) 485 // Expect(book).To(HaveField("Author.DOB.Year()", BeNumerically("<", 1900)) 486 func HaveField(field string, expected interface{}) types.GomegaMatcher { 487 return &matchers.HaveFieldMatcher{ 488 Field: field, 489 Expected: expected, 490 } 491 } 492 493 // HaveExistingField succeeds if actual is a struct and the specified field 494 // exists. 495 // 496 // HaveExistingField can be combined with HaveField in order to cover use cases 497 // with optional fields. HaveField alone would trigger an error in such situations. 498 // 499 // Expect(MrHarmless).NotTo(And(HaveExistingField("Title"), HaveField("Title", "Supervillain"))) 500 func HaveExistingField(field string) types.GomegaMatcher { 501 return &matchers.HaveExistingFieldMatcher{ 502 Field: field, 503 } 504 } 505 506 // HaveValue applies the given matcher to the value of actual, optionally and 507 // repeatedly dereferencing pointers or taking the concrete value of interfaces. 508 // Thus, the matcher will always be applied to non-pointer and non-interface 509 // values only. HaveValue will fail with an error if a pointer or interface is 510 // nil. It will also fail for more than 31 pointer or interface dereferences to 511 // guard against mistakenly applying it to arbitrarily deep linked pointers. 512 // 513 // HaveValue differs from gstruct.PointTo in that it does not expect actual to 514 // be a pointer (as gstruct.PointTo does) but instead also accepts non-pointer 515 // and even interface values. 516 // 517 // actual := 42 518 // Expect(actual).To(HaveValue(42)) 519 // Expect(&actual).To(HaveValue(42)) 520 func HaveValue(matcher types.GomegaMatcher) types.GomegaMatcher { 521 return &matchers.HaveValueMatcher{ 522 Matcher: matcher, 523 } 524 } 525 526 // BeNumerically performs numerical assertions in a type-agnostic way. 527 // Actual and expected should be numbers, though the specific type of 528 // number is irrelevant (float32, float64, uint8, etc...). 529 // 530 // There are six, self-explanatory, supported comparators: 531 // 532 // Expect(1.0).Should(BeNumerically("==", 1)) 533 // Expect(1.0).Should(BeNumerically("~", 0.999, 0.01)) 534 // Expect(1.0).Should(BeNumerically(">", 0.9)) 535 // Expect(1.0).Should(BeNumerically(">=", 1.0)) 536 // Expect(1.0).Should(BeNumerically("<", 3)) 537 // Expect(1.0).Should(BeNumerically("<=", 1.0)) 538 func BeNumerically(comparator string, compareTo ...interface{}) types.GomegaMatcher { 539 return &matchers.BeNumericallyMatcher{ 540 Comparator: comparator, 541 CompareTo: compareTo, 542 } 543 } 544 545 // BeTemporally compares time.Time's like BeNumerically 546 // Actual and expected must be time.Time. The comparators are the same as for BeNumerically 547 // 548 // Expect(time.Now()).Should(BeTemporally(">", time.Time{})) 549 // Expect(time.Now()).Should(BeTemporally("~", time.Now(), time.Second)) 550 func BeTemporally(comparator string, compareTo time.Time, threshold ...time.Duration) types.GomegaMatcher { 551 return &matchers.BeTemporallyMatcher{ 552 Comparator: comparator, 553 CompareTo: compareTo, 554 Threshold: threshold, 555 } 556 } 557 558 // BeAssignableToTypeOf succeeds if actual is assignable to the type of expected. 559 // It will return an error when one of the values is nil. 560 // 561 // Expect(0).Should(BeAssignableToTypeOf(0)) // Same values 562 // Expect(5).Should(BeAssignableToTypeOf(-1)) // different values same type 563 // Expect("foo").Should(BeAssignableToTypeOf("bar")) // different values same type 564 // Expect(struct{ Foo string }{}).Should(BeAssignableToTypeOf(struct{ Foo string }{})) 565 func BeAssignableToTypeOf(expected interface{}) types.GomegaMatcher { 566 return &matchers.AssignableToTypeOfMatcher{ 567 Expected: expected, 568 } 569 } 570 571 // Panic succeeds if actual is a function that, when invoked, panics. 572 // Actual must be a function that takes no arguments and returns no results. 573 func Panic() types.GomegaMatcher { 574 return &matchers.PanicMatcher{} 575 } 576 577 // PanicWith succeeds if actual is a function that, when invoked, panics with a specific value. 578 // Actual must be a function that takes no arguments and returns no results. 579 // 580 // By default PanicWith uses Equal() to perform the match, however a 581 // matcher can be passed in instead: 582 // 583 // Expect(fn).Should(PanicWith(MatchRegexp(`.+Foo$`))) 584 func PanicWith(expected interface{}) types.GomegaMatcher { 585 return &matchers.PanicMatcher{Expected: expected} 586 } 587 588 // BeAnExistingFile succeeds if a file exists. 589 // Actual must be a string representing the abs path to the file being checked. 590 func BeAnExistingFile() types.GomegaMatcher { 591 return &matchers.BeAnExistingFileMatcher{} 592 } 593 594 // BeARegularFile succeeds if a file exists and is a regular file. 595 // Actual must be a string representing the abs path to the file being checked. 596 func BeARegularFile() types.GomegaMatcher { 597 return &matchers.BeARegularFileMatcher{} 598 } 599 600 // BeADirectory succeeds if a file exists and is a directory. 601 // Actual must be a string representing the abs path to the file being checked. 602 func BeADirectory() types.GomegaMatcher { 603 return &matchers.BeADirectoryMatcher{} 604 } 605 606 // HaveHTTPStatus succeeds if the Status or StatusCode field of an HTTP response matches. 607 // Actual must be either a *http.Response or *httptest.ResponseRecorder. 608 // Expected must be either an int or a string. 609 // 610 // Expect(resp).Should(HaveHTTPStatus(http.StatusOK)) // asserts that resp.StatusCode == 200 611 // Expect(resp).Should(HaveHTTPStatus("404 Not Found")) // asserts that resp.Status == "404 Not Found" 612 // Expect(resp).Should(HaveHTTPStatus(http.StatusOK, http.StatusNoContent)) // asserts that resp.StatusCode == 200 || resp.StatusCode == 204 613 func HaveHTTPStatus(expected ...interface{}) types.GomegaMatcher { 614 return &matchers.HaveHTTPStatusMatcher{Expected: expected} 615 } 616 617 // HaveHTTPHeaderWithValue succeeds if the header is found and the value matches. 618 // Actual must be either a *http.Response or *httptest.ResponseRecorder. 619 // Expected must be a string header name, followed by a header value which 620 // can be a string, or another matcher. 621 func HaveHTTPHeaderWithValue(header string, value interface{}) types.GomegaMatcher { 622 return &matchers.HaveHTTPHeaderWithValueMatcher{ 623 Header: header, 624 Value: value, 625 } 626 } 627 628 // HaveHTTPBody matches if the body matches. 629 // Actual must be either a *http.Response or *httptest.ResponseRecorder. 630 // Expected must be either a string, []byte, or other matcher 631 func HaveHTTPBody(expected interface{}) types.GomegaMatcher { 632 return &matchers.HaveHTTPBodyMatcher{Expected: expected} 633 } 634 635 // And succeeds only if all of the given matchers succeed. 636 // The matchers are tried in order, and will fail-fast if one doesn't succeed. 637 // 638 // Expect("hi").To(And(HaveLen(2), Equal("hi")) 639 // 640 // And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions. 641 func And(ms ...types.GomegaMatcher) types.GomegaMatcher { 642 return &matchers.AndMatcher{Matchers: ms} 643 } 644 645 // SatisfyAll is an alias for And(). 646 // 647 // Expect("hi").Should(SatisfyAll(HaveLen(2), Equal("hi"))) 648 func SatisfyAll(matchers ...types.GomegaMatcher) types.GomegaMatcher { 649 return And(matchers...) 650 } 651 652 // Or succeeds if any of the given matchers succeed. 653 // The matchers are tried in order and will return immediately upon the first successful match. 654 // 655 // Expect("hi").To(Or(HaveLen(3), HaveLen(2)) 656 // 657 // And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions. 658 func Or(ms ...types.GomegaMatcher) types.GomegaMatcher { 659 return &matchers.OrMatcher{Matchers: ms} 660 } 661 662 // SatisfyAny is an alias for Or(). 663 // 664 // Expect("hi").SatisfyAny(Or(HaveLen(3), HaveLen(2)) 665 func SatisfyAny(matchers ...types.GomegaMatcher) types.GomegaMatcher { 666 return Or(matchers...) 667 } 668 669 // Not negates the given matcher; it succeeds if the given matcher fails. 670 // 671 // Expect(1).To(Not(Equal(2)) 672 // 673 // And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions. 674 func Not(matcher types.GomegaMatcher) types.GomegaMatcher { 675 return &matchers.NotMatcher{Matcher: matcher} 676 } 677 678 // WithTransform applies the `transform` to the actual value and matches it against `matcher`. 679 // The given transform must be either a function of one parameter that returns one value or a 680 // function of one parameter that returns two values, where the second value must be of the 681 // error type. 682 // 683 // var plus1 = func(i int) int { return i + 1 } 684 // Expect(1).To(WithTransform(plus1, Equal(2)) 685 // 686 // var failingplus1 = func(i int) (int, error) { return 42, "this does not compute" } 687 // Expect(1).To(WithTransform(failingplus1, Equal(2))) 688 // 689 // And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions. 690 func WithTransform(transform interface{}, matcher types.GomegaMatcher) types.GomegaMatcher { 691 return matchers.NewWithTransformMatcher(transform, matcher) 692 } 693 694 // Satisfy matches the actual value against the `predicate` function. 695 // The given predicate must be a function of one paramter that returns bool. 696 // 697 // var isEven = func(i int) bool { return i%2 == 0 } 698 // Expect(2).To(Satisfy(isEven)) 699 func Satisfy(predicate interface{}) types.GomegaMatcher { 700 return matchers.NewSatisfyMatcher(predicate) 701 } 702