diff --git a/docs/en-us/README.md b/docs/en-us/README.md new file mode 100644 index 0000000..9c430c4 --- /dev/null +++ b/docs/en-us/README.md @@ -0,0 +1,13 @@ +TestableMock Introduction +--- + +The Mock method in unit testing is usually to bypass method calls that rely on external resources or irrelevant functions, so that the focus of the test can be keep on the code logic that needs to be verified and guaranteed. + +When defining the Mock method, the developer really cares about only one thing: "This call should be replaced with the fake **mock method** during testing". + +However, when the current mainstream Mock framework implements the Mock function, developers have to worry about too many things: how the Mock framework is initialized, whether it is compatible with the unit testing framework used, whether the method to be mocked is private or static, whether the Mock object is created by `new` operator or injected, how to send the mock object back to the class under test... These non-critical additional tasks greatly distract the fun of using the mock tool. + +Therefore, we developed `TestableMock`, **a maverick and lightweight mock tool**. + + +!#[mock](https://testable-code.oss-cn-beijing.aliyuncs.com/en-us/mock-simpson.png) diff --git a/docs/en-us/doc/comparation.md b/docs/en-us/doc/comparation.md new file mode 100644 index 0000000..4750c7c --- /dev/null +++ b/docs/en-us/doc/comparation.md @@ -0,0 +1,26 @@ +Mock Tools Comparison +--- + +Besides `TestableMock`, there are also several other community Mock tools, such as `Mockito`, `Spock`, `PowerMock` and `JMockit`. Comparison as follows: + +| Tool | Mechanism | Minimal Mock Unit | Limitation of method be mocked | Ease of use | IDE support | +| ---- | ---- | ---- | ---- | ---- | ---- | +| Mockito | Dynamic proxy | Class | Except private/static method and constructor | **Easy** | **Very well** | +| Spock | Dynamic proxy | Class | Except private/static method and constructor | Complicate | Just so so | +| PowerMock | Custom class loader | Class | **No limitation, any method works** | Complicate | **Good** | +| JMockit | Runtime bytecode modification | Class | Except constructor (i.e. new operator) | Complicate | Just so so | +| TestableMock | Runtime bytecode modification | Method | **No limitation, any method works** | **Very easy** | Just so so | + +`Mockito` is Java's the most classical mock tool, good stability and easy to use, with both IntelliJ and Eclipse have plugin. The shortcoming part is that its mock functionality is sometimes not enough and have to be used in conjunction with other mock tools when necessary. + +`Spock` is a highly readable unit testing framework with built-in mock support, it has a good overall consistency. Since it is also based on dynamic proxy implementation, its shortcomings are similar to `Mockito`. + +`PowerMock` is a very powerful mock tool. Its basic syntax is compatible with `Mockito`, and extends many missing features of `Mockito`, including support for mocking of private, static and construction methods. However, due to the use of custom class loader, the test coverage of Jacoco will drop to zero in the default `on-the-fly` mode. + +`JMockit` is a mock tool whose functionality and convenience are between `Mockito` and `PowerMock`, and it makes up for their respective shortcomings. The project tried to launch a rewritten version of JMockit2 in 2017 but failed to complete, and is currently in an inactive maintenance state. + +The functionality of `TestabledMock` is basically the same as that of `PowerMock`, and it is extremely easy to use. You can complete most tasks only by mastering the annotations of `@MockMethod`. + +The main disadvantage of the current `TestableMock` is that the IDE cannot promptly prompt whether the method parameters are matched correctly when writing the mock method. If the mocking effect does not meet expectation, it has to be verified during runtime through the method provided in the [self-help troubleshooting](en-us/doc/troubleshooting.md) document. This feature needs to be provided by extending IDE plugins in the future. + +In addition, because `TestableMock` uses the mock mechanism based on a single method in a unique way, it decouples the mock method definition from the unit test cases. Thus, the mock methods are by default reusable, and the unit test cases become cleaner and purer. On the other hand, the mock methods become fragmented, and life cycle management is relatively difficult. Therefore, it may take some time for developers get used to it. diff --git a/docs/en-us/doc/feedback.md b/docs/en-us/doc/feedback.md new file mode 100644 index 0000000..1567c83 --- /dev/null +++ b/docs/en-us/doc/feedback.md @@ -0,0 +1,8 @@ +Feedback Channel +--- + +If you have any questions or suggestions during the use of `TestableMock`, please go ahead raise them in [Project Issue](https://github.com/alibaba/testable-mock/issues) and we will usually reply within 24 hours. + +Please describe the situation in detail. If you think the problem may be related to the potential BUG of `TestableMock`, please try to provide reproducible source code or examples for shorten the troubleshooting time. + +`TestableMock`, with no more untestable code in Java : ) diff --git a/docs/en-us/doc/frequently-asked-questions.md b/docs/en-us/doc/frequently-asked-questions.md new file mode 100644 index 0000000..970550d --- /dev/null +++ b/docs/en-us/doc/frequently-asked-questions.md @@ -0,0 +1,48 @@ +Frequently Asked Questions +--- + +#### 1. How to mock the fields initialized by `@Autowired` in the class under test? + +Create the class under test object directly, and then use the ability of `TestableMock` to access private members to directly assign values to these fields. + +#### 2. Can `TestableMock` be used with other Mock tools? + +`TestableMock` can be safely used together with other Mock tools based on dynamic proxy mechanism, such as `Mockito`, `EasyMock`, `Spock`, etc., all belong to this category. + +For Mock tools that modify the class loader or the bytecode of the class under test, such as `PowerMock` and `JMockit`, there is no yet case to prove that they will conflict with `TestableMock`, but in principle, there may be a risk of incompatibility between the two, Please use with caution. + +#### 3. How to implement the mock method when the parent class variable points to the child class object? + +In the code, there are often cases of using interface variables or parent class variables to point to an instance of subclasses and calling methods provided by the parent class or subclass. + +At this time, follow a principle that the type of the first parameter of the mock method is always the same as the type of the variable that initiated the call. + +Therefore, regardless of whether the actually called method comes from the parent class or the subclass, and whether the subclass overrides the method. If the calling variable is of the parent type (or interface type), the first parameter type of the Mock method should use the corresponding parent type (or interface) type. + +See the use case of the `DemoInheritTest` test class in the Java and Kotlin examples. + +#### 4. How to mock generic methods (template methods)? + +Same as the Mock method of the ordinary method, just use the same generic parameters directly on the Mock method. + +See the use case of the `DemoTemplateTest` test class in the Java and Kotlin examples. + +> Because JVM has a generic erasure mechanism, you can also directly use the `Object` type to replace generic parameters for Java projects, see the commented out "Second solution" example in the Java version of the `DemoTemplateTest` test class. + +#### 5. Why mocking methods in the `String` class in the Kotlin project does not work? + +The `String` type in Kotlin language is actually `kotlin.String` instead of `java.lang.String`. However, when this type is built from bytecode, it will be replaced with Java's `java.lang.String` class, so no matter if the Mock target is written as `kotlin.String` or `java.lang.String`, it cannot match the original called method. + +In actual scenarios, there are very few scenarios where methods in the `String` class need to be mocked, so `TestableMock` has not dealt with this situation specifically. + +#### 6. When trigger a single test case in IntelliJ IDE, why class with `@EnablePrivateAccess` annotation report still private member access errors? + +The default compiler provided by IntelliJ handle the annotation processor of the `JSR-269` specification in an incompatible way of maven. You can turn on the "Delegate IDE build/run actions to maven" option in "Build Tools > Maven > Runner" of IntelliJ system configuration: + +![delegate-ide-build-to-maven](https://testable-code.oss-cn-beijing.aliyuncs.com/delegate-ide-build-to-maven.png) + +#### 7. Can `TestableMock` be used for testing Android projects? + +It can be used in combination with [Roboelectric](https://github.com/robolectric/robolectric) testing framework. + +The `Dalvik` and `ART` virtual machines of the Android system use a bytecode system different from the standard JVM, which will affect the normal functionality of `TestableMock`. The `Roboelectric` framework can run Android unit tests on a standard JVM virtual machine, which is much faster than running unit tests through the Android virtual machine. Recently, most Android App unit tests are written with the `Roboelectric` framework. diff --git a/docs/en-us/doc/invoke-matcher.md b/docs/en-us/doc/invoke-matcher.md new file mode 100644 index 0000000..26027d5 --- /dev/null +++ b/docs/en-us/doc/invoke-matcher.md @@ -0,0 +1,75 @@ +Verify Mock Invocation +--- + +In the test, in addition to replacing **methods contain external dependencies** with mocks, it is often necessary to verify whether the actual parameters of mock invocation are in accordance with expectations. + +The **verifiers** and **matchers** are provided in `TestableMock` to achieve this function. for example: + +```java +@Test +public test_case() { + int res = insToTest.methodToTest(); + verify("mockMethod").with(123, "abc"); +} +``` + +This use case will check whether the mock method named `mockMethod` has been called when the method under test `methodToTest()` is executed, and whether the parameter values received during the call are `123` and `"abc"` (Assuming that the `mockMethod` method has two parameters). + +In addition to this simple verification, `TestableMock` currently supports a variety of **validators**, as well as **matchers** that can fuzzy match parameter characteristics. + +The `DemoMatcherTest` test classes in the sample projects `java-demo` and `kotlin-demo` show the usage of these validators and matchers in detail. + +## Basic validator + +- `with(Object...args)` → verify whether the method has been called by the specified parameters +- `withInOrder(Object... args)` → verify the specified method is called with specified parameters according to the actual calling order +- `withTimes(int expectedCount)` → verify whether the method has been called the specified number of times, ignoring the check of the calling parameters +- `without(Object...args)` → verification method has never been called with specified parameters +- `times(int count)` → use after the `with()` or `withInOrder()` method to verify that the method has been called the specified number of times with the same conditions + +## Basic matcher + +- `any()` → matches any value, including `null` +- `any(Class clazz)` → match any value of the specified type or subtype +- `anyTypeOf(Class... classes)` → match any type of value in the list +- `anyString()` → matches any string +- `anyNumber()` → matches any number (integer, long, float, double, etc) +- `anyBoolean()` → matches any Boolean value +- `anyByte()` → match any single byte type value +- `anyChar()` → matches any single character type value +- `anyInt()` → matches any integer value +- `anyLong()` → matches any value of long integer type +- `anyFloat()` → match any value of float type +- `anyDouble()` → match any double-precision float number type value +- `anyShort()` → matches any value of short integer type +- `anyArray()` → matches any array +- `anyArrayOf(Class clazz)` → matches any array of the specified type +- `anyList()` → matches any list +- `anyListOf(Class clazz)` → matches any list of the specified type +- `anySet()` → matches any set +- `anySetOf(Class clazz)` → matches any set of the specified type +- `anyMap()` → match any map +- `anyMapOf(Class keyClass, Class valueClass)` → match any map of the specified type +- `anyCollection()` → match any container +- `anyCollectionOf(Class clazz)` → matches any specified type of container +- `anyIterable()` → matches any iterator +- `anyIterableOf(Class clazz)` → matches any iterator of the specified type +- `eq(Object obj)` → match objects equal to the specified value +- `refEq(Object obj)` → match the specified object (not equal to the value, but the same object) + +## Null value matcher + +- `isNull()` → match `null` +- `notNull()` → matches any value except `null` +- `nullable(Class clazz)` → matches any value of `null` or specified type + +## String matcher + +- `contains(String substring)` → match a string containing a specific substring +- `matches(String regex)` → match strings that match the specified regular expression +- `endsWith(String suffix)` → match the string ending with the specified substring +- `startsWith(String prefix)` → match the string starting with the specified substring + +## Universal matcher + +- `any(MatchFunction matcher)` → match the value that matches the specified expression diff --git a/docs/en-us/doc/private-accessor.md b/docs/en-us/doc/private-accessor.md new file mode 100644 index 0000000..1821ddc --- /dev/null +++ b/docs/en-us/doc/private-accessor.md @@ -0,0 +1,34 @@ +Private Accessor +--- + +Nowadays, the debate about whether private methods should be unit tested is gradually disappearing, and the common practice of developers has given factual answers. Indirect testing of private methods through public methods is difficult in many cases. Developers are more willing to modify method visibility to make original private methods testable in test cases. + +In addition, before unit testing begin, it is often necessary to initialize specific member fields of the object under test, but sometimes it could be impossible to easily assign values to these private fields. So, is it possible let the code in the unit test case directly access the private methods and member fields of the class under test without breaking the encapsulation of the tested type? `TestableMock` provides two simple solutions. + +### Solution 1: Use `@EnablePrivateAccess` annotation + +Just add `@EnablePrivateAccess` annotation to the test class, then you have got the following enhancements in the test case: + +- Invoke private methods (including static methods) of the class under test +- Read private fields (including static fields) of the class under test +- Modify private fields (including static fields) of the class under test +- Modify the constant fields of the class under test (fields modified with final, including static fields) + +When accessing and modifying private and constant members, the IDE may prompt some syntax errors, but the compiler will be able to run the test normally. + +For the effect, see the use case in the test class of the `java-demo` sample project `DemoPrivateAccessTest`. (Using compile-time code enhancement, currently only the adaptation of the Java language is implemented) + +### Solution 2: Use the `PrivateAccessor` tool class + +If you don't want to see the IDE's syntax error reminder, or in a non-Java language JVM project (such as Kotlin language), you can also use the `PrivateAccessor` tool class to directly access private members. + +This class provides 6 static methods: + +- `PrivateAccessor.get(, "")` ➜ read the private field of the class under test +- `PrivateAccessor.set(, "", )` ➜ modify the private field (or constant field) of the class under test +- `PrivateAccessor.invoke(, "", ..)` ➜ call the private method of the class under test +- `PrivateAccessor.getStatic(, "")` ➜ read the **static** private field of the class under test +- `PrivateAccessor.setStatic(, "", )` ➜ modify the **static** private field (or **static** constant field) of the class under test +- `PrivateAccessor.invokeStatic(, "", ..)` ➜ call the **static** private method of the class under test + +For details, see the use cases in the test classes of the `java-demo` and `kotlin-demo` sample projects `DemoPrivateAccessTest`. diff --git a/docs/en-us/doc/release-note.md b/docs/en-us/doc/release-note.md new file mode 100644 index 0000000..1db2f94 --- /dev/null +++ b/docs/en-us/doc/release-note.md @@ -0,0 +1,69 @@ +# Release Note + +## 0.4.3 +- support static private member access + +## 0.4.2 +- support change javaagent global log level via maven plugin +- fix an issue of duplicate test class injection +- fix an issue cause multiple-line method invocation mock fail + +## 0.4.1 +- deprecate @TestableMock annotation, use @MockMethod and @MockConstructor instead + +## 0.4.0 +- fix a jvm 9+ compatibility issue cause by default classloader change +- fix a conflict issue when testcase name duplicated between different class +- refactor code structure, module `testable-all` added +- separate constant definition from `TestableTool` to `TestableConst` + +## 0.3.2 +- support grable project for both private member access and quick mock +- support access private static field and methods via PrivateAccessor + +## 0.3.1 +- support detail log of mocking process for diagnosis + +## v0.3.0 +- add `without()` checker to verify mock method never invoked with specified parameters +- support fuzz matcher when verifying mock invocation + +## v0.2.2 +- support mock method parameters check +- fix a compatibility issue with jvm 9+ + +## v0.2.1 +- support mock static method +- support mock kotlin companion object method +- support mock invoke by interface / base class object + +## v0.2.0 +- use `TestableTool` class to expose test context and verify mock invoke +- add `testable-maven-plugin` module to simplify javaagent configuration +- remove dependence on EnableTestable annotation in `testable-agent` +- rename annotations to reflect the actual use + +## v0.1.0 +- move generated agent jar to class folder +- support mock method of any object + +## v0.0.5 +- use dynamically runtime modification to replace static `e.java` file +- get rid of unit test framework dependence +- add testable ref field in test class at runtime instead of compile time + +## v0.0.4 +- use runtime byte code rewrite to invoke testable setup method +- add `TestableUtil` class to fetch current test case and invocation source + +## v0.0.3 +- use global method invoke to access private members instead of modification in place +- use `e.java` replace `testable` class make code more readable +- introduce `agent` module, use runtime byte code modification to support new operation and member method mocking + +## v0.0.2 +- add support of member method mocking by compile time code modification + +## v0.0.1 +- PoC version +- use compile time code modification to support new operation mocking and private field & method access diff --git a/docs/en-us/navbar.md b/docs/en-us/navbar.md new file mode 100644 index 0000000..d9badb9 --- /dev/null +++ b/docs/en-us/navbar.md @@ -0,0 +1,5 @@ +* [Home](/en-us/) +* [Feedback And Issue](https://github.com/alibaba/testable-mock/issues) +* Languages + * English + * [中文](/zh-cn/) diff --git a/docs/en-us/sidebar.md b/docs/en-us/sidebar.md new file mode 100644 index 0000000..609f4e9 --- /dev/null +++ b/docs/en-us/sidebar.md @@ -0,0 +1,16 @@ +- Quick Start + - [Use TestableMock](en-us/doc/setup.md) + - [Private Accessor](en-us/doc/private-accessor.md) + - [Fast Mocking](en-us/doc/use-mock.md) + - [Test Void Method](en-us/doc/test-void-method.md) + +- Usage Reference + - [Verify Mock Invocation](en-us/doc/invoke-matcher.md) + - [Frequently Asked Questions](en-us/doc/frequently-asked-questions.md) + - [Self-Help Troubleshooting](en-us/doc/troubleshooting.md) + - [Testable Maven Plugin](en-us/doc/use-maven-plugin.md) + +- Technical Reference + - [Mock Tools Comparison](en-us/doc/comparation.md) + - [Release Note](en-us/doc/release-note.md) + - [Feedback Channel](en-us/doc/feedback.md)