testable-mock/docs/en-us/doc/upgrade-guide.md

Upgrade Guide

Upgrade to 0.7

In version 0.7 mock related annotations and methods are renamed, in order to avoid naming conflict and misunderstanding.

1. The verify() used for check mock method invocation status has been renamed to verifyInvoked(), as there are several static methods also named verify() in com.sun package.
2. The annotation @MockMethod and @MockConstructor used for mark mock replacement method has been renamed to @MockInvoke and @MockNew, which is more suitable for its real usage.

The usage of those annotations and method has no change for below and above version 0.7.0, so during the upgrading only rename is required.

Upgrade to v0.6

In version 0.6，TestableMock provided a new quick complicated class construction capability. Meanwhile, it includes a modification that is incompatible with the 0.5 version: class PrivateAccessor have been moved from com.alibaba.testable.core.accessor package to com.alibaba.testable.core.tool package.

If you are using PrivateAccessor and having import statement like this:

import com.alibaba.testable.core.accessor.PrivateAccessor;

When upgrade TestableMock to 0.6 version, please replace it as：

import com.alibaba.testable.core.tool.PrivateAccessor;

Upgrade to v0.5

The 0.5 version solves the three historical problems left over before:

1. Mock method cannot call other non-static methods. The mock method in the new version no longer has any difference from the ordinary method, and can access any external method and member variable.
2. Mock method always acts on the entire test life cycle. From now on, the mock method supports restricting the effective scope to the test cases in the test class of which it belongs, so there is no need to worry about accidentally mocking cross-class test invocations.
3. The MOCK_CONTEXT needs manually cleaned up and only supports class-level parallel testing. Now each test case has an independent MOCK_CONTEXT variable, no need to clean up after used, and you can use unit test with any parallel level.

In order to better realize the reuse of Mock methods, the version 0.5 have made a clear boundary between the mock class and the test class in the new version. When upgrading from 0.4 to 0.5, the only change required is to wrap all mock methods in the test class with a public static class Mock {}.

For example, the original test class definition was as follows:

public class DemoMockTest {
    @MockMethod(targetClass = DemoMock.class)
    private String innerFunc(String text) {
        return "hello_" + text;
    }
        
    @Test
    void should_mock_member_method() throws Exception {
        assertEquals("hello_world", demoMock.outerFunc());
        verifyInvoked("innerFunc").with("world");
    }
}

After upgrading to the 0.5 version, move all mock methods (in this example, only the innerFunc method) to a static inner class named Mock, which is equivalent to adding two lines of code:

public class DemoMockTest {

    public static class Mock {   // Add this line
        @MockMethod(targetClass = DemoMock.class)
        private String innerFunc(String text) {
            return "hello_" + text;
        }
    }                            // Add this line
        
    @Test
    void should_mock_member_method() throws Exception {
        assertEquals("hello_world", demoMock.outerFunc());
        verifyInvoked("innerFunc").with("world");
    }
}

Finally, upgrade the TestableMock dependency in pom.xml or build.gradle file to the new version.