android-12.0.0_r34/s

/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.dx.mockito.inline.extended;

import org.mockito.InOrder;
import org.mockito.MockSettings;
import org.mockito.Mockito;
import org.mockito.internal.matchers.LocalizedMatcher;
import org.mockito.internal.progress.ArgumentMatcherStorageImpl;
import org.mockito.stubbing.Answer;
import org.mockito.verification.VerificationMode;

import java.lang.reflect.Field;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.util.ArrayList;
import java.util.List;

import static com.android.dx.mockito.inline.InlineDexmakerMockMaker.onSpyInProgressInstance;
import static com.android.dx.mockito.inline.InlineStaticMockMaker.onMethodCallDuringVerification;
import static org.mockito.internal.progress.ThreadSafeMockingProgress.mockingProgress;

/**
 * Mockito extended with the ability to stub static methods.
 * <p>E.g.
 * <pre>
 *     private class C {
 *         static int staticMethod(String arg) {
 *             return 23;
 *         }
 *     }
 *
 *    {@literal @}Test
 *     public void test() {
 *         // static mocking
 *         MockitoSession session = mockitoSession().staticSpy(C.class).startMocking();
 *         try {
 *             doReturn(42).when(() -> {return C.staticMethod(eq("Arg"));});
 *             assertEquals(42, C.staticMethod("Arg"));
 *             verify(() -> C.staticMethod(eq("Arg"));
 *         } finally {
 *             session.finishMocking();
 *         }
 *     }
 * </pre>
 * <p>It is possible to use this class for instance mocking too. Hence you can use it as a full
 * replacement for {@link Mockito}.
 * <p>This is a prototype that is intended to eventually be upstreamed into mockito proper. Some
 * APIs might change. All such APIs are annotated with {@link UnstableApi}.
 */
@UnstableApi
public class ExtendedMockito extends Mockito {
    /**
     * Currently active {@link #mockitoSession() sessions}
     */
    private static ArrayList<StaticMockitoSession> sessions = new ArrayList<>();

    /**
     * Same as {@link Mockito#doAnswer(Answer)} but adds the ability to stub static method calls via
     * {@link StaticCapableStubber#when(MockedMethod)} and
     * {@link StaticCapableStubber#when(MockedVoidMethod)}.
     */
    public static StaticCapableStubber doAnswer(Answer answer) {
        return new StaticCapableStubber(Mockito.doAnswer(answer));
    }

    /**
     * Same as {@link Mockito#doCallRealMethod()} but adds the ability to stub static method calls
     * via {@link StaticCapableStubber#when(MockedMethod)} and
     * {@link StaticCapableStubber#when(MockedVoidMethod)}.
     */
    public static StaticCapableStubber doCallRealMethod() {
        return new StaticCapableStubber(Mockito.doCallRealMethod());
    }

    /**
     * Same as {@link Mockito#doNothing()} but adds the ability to stub static method calls via
     * {@link StaticCapableStubber#when(MockedMethod)} and
     * {@link StaticCapableStubber#when(MockedVoidMethod)}.
     */
    public static StaticCapableStubber doNothing() {
        return new StaticCapableStubber(Mockito.doNothing());
    }

    /**
     * Same as {@link Mockito#doReturn(Object)} but adds the ability to stub static method calls
     * via {@link StaticCapableStubber#when(MockedMethod)} and
     * {@link StaticCapableStubber#when(MockedVoidMethod)}.
     */
    public static StaticCapableStubber doReturn(Object toBeReturned) {
        return new StaticCapableStubber(Mockito.doReturn(toBeReturned));
    }

    /**
     * Same as {@link Mockito#doReturn(Object, Object...)} but adds the ability to stub static
     * method calls via {@link StaticCapableStubber#when(MockedMethod)} and
     * {@link StaticCapableStubber#when(MockedVoidMethod)}.
     */
    public static StaticCapableStubber doReturn(Object toBeReturned, Object... toBeReturnedNext) {
        return new StaticCapableStubber(Mockito.doReturn(toBeReturned, toBeReturnedNext));
    }

    /**
     * Same as {@link Mockito#doThrow(Class)} but adds the ability to stub static method calls via
     * {@link StaticCapableStubber#when(MockedMethod)} and
     * {@link StaticCapableStubber#when(MockedVoidMethod)}.
     */
    public static StaticCapableStubber doThrow(Class<? extends Throwable> toBeThrown) {
        return new StaticCapableStubber(Mockito.doThrow(toBeThrown));
    }

    /**
     * Same as {@link Mockito#doThrow(Class, Class...)} but adds the ability to stub static method
     * calls via {@link StaticCapableStubber#when(MockedMethod)} and
     * {@link StaticCapableStubber#when(MockedVoidMethod)}.
     */
    @SafeVarargs
    public static StaticCapableStubber doThrow(Class<? extends Throwable> toBeThrown,
                                               Class<? extends Throwable>... toBeThrownNext) {
        return new StaticCapableStubber(Mockito.doThrow(toBeThrown, toBeThrownNext));
    }

