1package gomega
  2
  3import (
  4	"time"
  5
  6	"github.com/onsi/gomega/matchers"
  7	"github.com/onsi/gomega/types"
  8)
  9
 10//Equal uses reflect.DeepEqual to compare actual with expected.  Equal is strict about
 11//types when performing comparisons.
 12//It is an error for both actual and expected to be nil.  Use BeNil() instead.
 13func Equal(expected interface{}) types.GomegaMatcher {
 14	return &matchers.EqualMatcher{
 15		Expected: expected,
 16	}
 17}
 18
 19//BeEquivalentTo is more lax than Equal, allowing equality between different types.
 20//This is done by converting actual to have the type of expected before
 21//attempting equality with reflect.DeepEqual.
 22//It is an error for actual and expected to be nil.  Use BeNil() instead.
 23func BeEquivalentTo(expected interface{}) types.GomegaMatcher {
 24	return &matchers.BeEquivalentToMatcher{
 25		Expected: expected,
 26	}
 27}
 28
 29//BeIdenticalTo uses the == operator to compare actual with expected.
 30//BeIdenticalTo is strict about types when performing comparisons.
 31//It is an error for both actual and expected to be nil.  Use BeNil() instead.
 32func BeIdenticalTo(expected interface{}) types.GomegaMatcher {
 33	return &matchers.BeIdenticalToMatcher{
 34		Expected: expected,
 35	}
 36}
 37
 38//BeNil succeeds if actual is nil
 39func BeNil() types.GomegaMatcher {
 40	return &matchers.BeNilMatcher{}
 41}
 42
 43//BeTrue succeeds if actual is true
 44func BeTrue() types.GomegaMatcher {
 45	return &matchers.BeTrueMatcher{}
 46}
 47
 48//BeFalse succeeds if actual is false
 49func BeFalse() types.GomegaMatcher {
 50	return &matchers.BeFalseMatcher{}
 51}
 52
 53//HaveOccurred succeeds if actual is a non-nil error
 54//The typical Go error checking pattern looks like:
 55//    err := SomethingThatMightFail()
 56//    Expect(err).ShouldNot(HaveOccurred())
 57func HaveOccurred() types.GomegaMatcher {
 58	return &matchers.HaveOccurredMatcher{}
 59}
 60
 61//Succeed passes if actual is a nil error
 62//Succeed is intended to be used with functions that return a single error value. Instead of
 63//    err := SomethingThatMightFail()
 64//    Expect(err).ShouldNot(HaveOccurred())
 65//
 66//You can write:
 67//    Expect(SomethingThatMightFail()).Should(Succeed())
 68//
 69//It is a mistake to use Succeed with a function that has multiple return values.  Gomega's Ω and Expect
 70//functions automatically trigger failure if any return values after the first return value are non-zero/non-nil.
 71//This means that Ω(MultiReturnFunc()).ShouldNot(Succeed()) can never pass.
 72func Succeed() types.GomegaMatcher {
 73	return &matchers.SucceedMatcher{}
 74}
 75
 76//MatchError succeeds if actual is a non-nil error that matches the passed in string/error.
 77//
 78//These are valid use-cases:
 79//  Expect(err).Should(MatchError("an error")) //asserts that err.Error() == "an error"
 80//  Expect(err).Should(MatchError(SomeError)) //asserts that err == SomeError (via reflect.DeepEqual)
 81//
 82//It is an error for err to be nil or an object that does not implement the Error interface
 83func MatchError(expected interface{}) types.GomegaMatcher {
 84	return &matchers.MatchErrorMatcher{
 85		Expected: expected,
 86	}
 87}
 88
 89//BeClosed succeeds if actual is a closed channel.
 90//It is an error to pass a non-channel to BeClosed, it is also an error to pass nil
 91//
 92//In order to check whether or not the channel is closed, Gomega must try to read from the channel
 93//(even in the `ShouldNot(BeClosed())` case).  You should keep this in mind if you wish to make subsequent assertions about
 94//values coming down the channel.
 95//
 96//Also, if you are testing that a *buffered* channel is closed you must first read all values out of the channel before
 97//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).
 98//
 99//Finally, as a corollary: it is an error to check whether or not a send-only channel is closed.
