The matchers

Argument matchers for stubbing and verifications.

In general the call signature you specify when stubbing or verifying in mockito is as concrete as possible: it consists of values only:

when(os.path).exists('/foo/bar.txt').thenReturn(True)

This is for a reason. In controlled test environments, for the scope of a single test, you should usually know exactly how you use a function, and what you expect its outcome to be. In mockito usually (in strict mode) all invocations you did not specify upfront will throw at call time.

If you reason about your code, the above when tirade turns - for the time of the test - the specific stubbed function into a constant.

You can use so called argument matchers below if you can’t or don’t want to specify a single concrete value for an argument, but a type or class of possible values. E.g.:

when(os.path).exists(...).thenReturn(True)
when(os.path).exists(ANY).thenReturn(True)
when(os.path).exists(ANY(str)).thenReturn(True)

when(requests).get(ANY(str), **kwargs)
when(requests).get('https://example.com', ...)

when(math).sqrt(not_(_or(ANY(float), ANY(int)))).thenRaise(TypeError)

Now what you get each time is a function that up to a degree takes various arguments and responds with the same outcome each time. Now that’s a weird thing. So use the matchers for a reason, they’re powerful.

The one usage you should not care about is a loose signature when using verify(). Since mockito will throw for unexpected calls, a very loose verify should be ok:

verify(requests, times=1).get(...)

mockito.matchers.ANY(wanted_type=None)

Matches against type of argument (isinstance).

If you want to match any type, use either ANY or ANY().

Examples:

when(mock).foo(any).thenReturn(1)
verify(mock).foo(any(int))

mockito.matchers.and_(*matchers)

Matches if all given matchers match

Example:

when(mock).foo(and_(ANY(str), contains('foo')))

mockito.matchers.any(wanted_type=None)

Matches against type of argument (isinstance).

If you want to match any type, use either ANY or ANY().

Examples:

when(mock).foo(any).thenReturn(1)
verify(mock).foo(any(int))

mockito.matchers.any_(wanted_type=None)

Matches against type of argument (isinstance).

If you want to match any type, use either ANY or ANY().

Examples:

when(mock).foo(any).thenReturn(1)
verify(mock).foo(any(int))

mockito.matchers.arg_that(predicate)

Matches any argument for which predicate returns True

Example:

verify(mock).foo(arg_that(lambda arg: arg > 3 and arg < 7))

mockito.matchers.captor(matcher=None)

Returns argument captor that captures values for further assertions

Example:

arg = captor()
mock.do_something(123)
mock.do_something(456)
verify(mock).do_something(arg)
assert arg.value == 456
assert arg.all_values == [123, 456]

You can restrict what the captor captures using the other matchers shown herein:

arg = captor(any(str))
arg = captor(contains("foo"))

mockito.matchers.contains(sub)

Matches any string containing given substring

Example:

mock.foo([120, 121, 122, 123])
verify(mock).foo(contains(123))

mockito.matchers.eq(value)

Matches particular value (==)

mockito.matchers.gt(value)

Matches any value that is greater than given value (>)

mockito.matchers.gte(value)

Matches any value that is greater than or equal to given value (>=)

mockito.matchers.lt(value)

Matches any value that is less than given value (<)

mockito.matchers.lte(value)

Matches any value that is less than or equal to given value (<=)

mockito.matchers.matches(regex, flags=0)

Matches any string that matches given regex

mockito.matchers.neq(value)

Matches any but given value (!=)

mockito.matchers.not_(matcher)

Matches if given matcher does not match

Example:

when(mock).foo(not_(ANY(str))).thenRaise(TypeError)

mockito.matchers.or_(*matchers)

Matches if any given matcher match

Example:

when(mock).foo(or_(ANY(int), ANY(float)))