    /**
     * Same as {@link Mockito#doThrow(Throwable...)} but adds the ability to stub static method
     * calls via {@link StaticCapableStubber#when(MockedMethod)} and
     * {@link StaticCapableStubber#when(MockedVoidMethod)}.
     */
    public static StaticCapableStubber doThrow(Throwable... toBeThrown) {
        return new StaticCapableStubber(Mockito.doThrow(toBeThrown));
    }

    /**
     * Many methods of mockito take mock objects. To be able to call the same methods for static
     * mocking, this method gets a marker object that can be used instead.
     *
     * @param clazz The class object the marker should be crated for
     * @return A marker object. This should not be used directly. It can only be passed into other
     * ExtendedMockito methods.
     * @see #inOrder(Object...)
     * @see #clearInvocations(Object...)
     * @see #ignoreStubs(Object...)
     * @see #mockingDetails(Object)
     * @see #reset(Object[])
     * @see #verifyNoMoreInteractions(Object...)
     * @see #verifyZeroInteractions(Object...)
     */
    @UnstableApi
    @SuppressWarnings("unchecked")
    public static <T> T staticMockMarker(Class<T> clazz) {
        for (StaticMockitoSession session : sessions) {
            T marker = session.staticMockMarker(clazz);

            if (marker != null) {
                return marker;
            }
        }
        return null;
    }

    /**
     * Same as {@link #staticMockMarker(Class)} but for multiple classes at once.
     */
    @UnstableApi
    public static Object[] staticMockMarker(Class<?>... clazz) {
        Object[] markers = new Object[clazz.length];

        for (int i = 0; i < clazz.length; i++) {
            for (StaticMockitoSession session : sessions) {
                markers[i] = session.staticMockMarker(clazz[i]);

                if (markers[i] != null) {
                    break;
                }
            }

            if (markers[i] == null) {
                return null;
            }
        }

        return markers;
    }

    /**
     * Make an existing object a spy.
     *
     * <p>This does <u>not</u> clone the existing objects. If a method is stubbed on a spy
     * converted by this method all references to the already existing object will be affected by
     * the stubbing.
     *
     * @param toSpy The existing object to convert into a spy
     */
    @UnstableApi
    @SuppressWarnings("CheckReturnValue")
    public static void spyOn(Object toSpy) {
        if (onSpyInProgressInstance.get() != null) {
            throw new IllegalStateException("Cannot set up spying on an existing object while "
                    + "setting up spying for another existing object");
        }

        onSpyInProgressInstance.set(toSpy);
        try {
            spy(toSpy);
        } finally {
            onSpyInProgressInstance.remove();
        }
    }

    /**
     * To be used for static mocks/spies in place of {@link Mockito#verify(Object)} when calling
     * void methods.
     * <p>E.g.
     * <pre>
     *     private class C {
     *         void instanceMethod(String arg) {}
     *         static void staticMethod(String arg) {}
     *     }
     *
     *    {@literal @}Test
     *     public void test() {
     *         // instance mocking
     *         C mock = mock(C.class);
     *         mock.instanceMethod("Hello");
     *         verify(mock).mockedVoidInstanceMethod(eq("Hello"));
     *
     *         // static mocking
     *         MockitoSession session = mockitoSession().staticMock(C.class).startMocking();
     *         C.staticMethod("World");
     *         verify(() -> C.staticMethod(eq("World"));
     *         session.finishMocking();
     *     }
     * </pre>
     */
    public static void verify(MockedVoidMethod method) {
        verify(method, times(1));
    }

    /**
     * To be used for static mocks/spies in place of {@link Mockito#verify(Object)}.
     * <p>E.g. (please notice the 'return' in the lambda when verifying the static call)
     * <pre>
     *     private class C {
     *         int instanceMethod(String arg) {
     *             return 1;
     *         }
     *
     *         int static staticMethod(String arg) {
     *             return 2;
     *         }
     *     }
     *
     *    {@literal @}Test
     *     public void test() {
     *         // instance mocking
     *         C mock = mock(C.class);
     *         mock.instanceMethod("Hello");
     *         verify(mock).mockedVoidInstanceMethod(eq("Hello"));
     *
     *         // static mocking
     *         MockitoSession session = mockitoSession().staticMock(C.class).startMocking();
     *         C.staticMethod("World");
     *         verify(() -> <b>{return</b> C.staticMethod(eq("World")<b>;}</b>);
     *         session.finishMocking();
     *     }
     * </pre>
     */
    @UnstableApi
    public static void verify(MockedMethod method) {
        verify(method, times(1));
    }

    /**
     * To be used for static mocks/spies in place of
     * {@link Mockito#verify(Object, VerificationMode)} when calling void methods.
     *
     * @see #verify(MockedVoidMethod)
     */
    @UnstableApi
    public static void verify(MockedVoidMethod method, VerificationMode mode) {
        verifyInt(method, mode, null);
    }

    /**
     * To be used for static mocks/spies in place of
     * {@link Mockito#verify(Object, VerificationMode)}.
     *
     * @see #verify(MockedMethod)
     */
    @UnstableApi
    public static void verify(MockedMethod method, VerificationMode mode) {
        verify((MockedVoidMethod) method::get, mode);
    }