100func BeClosed() types.GomegaMatcher {
101	return &matchers.BeClosedMatcher{}
102}
103
104//Receive succeeds if there is a value to be received on actual.
105//Actual must be a channel (and cannot be a send-only channel) -- anything else is an error.
106//
107//Receive returns immediately and never blocks:
108//
109//- If there is nothing on the channel `c` then Expect(c).Should(Receive()) will fail and Ω(c).ShouldNot(Receive()) will pass.
110//
111//- If the channel `c` is closed then Expect(c).Should(Receive()) will fail and Ω(c).ShouldNot(Receive()) will pass.
112//
113//- 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.
114//
115//If you have a go-routine running in the background that will write to channel `c` you can:
116//    Eventually(c).Should(Receive())
117//
118//This will timeout if nothing gets sent to `c` (you can modify the timeout interval as you normally do with `Eventually`)
119//
120//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`:
121//    Consistently(c).ShouldNot(Receive())
122//
123//You can pass `Receive` a matcher.  If you do so, it will match the received object against the matcher.  For example:
124//    Expect(c).Should(Receive(Equal("foo")))
125//
126//When given a matcher, `Receive` will always fail if there is nothing to be received on the channel.
127//
128//Passing Receive a matcher is especially useful when paired with Eventually:
129//
130//    Eventually(c).Should(Receive(ContainSubstring("bar")))
131//
132//will repeatedly attempt to pull values out of `c` until a value matching "bar" is received.
133//
134//Finally, 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:
135//    var myThing thing
136//    Eventually(thingChan).Should(Receive(&myThing))
137//    Expect(myThing.Sprocket).Should(Equal("foo"))
138//    Expect(myThing.IsValid()).Should(BeTrue())
139func Receive(args ...interface{}) types.GomegaMatcher {
140	var arg interface{}
141	if len(args) > 0 {
142		arg = args[0]
143	}
144
145	return &matchers.ReceiveMatcher{
146		Arg: arg,
147	}
148}
149
150//BeSent succeeds if a value can be sent to actual.
151//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.
152//In addition, actual must not be closed.
153//
154//BeSent never blocks:
155//
156//- If the channel `c` is not ready to receive then Expect(c).Should(BeSent("foo")) will fail immediately
157//- 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
158//- If the channel `c` is closed then Expect(c).Should(BeSent("foo")) and Ω(c).ShouldNot(BeSent("foo")) will both fail immediately
159//
160//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).
161//Rather, the point of `BeSent` is to make it possible to easily and expressively write tests that can timeout on blocked channel sends.
162func BeSent(arg interface{}) types.GomegaMatcher {
163	return &matchers.BeSentMatcher{
164		Arg: arg,
165	}
166}
167
168//MatchRegexp succeeds if actual is a string or stringer that matches the
169//passed-in regexp.  Optional arguments can be provided to construct a regexp
170//via fmt.Sprintf().
171func MatchRegexp(regexp string, args ...interface{}) types.GomegaMatcher {
172	return &matchers.MatchRegexpMatcher{
173		Regexp: regexp,
174		Args:   args,
175	}
176}
177
178//ContainSubstring succeeds if actual is a string or stringer that contains the
179//passed-in substring.  Optional arguments can be provided to construct the substring
180//via fmt.Sprintf().
181func ContainSubstring(substr string, args ...interface{}) types.GomegaMatcher {
182	return &matchers.ContainSubstringMatcher{
183		Substr: substr,
184		Args:   args,
185	}
186}
187
188//HavePrefix succeeds if actual is a string or stringer that contains the
189//passed-in string as a prefix.  Optional arguments can be provided to construct
190//via fmt.Sprintf().
191func HavePrefix(prefix string, args ...interface{}) types.GomegaMatcher {
192	return &matchers.HavePrefixMatcher{
193		Prefix: prefix,
194		Args:   args,
195	}
196}
197
198//HaveSuffix succeeds if actual is a string or stringer that contains the
199//passed-in string as a suffix.  Optional arguments can be provided to construct
200//via fmt.Sprintf().
201func HaveSuffix(suffix string, args ...interface{}) types.GomegaMatcher {
202	return &matchers.HaveSuffixMatcher{
203		Suffix: suffix,
204		Args:   args,
205	}
206}
207
208//MatchJSON succeeds if actual is a string or stringer of JSON that matches
209//the expected JSON.  The JSONs are decoded and the resulting objects are compared via
210//reflect.DeepEqual so things like key-ordering and whitespace shouldn't matter.
211func MatchJSON(json interface{}) types.GomegaMatcher {
212	return &matchers.MatchJSONMatcher{
213		JSONToMatch: json,
214	}
215}
216
217//MatchXML succeeds if actual is a string or stringer of XML that matches
218//the expected XML.  The XMLs are decoded and the resulting objects are compared via
219//reflect.DeepEqual so things like whitespaces shouldn't matter.
220func MatchXML(xml interface{}) types.GomegaMatcher {
221	return &matchers.MatchXMLMatcher{
222		XMLToMatch: xml,
223	}
224}
225
226//MatchYAML succeeds if actual is a string or stringer of YAML that matches
227//the expected YAML.  The YAML's are decoded and the resulting objects are compared via
228//reflect.DeepEqual so things like key-ordering and whitespace shouldn't matter.
229func MatchYAML(yaml interface{}) types.GomegaMatcher {
230	return &matchers.MatchYAMLMatcher{
231		YAMLToMatch: yaml,
232	}
233}
234
235//BeEmpty succeeds if actual is empty.  Actual must be of type string, array, map, chan, or slice.
236func BeEmpty() types.GomegaMatcher {
237	return &matchers.BeEmptyMatcher{}
238}
239
240//HaveLen succeeds if actual has the passed-in length.  Actual must be of type string, array, map, chan, or slice.
241func HaveLen(count int) types.GomegaMatcher {
242	return &matchers.HaveLenMatcher{
243		Count: count,
244	}
245}
246
247//HaveCap succeeds if actual has the passed-in capacity.  Actual must be of type array, chan, or slice.
248func HaveCap(count int) types.GomegaMatcher {
249	return &matchers.HaveCapMatcher{
250		Count: count,
251	}
252}
253
254//BeZero succeeds if actual is the zero value for its type or if actual is nil.
255func BeZero() types.GomegaMatcher {
256	return &matchers.BeZeroMatcher{}
257}
258
259//ContainElement succeeds if actual contains the passed in element.
260//By default ContainElement() uses Equal() to perform the match, however a
261//matcher can be passed in instead:
262//    Expect([]string{"Foo", "FooBar"}).Should(ContainElement(ContainSubstring("Bar")))
263//
264//Actual must be an array, slice or map.
265//For maps, ContainElement searches through the map's values.
266func ContainElement(element interface{}) types.GomegaMatcher {
267	return &matchers.ContainElementMatcher{
268		Element: element,
269	}
270}
271
272//BeElementOf succeeds if actual is contained in the passed in elements.
273//BeElementOf() always uses Equal() to perform the match.
274//When the passed in elements are comprised of a single element that is either an Array or Slice, BeElementOf() behaves
275//as the reverse of ContainElement() that operates with Equal() to perform the match.
276//    Expect(2).Should(BeElementOf([]int{1, 2}))
277//    Expect(2).Should(BeElementOf([2]int{1, 2}))
278//Otherwise, BeElementOf() provides a syntactic sugar for Or(Equal(_), Equal(_), ...):
279//    Expect(2).Should(BeElementOf(1, 2))
280//
281//Actual must be typed.
282func BeElementOf(elements ...interface{}) types.GomegaMatcher {
283	return &matchers.BeElementOfMatcher{
284		Elements: elements,
285	}
286}
287
288//ConsistOf succeeds if actual contains precisely the elements passed into the matcher.  The ordering of the elements does not matter.
289//By default ConsistOf() uses Equal() to match the elements, however custom matchers can be passed in instead.  Here are some examples:
290//
291//    Expect([]string{"Foo", "FooBar"}).Should(ConsistOf("FooBar", "Foo"))
292//    Expect([]string{"Foo", "FooBar"}).Should(ConsistOf(ContainSubstring("Bar"), "Foo"))
293//    Expect([]string{"Foo", "FooBar"}).Should(ConsistOf(ContainSubstring("Foo"), ContainSubstring("Foo")))
294//
295//Actual must be an array, slice or map.  For maps, ConsistOf matches against the map's values.
296//
297//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
298//is the only element passed in to ConsistOf:
299//
300//    Expect([]string{"Foo", "FooBar"}).Should(ConsistOf([]string{"FooBar", "Foo"}))
301//
302//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.
303func ConsistOf(elements ...interface{}) types.GomegaMatcher {
304	return &matchers.ConsistOfMatcher{
305		Elements: elements,
306	}
307}
308
309//ContainElements succeeds if actual contains the passed in elements. The ordering of the elements does not matter.
310//By default ContainElements() uses Equal() to match the elements, however custom matchers can be passed in instead. Here are some examples:
311//
312//    Expect([]string{"Foo", "FooBar"}).Should(ContainElements("FooBar"))
313//    Expect([]string{"Foo", "FooBar"}).Should(ContainElements(ContainSubstring("Bar"), "Foo"))
314//
315//Actual must be an array, slice or map.
316//For maps, ContainElements searches through the map's values.
317func ContainElements(elements ...interface{}) types.GomegaMatcher {
318	return &matchers.ContainElementsMatcher{
319		Elements: elements,
320	}
321}
322
323//HaveKey succeeds if actual is a map with the passed in key.
324//By default HaveKey uses Equal() to perform the match, however a
325//matcher can be passed in instead:
326//    Expect(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKey(MatchRegexp(`.+Foo$`)))
327func HaveKey(key interface{}) types.GomegaMatcher {
328	return &matchers.HaveKeyMatcher{
329		Key: key,
330	}
331}
332
333//HaveKeyWithValue succeeds if actual is a map with the passed in key and value.
334//By default HaveKeyWithValue uses Equal() to perform the match, however a
335//matcher can be passed in instead:
336//    Expect(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKeyWithValue("Foo", "Bar"))
337//    Expect(map[string]string{"Foo": "Bar", "BazFoo": "Duck"}).Should(HaveKeyWithValue(MatchRegexp(`.+Foo$`), "Bar"))
338func HaveKeyWithValue(key interface{}, value interface{}) types.GomegaMatcher {
339	return &matchers.HaveKeyWithValueMatcher{
340		Key:   key,
341		Value: value,
342	}
343}
344
345//BeNumerically performs numerical assertions in a type-agnostic way.
346//Actual and expected should be numbers, though the specific type of
347//number is irrelevant (float32, float64, uint8, etc...).
348//
349//There are six, self-explanatory, supported comparators:
350//    Expect(1.0).Should(BeNumerically("==", 1))
351//    Expect(1.0).Should(BeNumerically("~", 0.999, 0.01))
352//    Expect(1.0).Should(BeNumerically(">", 0.9))
353//    Expect(1.0).Should(BeNumerically(">=", 1.0))
354//    Expect(1.0).Should(BeNumerically("<", 3))
355//    Expect(1.0).Should(BeNumerically("<=", 1.0))
356func BeNumerically(comparator string, compareTo ...interface{}) types.GomegaMatcher {
357	return &matchers.BeNumericallyMatcher{
358		Comparator: comparator,
359		CompareTo:  compareTo,
360	}
361}
362
363//BeTemporally compares time.Time's like BeNumerically
364//Actual and expected must be time.Time. The comparators are the same as for BeNumerically
365//    Expect(time.Now()).Should(BeTemporally(">", time.Time{}))
366//    Expect(time.Now()).Should(BeTemporally("~", time.Now(), time.Second))
367func BeTemporally(comparator string, compareTo time.Time, threshold ...time.Duration) types.GomegaMatcher {
368	return &matchers.BeTemporallyMatcher{
369		Comparator: comparator,
370		CompareTo:  compareTo,
371		Threshold:  threshold,
372	}
373}
374
375//BeAssignableToTypeOf succeeds if actual is assignable to the type of expected.
376//It will return an error when one of the values is nil.
377//    Expect(0).Should(BeAssignableToTypeOf(0))         // Same values
378//    Expect(5).Should(BeAssignableToTypeOf(-1))        // different values same type
379//    Expect("foo").Should(BeAssignableToTypeOf("bar")) // different values same type
380//    Expect(struct{ Foo string }{}).Should(BeAssignableToTypeOf(struct{ Foo string }{}))
381func BeAssignableToTypeOf(expected interface{}) types.GomegaMatcher {
382	return &matchers.AssignableToTypeOfMatcher{
383		Expected: expected,
384	}
385}
386
387//Panic succeeds if actual is a function that, when invoked, panics.
388//Actual must be a function that takes no arguments and returns no results.
389func Panic() types.GomegaMatcher {
390	return &matchers.PanicMatcher{}
391}
392
393//PanicWith succeeds if actual is a function that, when invoked, panics with a specific value.
394//Actual must be a function that takes no arguments and returns no results.
395//
396//By default PanicWith uses Equal() to perform the match, however a
397//matcher can be passed in instead:
398//    Expect(fn).Should(PanicWith(MatchRegexp(`.+Foo$`)))
399func PanicWith(expected interface{}) types.GomegaMatcher {
400	return &matchers.PanicMatcher{Expected: expected}
401}
402
403//BeAnExistingFile succeeds if a file exists.
404//Actual must be a string representing the abs path to the file being checked.
405func BeAnExistingFile() types.GomegaMatcher {
406	return &matchers.BeAnExistingFileMatcher{}
407}
408
409//BeARegularFile succeeds if a file exists and is a regular file.
410//Actual must be a string representing the abs path to the file being checked.
411func BeARegularFile() types.GomegaMatcher {
412	return &matchers.BeARegularFileMatcher{}
413}
414
415//BeADirectory succeeds if a file exists and is a directory.
416//Actual must be a string representing the abs path to the file being checked.
417func BeADirectory() types.GomegaMatcher {
418	return &matchers.BeADirectoryMatcher{}
419}
420
421//HaveHTTPStatus succeeds if the Status or StatusCode field of an HTTP response matches.
422//Actual must be either a *http.Response or *httptest.ResponseRecorder.
423//Expected must be either an int or a string.
424//  Expect(resp).Should(HaveHTTPStatus(http.StatusOK))   // asserts that resp.StatusCode == 200
425//  Expect(resp).Should(HaveHTTPStatus("404 Not Found")) // asserts that resp.Status == "404 Not Found"
426func HaveHTTPStatus(expected interface{}) types.GomegaMatcher {
427	return &matchers.HaveHTTPStatusMatcher{Expected: expected}
428}
429
430//And succeeds only if all of the given matchers succeed.
431//The matchers are tried in order, and will fail-fast if one doesn't succeed.
432//  Expect("hi").To(And(HaveLen(2), Equal("hi"))
433//
434//And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions.
435func And(ms ...types.GomegaMatcher) types.GomegaMatcher {
436	return &matchers.AndMatcher{Matchers: ms}
437}
438
439//SatisfyAll is an alias for And().
440//  Expect("hi").Should(SatisfyAll(HaveLen(2), Equal("hi")))
441func SatisfyAll(matchers ...types.GomegaMatcher) types.GomegaMatcher {
442	return And(matchers...)
443}
444
445//Or succeeds if any of the given matchers succeed.
446//The matchers are tried in order and will return immediately upon the first successful match.
447//  Expect("hi").To(Or(HaveLen(3), HaveLen(2))
448//
449//And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions.
450func Or(ms ...types.GomegaMatcher) types.GomegaMatcher {
451	return &matchers.OrMatcher{Matchers: ms}
452}
453
454//SatisfyAny is an alias for Or().
455//  Expect("hi").SatisfyAny(Or(HaveLen(3), HaveLen(2))
456func SatisfyAny(matchers ...types.GomegaMatcher) types.GomegaMatcher {
457	return Or(matchers...)
458}
459
460//Not negates the given matcher; it succeeds if the given matcher fails.
461//  Expect(1).To(Not(Equal(2))
462//
463//And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions.
464func Not(matcher types.GomegaMatcher) types.GomegaMatcher {
465	return &matchers.NotMatcher{Matcher: matcher}
466}
467
468//WithTransform applies the `transform` to the actual value and matches it against `matcher`.
469//The given transform must be a function of one parameter that returns one value.
470//  var plus1 = func(i int) int { return i + 1 }
471//  Expect(1).To(WithTransform(plus1, Equal(2))
472//
473//And(), Or(), Not() and WithTransform() allow matchers to be composed into complex expressions.
474func WithTransform(transform interface{}, matcher types.GomegaMatcher) types.GomegaMatcher {
475	return matchers.NewWithTransformMatcher(transform, matcher)
476}
477
478//Satisfy matches the actual value against the `predicate` function.
479//The given predicate must be a function of one paramter that returns bool.
480//  var isEven = func(i int) bool { return i%2 == 0 }
481//  Expect(2).To(Satisfy(isEven))
482func Satisfy(predicate interface{}) types.GomegaMatcher {
483	return matchers.NewSatisfyMatcher(predicate)
484}