How to use isMatchesMethod method of org.mockito.internal.invocation.TypeSafeMatching class

As of Java 11, WildFly 14+ and Mockito 2.23.0+, adding jdk.unsupported module dependency to your WAR solves the problem. You can do this in two ways:

A. META-INF/MANIFEST.MF

Add the following line to META_INF/MANIFEST.MF of your WAR archive:

Dependencies: jdk.unsupported

Note that the file must end with a new line or carriage return.

Here is how you'd typically do it with ShrinkWrap/Arquillian:

@Deployment
public static WebArchive createDeployment() {
    return ShrinkWrap.create(WebArchive.class, "my-app.war")
        .addPackages(true, Mockito.class.getPackage(), Objenesis.class.getPackage(), ByteBuddy.class.getPackage())
        .addAsManifestResource(new StringAsset("Dependencies: jdk.unsupported\n" /* required by Mockito */), "MANIFEST.MF");
}

B. WEB-INF/jboss-deployment-structure.xml

Add the following content to WEB-INF/jboss-deployment-structure.xml of your WAR archive:

<jboss-deployment-structure>
  <deployment>
    <dependencies>
      <module name="jdk.unsupported" />
    </dependencies>
  </deployment>
</jboss-deployment-structure>

One way could be to avoid being too restrictive on your arguments in order to provide all the expected results with only one thenReturn call.

For example let's say that I want to mock this method:

public String foo(String firstArgument, Object obj) {
    return "Something";
}

You could then mock it by providing as many results as you want like below:

// Mock the call of foo of any String to provide 3 results
when(mock.foo(anyString(), anyObject())).thenReturn("val1", "val2", "val3");

Calls to foo with any parameters will provide respectively "val1", "val2", then any subsequent calls will provide "val3".

In case you do care about passed values but don't want to depend on call sequence you can use thenAnswer to provide an answer that matches with the second argument like you currently do but with 3 different thenReturn. Assuming that you have overridden the method equals(Object o).

when(mock.foo(anyString(), anyObject())).thenAnswer(
    invocation -> {
        Object argument = invocation.getArguments()[1];
        if (argument.equals(new ARequest(1, "A"))) {
            return new AResponse(1, "passed");
        } else if (argument.equals(new ARequest(2, "2A"))) {
            return new AResponse(2, "passed");
        } else if (argument.equals(new BRequest(1, "B"))) {
            return new BResponse(112, "passed");
        }
        throw new InvalidUseOfMatchersException(
            String.format("Argument %s does not match", argument)
        );
    }
);

Or simply, using the methods anyString and eq as argument marchers. Assuming that you have overridden the method equals(Object o).

when(service.foo(anyString(), eq(new ARequest(1, "A"))))
    .thenReturn(new AResponse(1, "passed"));
when(service.foo(anyString(), eq(new ARequest(2, "2A"))))
    .thenReturn(new AResponse(2, "passed"));
when(service.foo(anyString(), eq(new BRequest(1, "B"))))
    .thenReturn(new BResponse(112, "passed"));

See Update below: You don't need a Factory

If you are using Jersey 2, one solution would be to use Custom Injection and Lifecycle Management feature (with HK2 - which comes with the Jersey dist). Also required would be a Mocking framework of course. I'm going to use Mockito.

First create a Factory with mocked instance:

public static interface GreetingService {
    public String getGreeting(String name);
}

public static class MockGreetingServiceFactory 
                                     implements Factory<GreetingService> {
    @Override
    public GreetingService provide() {
        final GreetingService mockedService
                = Mockito.mock(GreetingService.class);
        Mockito.when(mockedService.getGreeting(Mockito.anyString()))
                .thenAnswer(new Answer<String>() {
                    @Override
                    public String answer(InvocationOnMock invocation) 
                                                      throws Throwable {
                        String name = (String)invocation.getArguments()[0];
                        return "Hello " + name;
                    }

                });
        return mockedService;
    }

    @Override
    public void dispose(GreetingService t) {}
}