    /**
     * Same as {@link Mockito#inOrder(Object...)} but adds the ability to verify static method
     * calls via {@link StaticInOrder#verify(MockedMethod)},
     * {@link StaticInOrder#verify(MockedVoidMethod)},
     * {@link StaticInOrder#verify(MockedMethod, VerificationMode)}, and
     * {@link StaticInOrder#verify(MockedVoidMethod, VerificationMode)}.
     * <p>To verify static method calls, the result of {@link #staticMockMarker(Class)} has to be
     * passed to the {@code mocksAndMarkers} parameter. It is possible to mix static and instance
     * mocking.
     */
    @UnstableApi
    public static StaticInOrder inOrder(Object... mocksAndMarkers) {
        return new StaticInOrder(Mockito.inOrder(mocksAndMarkers));
    }

    /**
     * Same as {@link Mockito#mockitoSession()} but adds the ability to mock static methods
     * calls via {@link StaticMockitoSessionBuilder#mockStatic(Class)},
     * {@link StaticMockitoSessionBuilder#mockStatic(Class, Answer)}, and {@link
     * StaticMockitoSessionBuilder#mockStatic(Class, MockSettings)};
     * <p>All mocking spying will be removed once the session is finished.
     */
    public static StaticMockitoSessionBuilder mockitoSession() {
        return new StaticMockitoSessionBuilder(Mockito.mockitoSession());
    }

    /**
     * Common implementation of verification of static method calls.
     *
     * @param method          The static method call to be verified
     * @param mode            The verification mode
     * @param instanceInOrder If set, the {@link StaticInOrder} object
     */
    @SuppressWarnings({"CheckReturnValue", "MockitoUsage", "unchecked"})
    static void verifyInt(MockedVoidMethod method, VerificationMode mode, InOrder
            instanceInOrder) {
        if (onMethodCallDuringVerification.get() != null) {
            throw new IllegalStateException("Verification is already in progress on this "
                    + "thread.");
        }

        ArrayList<Method> verifications = new ArrayList<>();

        /* Set up callback that is triggered when the next static method is called on this thread.
         *
         * This is necessary as we don't know which class the method will be called on. Once the
         * call is intercepted this will
         *    1. Remove all matchers (e.g. eq(), any()) from the matcher stack
         *    2. Call verify on the marker for the class
         *    3. Add the markers back to the stack
         */
        onMethodCallDuringVerification.set((clazz, verifiedMethod) -> {
            // TODO: O holy reflection! Let's hope we can integrate this better.
            try {
                ArgumentMatcherStorageImpl argMatcherStorage = (ArgumentMatcherStorageImpl)
                        mockingProgress().getArgumentMatcherStorage();
                List<LocalizedMatcher> matchers;

                // Matcher are called before verify, hence remove the from the storage
                Method resetStackMethod
                        = argMatcherStorage.getClass().getDeclaredMethod("resetStack");
                resetStackMethod.setAccessible(true);

                matchers = (List<LocalizedMatcher>) resetStackMethod.invoke(argMatcherStorage);

                if (instanceInOrder == null) {
                    verify(staticMockMarker(clazz), mode);
                } else {
                    instanceInOrder.verify(staticMockMarker(clazz), mode);
                }

                // Add the matchers back after verify is called
                Field matcherStackField
                        = argMatcherStorage.getClass().getDeclaredField("matcherStack");
                matcherStackField.setAccessible(true);

                Method pushMethod = matcherStackField.getType().getDeclaredMethod("push",
                        Object.class);

                for (LocalizedMatcher matcher : matchers) {
                    pushMethod.invoke(matcherStackField.get(argMatcherStorage), matcher);
                }
            } catch (NoSuchFieldException | NoSuchMethodException | IllegalAccessException
                    | InvocationTargetException | ClassCastException e) {
                throw new Error("Reflection failed. Do you use a compatible version of "
                        + "mockito?", e);
            }

            verifications.add(verifiedMethod);
        });
        try {
            try {
                // Trigger the method call. This call will be intercepted and trigger the
                // onMethodCallDuringVerification callback.
                method.run();
            } catch (Throwable t) {
                if (t instanceof RuntimeException) {
                    throw (RuntimeException) t;
                } else if (t instanceof Error) {
                    throw (Error) t;
                }
                throw new RuntimeException(t);
            }

            if (verifications.isEmpty()) {
                // Make sure something was intercepted
                throw new IllegalArgumentException("Nothing was verified. Does the lambda call "
                        + "a static method on a 'static' mock/spy ?");
            } else if (verifications.size() > 1) {
                // A lambda might call several methods. In this case it is not clear what should
                // be verified. Hence throw an error.
                throw new IllegalArgumentException("Multiple intercepted calls on methods "
                        + verifications);
            }
        } finally {
            onMethodCallDuringVerification.remove();
        }
    }

    /**
     * Register a new session.
     *
     * @param session Session to register
     */
    static void addSession(StaticMockitoSession session) {
        sessions.add(session);
    }

    /**
     * Remove a finished session.
     *
     * @param session Session to remove
     */
    static void removeSession(StaticMockitoSession session) {
        sessions.remove(session);
    }
}