org.mockito.ArgumentMatcher Maven / Gradle / Ivy
/*
* Copyright (c) 2007 Mockito contributors
* This program is made available under the terms of the MIT License.
*/
package org.mockito;
import org.hamcrest.*;
import org.mockito.internal.util.Decamelizer;
/**
* Allows creating customized argument matchers.
*
* ArgumentMatcher is an hamcrest {@link Matcher} with predefined describeTo() method.
* In case of failure, ArgumentMatcher generates description based on decamelized class name - to promote meaningful class names.
* For example StringWithStrongLanguage matcher will generate 'String with strong language' description.
* You can always override describeTo() method and provide detailed description.
*
* Use {@link Matchers#argThat} method and pass an instance of hamcrest {@link Matcher}, e.g:
*
*
* class IsListOfTwoElements extends ArgumentMatcher<List> {
* public boolean matches(Object list) {
* return ((List) list).size() == 2;
* }
* }
*
* List mock = mock(List.class);
*
* when(mock.addAll(argThat(new IsListOfTwoElements()))).thenReturn(true);
*
* mock.addAll(Arrays.asList("one", "two"));
*
* verify(mock).addAll(argThat(new IsListOfTwoElements()));
*
*
* To keep it readable you may want to extract method, e.g:
*
*
* verify(mock).addAll(argThat(new IsListOfTwoElements()));
* //becomes
* verify(mock).addAll(listOfTwoElements());
*
*
* Warning: Be reasonable with using complicated argument matching, especially custom argument matchers, as it can make the test less readable.
* Sometimes it's better to implement equals() for arguments that are passed to mocks
* (Mockito naturally uses equals() for argument matching).
* This can make the test cleaner.
*
* Also, sometimes {@link ArgumentCaptor} may be a better fit than custom matcher.
* For example, if custom argument matcher is not likely to be reused
* or you just need it to assert on argument values to complete verification of behavior.
*
* Read more about other matchers in javadoc for {@link Matchers} class
*
* @param type of argument
*/
public abstract class ArgumentMatcher extends BaseMatcher {
private static final long serialVersionUID = -2145234737829370369L;
/**
* Returns whether this matcher accepts the given argument.
*
* The method should never assert if the argument doesn't match. It
* should only return false.
*
* @param argument
* the argument
* @return whether this matcher accepts the given argument.
*/
public abstract boolean matches(Object argument);
/*
* By default this method decamlizes matchers name to promote meaningful names for matchers.
*
* For example StringWithStrongLanguage matcher will generate 'String with strong language' description in case of failure.
*
* You might want to override this method to
* provide more specific description of the matcher (useful when
* verification failures are reported).
*
* @param description the description to which the matcher description is
* appended.
*/
public void describeTo(Description description) {
String className = getClass().getSimpleName();
description.appendText(Decamelizer.decamelizeMatcher(className));
}
}