Then use the AbstractBinder to bind the factory to the interface/service class, and register the binder. (It's all described in the link above):

@Override
public Application configure() {
    AbstractBinder binder = new AbstractBinder() {
        @Override
        protected void configure() {
            bindFactory(MockGreetingServiceFactory.class)
                               .to(GreetingService.class);
        }
    };
    ResourceConfig config = new ResourceConfig(GreetingResource.class);
    config.register(binder);
    return config;
}

Seems like a lot, but it's just an option. I'm not too familiar with the test framework, or if it has an mocking capabilities for injection.

Here is the full test:

import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.core.Application;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import org.glassfish.hk2.api.Factory;
import org.glassfish.hk2.utilities.binding.AbstractBinder;
import org.glassfish.jersey.server.ResourceConfig;
import org.glassfish.jersey.test.JerseyTest;
import org.junit.Assert;
import org.junit.Test;
import org.mockito.Mockito;
import org.mockito.invocation.InvocationOnMock;
import org.mockito.stubbing.Answer;

public class ServiceMockingTest extends JerseyTest {

    @Path("/greeting")
    public static class GreetingResource {

        @Inject
        private GreetingService greetingService;

        @GET
        @Produces(MediaType.TEXT_PLAIN)
        public String getGreeting(@QueryParam("name") String name) {
            return greetingService.getGreeting(name);
        }
    }

    public static interface GreetingService {
        public String getGreeting(String name);
    }
    
    public static class MockGreetingServiceFactory 
                                  implements Factory<GreetingService> {
        @Override
        public GreetingService provide() {
            final GreetingService mockedService
                    = Mockito.mock(GreetingService.class);
            Mockito.when(mockedService.getGreeting(Mockito.anyString()))
                    .thenAnswer(new Answer<String>() {
                        @Override
                        public String answer(InvocationOnMock invocation) 
                                                       throws Throwable {
                            String name = (String)invocation.getArguments()[0];
                            return "Hello " + name;
                        }

                    });
            return mockedService;
        }

        @Override
        public void dispose(GreetingService t) {}
    }

    @Override
    public Application configure() {
        AbstractBinder binder = new AbstractBinder() {
            @Override
            protected void configure() {
                bindFactory(MockGreetingServiceFactory.class)
                        .to(GreetingService.class);
            }
        };
        ResourceConfig config = new ResourceConfig(GreetingResource.class);
        config.register(binder);
        return config;
    }
    
    @Test
    public void testMockedGreetingService() {
        Client client = ClientBuilder.newClient();
        Response response = client.target("http://localhost:9998/greeting")
                .queryParam("name", "peeskillet")
                .request(MediaType.TEXT_PLAIN).get();
        Assert.assertEquals(200, response.getStatus());
        
        String msg = response.readEntity(String.class);
        Assert.assertEquals("Hello peeskillet", msg);
        System.out.println("Message: " + msg);
        
        response.close();
        client.close();
       
    }
}

Dependencies for this test:

<dependency>
    <groupId>org.glassfish.jersey.test-framework.providers</groupId>
    <artifactId>jersey-test-framework-provider-grizzly2</artifactId>
    <version>2.13</version>
</dependency>
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-all</artifactId>
    <version>1.9.0</version>
</dependency>

UPDATE

So in most cases, you really don't need a Factory. You can simply bind the mock instance with its contract:

@Mock
private Service service;

@Override
public ResourceConfig configure() {
    MockitoAnnotations.initMocks(this);
    return new ResourceConfig()
        .register(MyResource.class)
        .register(new AbstractBinder() {
            @Override
            protected configure() {
                bind(service).to(Service.class);
            }
        });
}

@Test
public void test() {
    when(service.getSomething()).thenReturn("Something");
    // test
}

Much simpler!

To answer your second question first. If you're using JUnit 4, you can annotate your test with

@Test(expected=MyException.class)

to assert that an exception has occured. And to "mock" an exception with mockito, use

when(myMock.doSomething()).thenThrow(new MyException());

Technically speaking both "mocks" and "spies" are a special kind of "test doubles".

Mockito is unfortunately making the distinction weird.

A mock in mockito is a normal mock in other mocking frameworks (allows you to stub invocations; that is, return specific values out of method calls).

A spy in mockito is a partial mock in other mocking frameworks (part of the object will be mocked and part will use real method invocations).

The nested generics-problem can be avoided with the @Captor annotation:

public class Test{

    @Mock
    private Service service;

    @Captor
    private ArgumentCaptor<ArrayList<SomeType>> captor;

    @Before
    public void init(){
        MockitoAnnotations.initMocks(this);
    }

    @Test 
    public void shouldDoStuffWithListValues() {
        //...
        verify(service).doStuff(captor.capture()));
    }
}

The javax:javaee-api is intended for compiling, not running, including unit tests. If you need classes suitable for running against, run against a Java EE application server.

Also, the correct name is Java EE, not JEE.

Update Sep 2019: The only mocking framework supported (by default) by Spring Boot is Mockito. If you use Spring, the answer is quite obvious.

I'd say the competition is between JMockit and PowerMock, then Mockito.

I'd leave "plain" jMock and EasyMock because they use only proxy & CGLIB and do not use Java 5 instrumentation like the newer frameworks.

