Module com.roscopeco.moxy.core
Package com.roscopeco.moxy

Class Moxy

  • public final class Moxy
extends Object

    Top-level static-imports for convenient Moxy use.

    This class, along with the Matchers class, are the main top-level classes most users will need to interact with when using Moxy. They are designed so you can simply import static and start mocking. For example:

    
 import static com.roscopeco.moxy.Moxy.*;
 import static com.roscopeco.moxy.matchers.Matchers.*;

 // ... later ...

 SomeClass mock = mock(SomeClass.class);

 when(() -> mock.someMethod(any(), eq("something"))).thenReturn("whatever");

 // ... mock usage ...

 assertMock(() -> mock.someMethod("expected", "something").wasCalledTwice();
 assertMock(() -> mock.someMethod("badfood", "something").wasNotCalled();

    See README.md for more detailed usage of the library.

    Since:
    1.0
    Author:
    Ross Bamford <roscopeco AT gmail DOT com>
    See Also:
    Matchers

    • Method Detail

      • setMoxyEngine

        public static void setMoxyEngine​(MoxyEngine moxyEngine)

        Set the MoxyEngine that will be used by all future calls to methods in this class.

        Note: Calling this method after the current (or default) engine has been used may cause problems. If you are changing the engine, you should change it before interacting with the library in any other way (especially creating mocks).

        Parameters:
        moxyEngine - The MoxyEngine implementation to use.
        Since:
        1.0

      • getMoxyEngine

        public static MoxyEngine getMoxyEngine()
        Get the current MoxyEngine in use by this class, or create and return a default engine if none has been set.
        Returns:
        The MoxyEngine currently in use.
        Since:
        1.0

      • setMoxyClassMockEngine

        public static void setMoxyClassMockEngine​(MoxyClassMockEngine moxyClassMockEngine)

        Set the MoxyClassMockEngine that will be used by all future calls to methods in this class.

        Note: Calling this method after the current (or default) engine has been used may cause problems. If you are changing the engine, you should change it before interacting with the library in any other way (especially creating mocks).

        Parameters:
        moxyClassMockEngine - The MoxyClassMockEngine implementation to use.
        Since:
        1.0

      • mock

        public static <T> T mock​(Class<T> clz)

        Create a mock instance of the given class using the currently-set (or default) MoxyEngine.

        The mock will be created in the engine's default ClassLoader. For the default engine, this is the same ClassLoader that loaded the Moxy framework.

        Note: This method will not call a constructor on the generated instance, which may cause problems if you plan to use #MoxyStubber.thenCallRealMethod() with this mock.

        If that is the case, see constructSpy(Class, Object...).

        Type Parameters:
        T - The type being mocked.
        Parameters:
        clz - The Class to mock.
        Returns:
        A new mock instance.
        Since:
        1.0
        See Also:
        mock(Class, PrintStream), mock(MoxyEngine, Class, PrintStream)

      • mock

        public static <T> T mock​(Class<T> clz,
                         PrintStream trace)

        Create a mock instance of the given class using the currently-set (or default) MoxyEngine.

        The mock will be created in the engine's default ClassLoader. For the default engine, this is the same ClassLoader that loaded the Moxy framework.

        During creation of the mock, this method will also dump the generated bytecode, in a debugging format, to the supplied PrintStream.

        Note: This method will not call a constructor on the generated instance, which may cause problems if you plan to use #MoxyStubber.thenCallRealMethod() with this mock.

        If that is the case, see constructSpy(Class, PrintStream, Object...).

        Type Parameters:
        T - The type being mocked.
        Parameters:
        clz - The Class to mock.
        trace - If non-null, the resulting class will be dumped (with a TraceClassVisitor) to the given stream.
        Returns:
        A new mock instance.
        Since:
        1.0
        See Also:
        mock(Class), mock(MoxyEngine, Class, PrintStream)

      • mock

        public static <T> T mock​(MoxyEngine engine,
                         Class<T> clz,
                         PrintStream trace)

        Create a mock instance of the given class using the specified MoxyEngine.

        The mock will be created in the engine's default ClassLoader. For the default engine, this is the same ClassLoader that loaded the Moxy framework.

        During creation of the mock, this method will also dump the generated bytecode, in a debugging format, to the supplied PrintStream.

        Note: This method will not call a constructor on the generated instance, which may cause problems if you plan to use #MoxyStubber.thenCallRealMethod() with this mock.

        If that is the case, see constructSpy(MoxyEngine, Class, PrintStream, Object...).

        Type Parameters:
        T - The type being mocked.
        Parameters:
        engine - The MoxyEngine implementation to use.
        clz - The Class to mock.
        trace - If non-null, the resulting class will be dumped (with a TraceClassVisitor) to the given stream.
        Returns:
        A new mock instance.
        Since:
        1.0
        See Also:
        mock(Class), mock(Class, PrintStream)

      • constructMock

        public static <T> T constructMock​(Class<T> clz,
                                  PrintStream trace,
                                  Object... args)

        Create a mock instance of the given class using the default MoxyEngine using a constructor call. This method is intended for use when one or more methods will be spied (with MoxyStubber.thenCallRealMethod().

        The mock will be created in the engine's default ClassLoader. For the default engine, this is the same ClassLoader that loaded the Moxy framework.

        During creation of the mock, this method will also dump the generated bytecode, in a debugging format, to the supplied PrintStream (if non-null).

        This method uses a best-fit algorithm to determine which constructor to call based on the supplied arguments. Primitive types will be boxed/unboxed automatically.

        Type Parameters:
        T - The type being mocked.
        Parameters:
        clz - The Class to spy.
        trace - If non-null, the resulting class will be dumped (with a TraceClassVisitor) to the given stream.
        args - Constructor arguments for the mock.
        Returns:
        A new mock instance.
        Since:
        1.0
        See Also:
        mock(Class), constructMock(Class, Object...), constructMock(MoxyEngine, Class, PrintStream, Object...), MoxyStubber.thenCallRealMethod()

      • constructMock

        public static <T> T constructMock​(MoxyEngine engine,
                                  Class<T> clz,
                                  PrintStream trace,
                                  Object... args)

        Create a mock instance of the given class using the supplied MoxyEngine using a constructor call. This method is intended for use when one or more methods will be spied (with MoxyStubber.thenCallRealMethod().

        The mock will be created in the engine's default ClassLoader. For the default engine, this is the same ClassLoader that loaded the Moxy framework.

        During creation of the mock, this method will also dump the generated bytecode, in a debugging format, to the supplied PrintStream (if non-null).

        This method uses a best-fit algorithm to determine which constructor to call based on the supplied arguments. Primitive types will be boxed/unboxed automatically.

        Type Parameters:
        T - The type being mocked.
        Parameters:
        engine - The MoxyEngine implementation to use.
        clz - The Class to mock.
        trace - If non-null, the resulting class will be dumped (with a TraceClassVisitor) to the given stream.
        args - Constructor arguments for the mock.
        Returns:
        A new mock instance.
        Since:
        1.0
        See Also:
        mock(Class), constructMock(Class, Object...), constructMock(Class, PrintStream, Object...), MoxyStubber.thenCallRealMethod()

      • spy

        public static <T> T spy​(T object)

        Convert the given object into a spy.

        This method can be used to convert any Object into a spy. It behaves differently depending on whether the passed object is a mock, or a standard object:

        It is, in the latter case, important to note that this may not be exactly the behaviour you expect. You should always convert to a spy before applying any additional stubbing.

        Note that this will reset all prior stubbing on the given mock.

        Type Parameters:
        T - The type of the mock.
        Parameters:
        object - The object to be spied-upon.
        Returns:
        The mock, converted to a spy.
        Since:
        1.0
        See Also:
        spy(Class), spy(Class, PrintStream), spy(MoxyEngine, Class, PrintStream)

      • spy

        public static <T> T spy​(Class<T> clz,
                        PrintStream trace)

        Create a spy instance of the given class using the default MoxyEngine.

        The spy will be created in the engine's default ClassLoader. For the default engine, this is the same ClassLoader that loaded the Moxy framework.

        During creation of the spy, this method will also dump the generated bytecode, in a debugging format, to the supplied PrintStream (if non-null).

        Note: This method will not call a constructor on the generated instance, which may be more troublesome for spies than it is for mocks (as the real methods being called may rely on some state initialized by the constructor).

        If you require a constructor be called, see constructSpy(Class, PrintStream, Object...).

        Type Parameters:
        T - The type being spied.
        Parameters:
        clz - The Class to spy.
        trace - If non-null, the resulting class will be dumped (with a TraceClassVisitor) to the given stream.
        Returns:
        A new spy instance.
        Since:
        1.0
        See Also:
        spy(Class), spy(MoxyEngine, Class, PrintStream), spy(Object), constructSpy(Class, PrintStream, Object...), mock(Class, PrintStream), MoxyStubber.thenCallRealMethod()

      • constructSpy

        public static <T> T constructSpy​(Class<T> clz,
                                 PrintStream trace,
                                 Object... args)

        Create a spy instance of the given class using the default MoxyEngine using a constructor call.

        The spy will be created in the engine's default ClassLoader. For the default engine, this is the same ClassLoader that loaded the Moxy framework.

        During creation of the spy, this method will also dump the generated bytecode, in a debugging format, to the supplied PrintStream (if non-null).

        This method uses a best-fit algorithm to determine which constructor to call based on the supplied arguments. Primitive types will be boxed/unboxed automatically.

        Type Parameters:
        T - The type being spied.
        Parameters:
        clz - The Class to spy.
        trace - If non-null, the resulting class will be dumped (with a TraceClassVisitor) to the given stream.
        args - Constructor arguments for the spy.
        Returns:
        A new spy instance.
        Since:
        1.0
        See Also:
        spy(Class, PrintStream), spy(Object), constructSpy(Class, Object...), constructSpy(MoxyEngine, Class, PrintStream, Object...), mock(Class, PrintStream), MoxyStubber.thenCallRealMethod()

      • constructSpy

        public static <T> T constructSpy​(MoxyEngine engine,
                                 Class<T> clz,
                                 PrintStream trace,
                                 Object... args)

        Create a spy instance of the given class using the supplied MoxyEngine using a constructor call.

        The spy will be created in the engine's default ClassLoader. For the default engine, this is the same ClassLoader that loaded the Moxy framework.

        During creation of the spy, this method will also dump the generated bytecode, in a debugging format, to the supplied PrintStream (if non-null).

        This method uses a best-fit algorithm to determine which constructor to call based on the supplied arguments. Primitive types will be boxed/unboxed automatically.

        Type Parameters:
        T - The type being spied.
        Parameters:
        engine - The MoxyEngine implementation to use.
        clz - The Class to spy.
        trace - If non-null, the resulting class will be dumped (with a TraceClassVisitor) to the given stream.
        args - Constructor arguments for the spy.
        Returns:
        A new spy instance.
        Since:
        1.0
        See Also:
        spy(MoxyEngine, Class, PrintStream), spy(Object), constructSpy(Class, Object...), constructSpy(Class, PrintStream, Object...), mock(MoxyEngine, Class, PrintStream), MoxyStubber.thenCallRealMethod()

      • isMock

        public static boolean isMock​(Class<?> clz)

        Determines whether the supplied class is a mock class.

        How this determination is made is engine-dependent, but may rely on the fact that the class has the (mandatory) MoxyMock annotation.

        Parameters:
        clz - The class to query.
        Returns:
        true if the class is a mock, false otherwise.
        Since:
        1.0

      • isMock

        public static boolean isMock​(Object obj)

        Determines whether the supplied object is a mock instance.

        How this determination is made is engine-dependent, but may rely on the fact that the class has the (mandatory) MoxyMock annotation.

        Parameters:
        obj - The object to query.
        Returns:
        true if the object is a mock, false otherwise.
        Since:
        1.0

      • isMock

        public static boolean isMock​(MoxyEngine engine,
                             Class<?> clz)

        Determines whether the supplied class is a mock class in the context of the supplied MoxyEngine.

        How this determination is made is engine-dependent.

        Parameters:
        engine - The MoxyEngine implementation to use.
        clz - The class to query.
        Returns:
        true if the class is a mock, false otherwise.
        Since:
        1.0

      • isMock

        public static boolean isMock​(MoxyEngine engine,
                             Object obj)

        Determines whether the supplied class is a mock class in the context of the supplied MoxyEngine.

        How this determination is made is engine-dependent.

        Parameters:
        engine - The MoxyEngine implementation to use.
        obj - The object to query.
        Returns:
        true if the object is a mock, false otherwise.
        Since:
        1.0

      • when

        public static <T> MoxyStubber<T> when​(InvocationSupplier<T> invocation)

        Starts stubbing of the mock invocation in the supplied lambda expression using the currently-set (or default) MoxyEngine.

        The invocation of the mock is used to determine which method and argument combination is to be stubbed and is not counted toward mock invocation, return or throw counters.

        Example usage:

        
 Moxy.when(() -> mock.someMethod("one", "two")).thenReturn("three");

        The arguments passed to the mock within the lambda may be either immediate arguments, other mocks, or argument matchers (see Matchers).

        This method begins a new chain of stubbing for the given invocation - Any prior stubbing applied is discarded, to be replaced by the stubbing applied on the returned MoxyStubber.

        See MoxyStubber for details on the stubbing methods available.

        Type Parameters:
        T - The type being stubbed (return type of the mock method).
        Parameters:
        invocation - A lambda that will invoke the method to be stubbed.
        Returns:
        A MoxyStubber that will stub the given method.
        Since:
        1.0
        See Also:
        when(InvocationRunnable), when(MoxyEngine, InvocationSupplier), MoxyStubber

      • when

        public static MoxyVoidStubber when​(InvocationRunnable invocation)

        Starts stubbing of the mock invocation in the supplied lambda expression using the currently-set (or default) MoxyEngine.

        The Java compiler will automatically select this overload of the when method when the method to be stubbed is void.

        The invocation of the mock is used to determine which method and argument combination is to be stubbed and is not counted toward mock invocation, return or throw counters.

        Example usage:

        
 Moxy.when(() -> mock.voidMethod("one", "two")).thenThrow("three");

        The arguments passed to the mock within the lambda may be either immediate arguments, other mocks, or argument matchers (see Matchers).

        This method begins a new chain of stubbing for the given invocation - Any prior stubbing applied is discarded, to be replaced by the stubbing applied on the returned MoxyVoidStubber.

        See MoxyStubber for details on the stubbing methods available.

        Parameters:
        invocation - A lambda that will invoke the method to be stubbed.
        Returns:
        A MoxyStubber that will stub the given method.
        Since:
        1.0
        See Also:
        when(InvocationSupplier), when(MoxyEngine, InvocationRunnable), MoxyStubber

      • when

        public static <T> MoxyStubber<T> when​(MoxyEngine engine,
                                      InvocationSupplier<T> invocation)

        Starts stubbing of the mock invocation in the supplied lambda expression using the specified MoxyEngine.

        The invocation of the mock is used to determine which method and argument combination is to be stubbed and is not counted toward mock invocation, return or throw counters.

        Example usage:

        
 Moxy.when(engine, () -> mock.someMethod("one", "two")).thenReturn("three");

        The arguments passed to the mock within the lambda may be either immediate arguments, other mocks, or argument matchers (see Matchers).

        See MoxyStubber for details on the stubbing methods available.

        Type Parameters:
        T - The type being stubbed (return type of the mocked method).
        Parameters:
        engine - The MoxyEngine implementation to use.
        invocation - A lambda that will invoke the method to be stubbed.
        Returns:
        A MoxyStubber that will stub the given method.
        Since:
        1.0
        See Also:
        when(MoxyEngine, InvocationRunnable), when(InvocationSupplier), MoxyStubber

      • when

        public static MoxyVoidStubber when​(MoxyEngine engine,
                                   InvocationRunnable invocation)

        Starts stubbing of the mock invocation in the supplied lambda expression using the specified MoxyEngine.

        The Java compiler will automatically select this overload of the when method when the method to be stubbed is void.

        The invocation of the mock is used to determine which method and argument combination is to be stubbed and is not counted toward mock invocation, return or throw counters.

        Example usage:

        
 Moxy.when(() -> mock.voidMethod(engine, "one", "two")).thenThrow("three");

        The arguments passed to the mock within the lambda may be either immediate arguments, other mocks, or argument matchers (see Matchers).

        See MoxyStubber for details on the stubbing methods available.

        Parameters:
        engine - The MoxyEngine implementation to use.
        invocation - A lambda that will invoke the method to be stubbed.
        Returns:
        A MoxyStubber that will stub the given method.
        Since:
        1.0
        See Also:
        when(InvocationSupplier), when(MoxyEngine, InvocationRunnable), MoxyStubber

      • assertMock

        public static MoxyVerifier assertMock​(InvocationRunnable invocation)

        Starts verification of the mock invocation in the supplied lambda expression using the currently-set (or default) MoxyEngine.

        The invocation of the mock is used to determine which method and argument combination is to be verified and is not counted toward mock invocation, return or throw counters.

        Example usage:

        
 Moxy.assertMock(() -> mock.voidMethod(engine, "one", "two")).wasCalled();

        The arguments passed to the mock within the lambda may be either immediate arguments, other mocks, or argument matchers (see Matchers).

        See MoxyStubber for details on the stubbing methods available.

        Parameters:
        invocation - A lambda that will invoke the method to be stubbed.
        Returns:
        A MoxyVerifier that will verify the given method.
        Since:
        1.0
        See Also:
        assertMock(MoxyEngine, InvocationRunnable), MoxyVerifier

      • assertMock

        public static MoxyVerifier assertMock​(MoxyEngine engine,
                                      InvocationRunnable invocation)

        Starts verification of the mock invocation in the supplied lambda expression using the specified MoxyEngine.

        The invocation of the mock is used to determine which method and argument combination is to be verified and is not counted toward mock invocation, return or throw counters.

        Example usage:

        
 Moxy.assertMock(() -> mock.voidMethod(engine, "one", "two")).wasCalled();

        The arguments passed to the mock within the lambda may be either immediate arguments, other mocks, or argument matchers (see Matchers).

        See MoxyStubber for details on the stubbing methods available.

        Parameters:
        engine - The MoxyEngine implementation to use.
        invocation - A lambda that will invoke the method to be stubbed.
        Returns:
        A MoxyVerifier that will verify the given method.
        Since:
        1.0
        See Also:
        assertMock(InvocationRunnable), MoxyVerifier

      • assertMocks

        public static MoxyMultiVerifier assertMocks​(InvocationRunnable invocation)

        Starts verification of one or more mock invocations at the same time. This allows multiple invocations to be checked together to ensure ordering, for example.

        This method uses the current default MoxyEngine.

        The invocation of the mock is used to determine which method and argument combination is to be verified and is not counted toward mock invocation, return or throw counters.

        Example usage:

        
 engine.assertMocks(() -> {
   mock.voidMethod(engine, "one", "two")).wasCalled();
   mock.anotherMethod();

   anotherMock.someMethod("five");

   mock.finalMethod("Bees");
 })
     .wereAllCalledOnce()
     .inThatOrder();

        The arguments passed to the mocks within the lambda may be either immediate arguments, other mocks, or argument matchers (see Matchers).

        See MoxyMultiVerifier for details on the verifying methods available.

        Parameters:
        invocation - A lambda that will invoke the methods to be verified.
        Returns:
        A MoxyMultiVerifier that will verify the invocations.
        Since:
        1.0
        See Also:
        assertMock(InvocationRunnable)

      • assertMocks

        public static MoxyMultiVerifier assertMocks​(MoxyEngine engine,
                                            InvocationRunnable invocation)

        Starts verification of one or more mock invocations at the same time. This allows multiple invocations to be checked together to ensure ordering, for example.

        This method uses the supplied MoxyEngine.

        The invocation of the mock is used to determine which method and argument combination is to be verified and is not counted toward mock invocation, return or throw counters.

        Example usage:

        
 engine.assertMocks(() -> {
   mock.voidMethod(engine, "one", "two")).wasCalled();
   mock.anotherMethod();

   anotherMock.someMethod("five");

   mock.finalMethod("Bees");
 })
     .wereAllCalledOnce()
     .inThatOrder();

        The arguments passed to the mocks within the lambda may be either immediate arguments, other mocks, or argument matchers (see Matchers).

        See MoxyMultiVerifier for details on the verifying methods available.

        Parameters:
        engine - The MoxyEngine to use.
        invocation - A lambda that will invoke the methods to be verified.
        Returns:
        A MoxyMultiVerifier that will verify the invocations.
        Since:
        1.0
        See Also:
        assertMock(InvocationRunnable)