jMock also didn't have a stable release for over 4 years. jMock 2.6.0 required 2 years to go from RC1 to RC2, and then another 2 years before it actually got released.

Regarding Proxy & CGLIB vs instrumentation:

(EasyMock and jMock) are based on java.lang.reflect.Proxy, which requires an interface to be implemented. Additionally, they support the creation of mock objects for classes through CGLIB subclass generation. Because of that, said classes cannot be final and only overridable instance methods can be mocked. Most importantly, however, when using these tools the dependencies of code under test (that is, the objects of other classes on which a given class under test depends) must be controlled by the tests, so that mock instances can be passed to the clients of those dependencies. Therefore, dependencies can't simply be instantiated with the new operator in a client class for which we want to write unit tests.

Ultimately, the technical limitations of conventional mocking tools impose the following design restrictions on production code:

1. Each class which may need to be mocked in a test must either implement a separate interface or not be final.
2. The dependencies of each class to be tested must either be obtained through configurable instance creation methods (factories or a Service Locator), or be exposed for dependency injection. Otherwise, unit tests won't be able to pass mock implementations of dependencies to the unit under test.
3. Since only instance methods can be mocked, classes to be unit tested cannot call any static methods on their dependencies, nor instantiate them using any of the constructors.

The above is copied from http://jmockit.org/about.html . Further, it compares between itself (JMockit), PowerMock, and Mockito in several ways:

There are now other mocking tools for Java which also overcome the limitations of the conventional ones, between them PowerMock, jEasyTest, and MockInject. The one that comes closest to the feature set of JMockit is PowerMock, so I will briefly evaluate it here (besides, the other two are more limited and don't seem to be actively developed anymore).

JMockit vs PowerMock

• First of all, PowerMock does not provide a complete API for mocking, but instead works as an extension to another tool, which currently can be EasyMock or Mockito. This is obviously an advantage for existing users of those tools.
• JMockit, on the other hand, provides entirely new APIs, although its main API (Expectations) is similar to both EasyMock and jMock. While this creates a longer learning curve, it also allows JMockit to provide a simpler, more consistent, and easier to use API.
• Compared to the JMockit Expectations API, the PowerMock API is more "low-level", forcing users to figure out and specify which classes need to be prepared for testing (with the @PrepareForTest({ClassA.class, ...}) annotation) and requiring specific API calls to deal with various kinds of language constructs that may be present in the production code: static methods (mockStatic(ClassA.class)), constructors (suppress(constructor(ClassXyz.class))), constructor invocations (expectNew(AClass.class)), partial mocks (createPartialMock(ClassX.class, "methodToMock")), etc.
• With JMockit Expectations, all kinds of methods and constructors are mocked in a purely declarative way, with partial mocking specified through regular expressions in the @Mocked annotation or by simply "un-mocking" the members with no recorded expectations; that is, the developer simply declares some shared "mock fields" for the test class, or some "local mock fields" and/or "mock parameters" for individual test methods (and in this last case the @Mocked annotation often won't be needed).
• Some capabilities available in JMockit, such as support for mocking equals and hashCode, overridden methods, and others, are currently not supported in PowerMock. Also, there is no equivalent to JMockit's ability to capture instances and mock implementations of specified base types as the test executes, without the test code itself having any knowledge of the actual implementation classes.
• PowerMock uses custom class loaders (usually one per test class) in order to generate modified versions of the mocked classes. Such heavy use of custom class loaders can lead to conflicts with third-party libraries, hence the need to sometimes use the @PowerMockIgnore("package.to.be.ignored") annotation on test classes.
• The mechanism used by JMockit (runtime instrumentation through a "Java agent") is simpler and safer, although it does require passing a "-javaagent" parameter to the JVM when developing on JDK 1.5; on JDK 1.6+ (which can always be used for development, even if deploying on an older version) there is no such requirement, since JMockit can transparently load the Java agent on demand by using the Attach API.

Another recent mocking tool is Mockito. Although it does not attempt to overcome the limitations of older tools (jMock, EasyMock), it does introduce a new style of behavior testing with mocks. JMockit also supports this alternative style, through the Verifications API.

JMockit vs Mockito

• Mockito relies on explicit calls to its API in order to separate code between the record (when(...)) and verify (verify(...)) phases. This means that any invocation to a mock object in test code will also require a call to the mocking API. Additionally, this will often lead to repetitive when(...) and verify(mock)... calls.
• With JMockit, no similar calls exist. Sure, we have the new NonStrictExpectations() and new Verifications() constructor calls, but they occur only once per test (typically), and are completely separate from the invocations to mocked methods and constructors.
• The Mockito API contains several inconsistencies in the syntax used for invocations to mocked methods. In the record phase, we have calls like when(mock.mockedMethod(args))... while in the verify phase this same call will be written as verify(mock).mockedMethod(args). Notice that in the first case the invocation to mockedMethod is made directly on the mock object, while in the second case it is made on the object returned by verify(mock).
• JMockit has no such inconsistencies because invocations to mocked methods are always made directly on the mocked instances themselves. (With one exception only: to match invocations on the same mocked instance, an onInstance(mock) call is used, resulting in code like onInstance(mock).mockedMethod(args); most tests won't need to use this, though.)
• Just like other mocking tools which rely on method chaining/wrapping, Mockito also runs into inconsistent syntax when stubbing void methods. For example, you write when(mockedList.get(1)).thenThrow(new RuntimeException()); for a non-void method, and doThrow(new RuntimeException()).when(mockedList).clear(); for a void one. With JMockit, it's always the same syntax: mockedList.clear(); result = new RuntimeException();.
• Yet another inconsistency occurs in the use of Mockito spies: "mocks" that allow the real methods to be executed on the spied instance. For example, if spy refers to an empty List, then instead of writing when(spy.get(0)).thenReturn("foo") you will need to write doReturn("foo").when(spy).get(0). With JMockit, the dynamic mocking feature provides similar functionality to spies, but without this issue since real methods only get executed during the replay phase.
• In EasyMock and jMock, the first mocking APIs for Java, the focus was entirely on the recording of expected invocations of mocked methods, for mock objects that (by default) do not allow unexpected invocations. Those APIs also provide the recording of allowed invocations for mock objects that do allow unexpected invocations, but this was treated as a second-class feature. Additionally, with these tools there is no way to explicitly verify invocations to mocks after the code under test is exercised. All such verifications are performed implicitly and automatically.
• In Mockito (and also in Unitils Mock), the opposite viewpoint is taken. All invocations to mock objects that may happen during the test, whether recorded or not, are allowed, never expected. Verification is performed explicitly after the code under test is exercised, never automatically.
• Both approaches are too extreme, and consequently less than optimal. JMockit Expectations & Verifications is the only API that allows the developer to seamlessly choose the best combination of strict (expected by default) and non-strict (allowed by default) mock invocations for each test.
• To be more clear, the Mockito API has the following shortcoming. If you need to verify that an invocation to a non-void mocked method happened during the test, but the test requires a return value from that method that is different from the default for the return type, then the Mockito test will have duplicate code: a when(mock.someMethod()).thenReturn(xyz) call in the record phase, and a verify(mock).someMethod() in the verify phase. With JMockit, a strict expectation can always be recorded, which won't have to be explicitly verified. Alternatively, an invocation count constraint (times = 1) can be specified for any recorded non-strict expectation (with Mockito such constraints can only be specified in a verify(mock, constraint) call).
• Mockito has poor syntax for verifications in order, and for full verifications (that is, checking that all invocations to mock objects are explicitly verified). In the first case, an extra object needs to be created, and calls to verify made on it: InOrder inOrder = inOrder(mock1, mock2, ...). In the second case, calls like verifyNoMoreInteractions(mock) or verifyZeroInteractions(mock1, mock2) need to be made.
• With JMockit, you simply write new VerificationsInOrder() or new FullVerifications() instead of new Verifications() (or new FullVerificationsInOrder() to combine both requirements). No need to specify which mock objects are involved. No extra mocking API calls. And as a bonus, by calling unverifiedInvocations() inside an ordered verification block, you can perform order-related verifications that are simply impossible in Mockito.

Finally, the JMockit Testing Toolkit has a wider scope and more ambitious goals than other mocking toolkits, in order to provide a complete and sophisticated developer testing solution. A good API for mocking, even without artificial limitations, is not enough for productive creation of tests. An IDE-agnostic, easy to use, and well integrated Code Coverage tool is also essential, and that's what JMockit Coverage aims to provide. Another piece of the developer testing toolset which will become more useful as the test suite grows in size is the ability to incrementally rerun tests after a localized change to production code; this is also included in the Coverage tool.

(granted, the source may be biased, but well...)

I'd say go with JMockit. It's the easiest to use, flexible, and works for pretty much all cases even difficult ones and scenarios when you can't control the class to be tested (or you can't break it due to compatibility reasons etc.).

My experiences with JMockit have been very positive.

Technically speaking both "mocks" and "spies" are a special kind of "test doubles".

Mockito is unfortunately making the distinction weird.

A mock in mockito is a normal mock in other mocking frameworks (allows you to stub invocations; that is, return specific values out of method calls).

A spy in mockito is a partial mock in other mocking frameworks (part of the object will be mocked and part will use real method invocations).