From d75fdcd4e95b24166a1a6455c11242dc3830fc32 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=87=91=E6=88=9F?= Date: Tue, 24 Nov 2020 23:18:12 +0800 Subject: [PATCH] update docs and release 0.3.1 --- README.md | 2 +- demo/java-demo/pom.xml | 42 ++++++------- demo/kotlin-demo/pom.xml | 2 +- docs/zh-cn/README.md | 4 +- docs/zh-cn/doc/known-issues.md | 46 -------------- docs/zh-cn/doc/private-accessor.md | 2 +- docs/zh-cn/doc/release-note.md | 2 + docs/zh-cn/doc/troubleshooting.md | 38 +++++++++++- docs/zh-cn/doc/usage.md | 60 +++++++++++-------- docs/zh-cn/doc/use-maven-plugin.md | 34 +++++++++++ docs/zh-cn/sidebar.md | 4 +- pom.xml | 2 +- testable-agent/pom.xml | 4 +- .../alibaba/testable/agent/util/LogUtil.java | 10 ++-- testable-core/pom.xml | 2 +- testable-maven-plugin/pom.xml | 4 +- testable-processor/pom.xml | 4 +- 17 files changed, 151 insertions(+), 111 deletions(-) delete mode 100644 docs/zh-cn/doc/known-issues.md create mode 100644 docs/zh-cn/doc/use-maven-plugin.md diff --git a/README.md b/README.md index 9a3ce22..8e94ccb 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 换种思路写Mock，让单元测试更简单。 -无需初始化，不挑测试框架，甭管要换的方法是被测类的私有方法、静态方法还是其他任何类的成员方法，也甭管要换的对象是怎么创建的。写好Mock方法，加个@TestableMock注解，一切统统搞定。 +无需初始化，不挑测试框架，甭管要换的方法是被测类的私有方法、静态方法还是其他任何类的成员方法，也甭管要换的对象是怎么创建的。写好Mock方法，加个`@TestableMock`注解，一切统统搞定。 文档：https://alibaba.github.io/testable-mock/ diff --git a/demo/java-demo/pom.xml b/demo/java-demo/pom.xml index fbec31f..ded34aa 100644 --- a/demo/java-demo/pom.xml +++ b/demo/java-demo/pom.xml @@ -11,7 +11,7 @@ 1.8 1.8 - 0.3.1-SNAPSHOT + 0.3.1 @@ -36,26 +36,26 @@ maven-surefire-plugin 3.0.0-M5 - - - - - - - - - com.alibaba.testable - testable-maven-plugin - ${testable.version} - - - prepare - - prepare - - - - + + org.apache.maven.plugins + maven-surefire-plugin + + @{argLine} -javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/${testable.version}/testable-agent-${testable.version}.jar + + + + + + + + + + + + + + + org.jacoco jacoco-maven-plugin diff --git a/demo/kotlin-demo/pom.xml b/demo/kotlin-demo/pom.xml index e8ff31d..6d692e7 100644 --- a/demo/kotlin-demo/pom.xml +++ b/demo/kotlin-demo/pom.xml @@ -13,7 +13,7 @@ 1.3.72 1.8 1.8 - 0.3.1-SNAPSHOT + 0.3.1 diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md index 59587cf..01a8317 100644 --- a/docs/zh-cn/README.md +++ b/docs/zh-cn/README.md @@ -7,4 +7,6 @@ TestableMock简介 然而当下主流的Mock框架在实现Mock功能时，需要开发者操心的事情实在太多：Mock框架如何初始化、与所用的单元测试框架是否兼容、要被Mock的方法是不是私有的、是不是静态的、被Mock对象是new出来的还是注入的、怎样把被测对象送回被测类里...这些非关键的额外工作极大分散了使用Mock工具应有的乐趣。 -为此，我们开发了`TestableMock`，**一款特立独行的轻量Mock工具**。 +于是，我们开发了`TestableMock`，**一款特立独行的轻量Mock工具**。 + +![mock](https://testable-code.oss-cn-beijing.aliyuncs.com/mock.jpg) diff --git a/docs/zh-cn/doc/known-issues.md b/docs/zh-cn/doc/known-issues.md deleted file mode 100644 index 2cf83d7..0000000 --- a/docs/zh-cn/doc/known-issues.md +++ /dev/null @@ -1,46 +0,0 @@ -已知缺陷 ---- - -#### 1. 访问私有方法或私有成员代码在IDE提示语法错误 - -使用`@EnablePrivateAccessor`注解后访问私有方法或成员变量，虽然能正常通过编译，但在IDE上依然会提示语法错误。 -这个问题与使用`Lombok`工具库后使用生成的`getter`和`setter`会被IDE报语法错误一样，需要通过IDE插件来解决。 -当前`TestableMock`尚未提供相关插件。也可以改用`PrivateAccessor`工具类来访问私有成员，来避免IDE的异常信息。 - -#### 2. 通过IDE运行单个测试用例时，Mock功能失效 - -这是由于IDE运行单个测试用例时只会运行`maven-surefire-plugin`插件，跳过了`testable-maven-plugin`插件执行，导致Mock功能所需的JavaAgent没有随测试启动。 - -解决方法有两种： - -**方法一**：在单元测试配置的"虚拟机参数（VM Option）"属性值末尾添加JavaAgent启动参数：`-javaagent:${HOME}/.m2/repository/com/alibaba/testable/testable-agent/0.3.0/testable-agent-0.3.0.jar` - -> PS：请将路径中的版本号替换成实际使用的版本号 - -![idea-vm-option](https://testable-code.oss-cn-beijing.aliyuncs.com/idea-vm-option.png) - -**方法二**：不使用`testable-maven-plugin`插件，直接配置JavaAgent参数到`maven-surefire-plugin`插件上。（`JMockit`也是使用了这种方法）配置方法为： - -> PS：请将路径中的版本号替换成实际使用的版本号 - -```xml - - org.apache.maven.plugins - maven-surefire-plugin - - -javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/0.2.2/testable-agent-0.2.2.jar - - -``` - -用这种方法需要注意，如果项目同时还使用了`Jacoco`的`on-the-fly`模式（默认模式）统计单元测试覆盖率，则需要在参数中再添加一个`@{argLine}`参数，完整配置如下： - -```xml - - org.apache.maven.plugins - maven-surefire-plugin - - @{argLine} -javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/0.2.2/testable-agent-0.2.2.jar - - -``` diff --git a/docs/zh-cn/doc/private-accessor.md b/docs/zh-cn/doc/private-accessor.md index 3cec22e..d08eabe 100644 --- a/docs/zh-cn/doc/private-accessor.md +++ b/docs/zh-cn/doc/private-accessor.md @@ -10,6 +10,6 @@ 访问和修改私有、常量成员时，IDE可能会提示语法有误，但编译器将能够正常运行测试。 -若不希望看到IDE的语法错误提醒，或是在基于JVM的非Java语言项目里（譬如Kotlin语言），也可以借助`PrivateAccessor`工具类来实现私有成员的访问。 +若不希望看到IDE的语法错误提醒，或是在非Java语言的JVM项目里（譬如Kotlin语言），也可以借助`PrivateAccessor`工具类来实现私有成员的访问。 效果见`java-demo`和`kotlin-demo`示例项目`DemoPrivateAccessTest`测试类中的用例。 diff --git a/docs/zh-cn/doc/release-note.md b/docs/zh-cn/doc/release-note.md index 7116d0e..39291dd 100644 --- a/docs/zh-cn/doc/release-note.md +++ b/docs/zh-cn/doc/release-note.md @@ -2,6 +2,8 @@ ## upcoming version - support share mock method between test classes + +## 0.3.1 - support detail log of mocking process for diagnosis ## v0.3.0 diff --git a/docs/zh-cn/doc/troubleshooting.md b/docs/zh-cn/doc/troubleshooting.md index 37d81b3..790e413 100644 --- a/docs/zh-cn/doc/troubleshooting.md +++ b/docs/zh-cn/doc/troubleshooting.md @@ -1,4 +1,40 @@ 自助问题排查 --- -TBD +相比Mockito等由开发者手工放置Mock类的做法，TestableMock使用方法名和参数类型匹配自动寻找需Mock的调用。这种机制在带来方便的同时也有可能发生预料之外的Mock替换。 + +若要排查Mock相关的问题，只需在测试类上添加`@MockWith`注解，并配置参数`diagnose`值为`MockDiagnose.ENABLE`，在运行测试时就会打印出详细的Mock方法替换过程。 + +```java +@MockWith(diagnose = MockDiagnose.ENABLE) +class DemoTest { + ... +} +``` + +输出日志示例如下： + +```text +[DIAGNOSE] Handling test class com/alibaba/testable/demo/DemoMockTest +[DIAGNOSE] Handling source class com/alibaba/testable/demo/DemoMock +[DIAGNOSE] Found 7 mock methods +[DIAGNOSE] Handling method +[DIAGNOSE] Handling method newFunc +[DIAGNOSE] Line 14, mock method createBlackBox used +[DIAGNOSE] Handling method outerFunc +[DIAGNOSE] Line 22, mock method innerFunc used +[DIAGNOSE] Handling method commonFunc +[DIAGNOSE] Line 29, mock method trim used +[DIAGNOSE] Line 29, mock method sub used +[DIAGNOSE] Line 29, mock method startsWith used +[DIAGNOSE] Handling method getBox +[DIAGNOSE] Line 36, mock method secretBox used +[DIAGNOSE] Handling method callerOne +[DIAGNOSE] Line 43, mock method callFromDifferentMethod used +[DIAGNOSE] Handling method callerTwo +[DIAGNOSE] Line 47, mock method callFromDifferentMethod used +[DIAGNOSE] Handling method innerFunc +[DIAGNOSE] Handling method callFromDifferentMethod +``` + +该日志展示了被测类中所有发生了Mock替换的调用和相应代码行号。 diff --git a/docs/zh-cn/doc/usage.md b/docs/zh-cn/doc/usage.md index e236684..3354c1c 100644 --- a/docs/zh-cn/doc/usage.md +++ b/docs/zh-cn/doc/usage.md @@ -8,38 +8,50 @@ ## 在Maven项目中使用 -在`pom.xml`文件中添加`testable-processor`依赖： +在项目`pom.xml`文件中，增加`testable-processor`依赖和`maven-surefire-plugin`配置，具体方法如下。 + +建议先添加一个标识TestableMock版本的`property`，便于统一管理： ```xml - - com.alibaba.testable - testable-processor - ${testable.version} - provided - + + 0.3.1 + ``` -以及`testable-maven-plugin`插件： +在`dependencies`列表添加`testable-processor`依赖： ```xml - - com.alibaba.testable - testable-maven-plugin - ${testable.version} - - - prepare - - prepare - - - - + + + com.alibaba.testable + testable-processor + ${testable.version} + provided + + ``` -> 其中`${testable.version}`需替换为具体版本号，当前最新版本为`0.3.0` +最后在`build`区域的`plugins`列表里添加`maven-surefire-plugin`插件（如果已有此插件则只需添加``部分配置）： -若仅需使用单元测试随意访问被测类私有字段和方法的能力，不使用Mock功能，则`testable-maven-plugin`插件可以省略。 +```xml + + + + org.apache.maven.plugins + maven-surefire-plugin + + -javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/${testable.version}/testable-agent-${testable.version}.jar + + + + +``` + +若项目同时还使用了`Jacoco`的`on-the-fly`模式（默认模式）统计单元测试覆盖率，则需在``配置中添加一个`@{argLine}`参数，添加后的配置如下： + +```xml +@{argLine} -javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/${testable.version}/testable-agent-${testable.version}.jar +``` ## 在Gradle项目中使用 @@ -47,7 +59,7 @@ ```groovy dependencies { - testCompile('com.alibaba.testable:testable-processor:0.3.0') + testCompile('com.alibaba.testable:testable-processor:0.3.1') } ``` diff --git a/docs/zh-cn/doc/use-maven-plugin.md b/docs/zh-cn/doc/use-maven-plugin.md new file mode 100644 index 0000000..2ce461b --- /dev/null +++ b/docs/zh-cn/doc/use-maven-plugin.md @@ -0,0 +1,34 @@ +使用Testable Maven插件 +--- + +在使用Maven构建的项目里，除了直接修改`maven-surefire-plugin`插件的运行参数，也可通过`testable-maven-plugin`插件获得相同效果： + +```xml + + com.alibaba.testable + testable-maven-plugin + ${testable.version} + + + prepare + + prepare + + + + +``` + +> 当使用`testable-maven-plugin`插件时，应该移除`maven-surefire-plugin`插件上的TestableMock相关配置 + +相比而言，`testable-maven-plugin`插件能够与Jacoco插件直接同时使用，无需额外适配。但当通过IDE运行单个测试用例时，Mock功能会失效。 + +这是由于IDE运行单个测试用例时只会运行`maven-surefire-plugin`插件，跳过了`testable-maven-plugin`插件执行，导致Mock功能所需的JavaAgent没有随测试启动。 + +这个问题可以通过配置IDE的测试参数绕过。以IntelliJ为例，在单元测试配置的"虚拟机参数（VM Option）"属性值末尾添加JavaAgent启动参数：`-javaagent:${HOME}/.m2/repository/com/alibaba/testable/testable-agent/x.y.z/testable-agent-x.y.z.jar` + +> PS：请将路径中的`x.y.z`替换成实际使用的版本号 + +![idea-vm-option](https://testable-code.oss-cn-beijing.aliyuncs.com/idea-vm-option.png) + +由于需要在每个单测任务上分别配置，这种方法实际使用起来比较麻烦，因此目前依然优先推荐修改`maven-surefire-plugin`插件配置的方案。 diff --git a/docs/zh-cn/sidebar.md b/docs/zh-cn/sidebar.md index ef5a8b1..80fda66 100644 --- a/docs/zh-cn/sidebar.md +++ b/docs/zh-cn/sidebar.md @@ -3,9 +3,9 @@ - [直接访问私有成员](zh-cn/doc/private-accessor.md) - [快速Mock任意方法](zh-cn/doc/use-mock.md) - [校验Mock调用](zh-cn/doc/matcher.md) + - [常见使用问题](zh-cn/doc/frequency-asked-questions.md) - [自助问题排查](zh-cn/doc/troubleshooting.md) - 其他文档 - - [常见问题](zh-cn/doc/frequency-asked-questions.md) - - [已知缺陷](zh-cn/doc/known-issues.md) + - [Testable Maven插件](zh-cn/doc/use-maven-plugin.md) - [Release Note](zh-cn/doc/release-note.md) diff --git a/pom.xml b/pom.xml index fc1a7e8..f5f7ae3 100755 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ 4.0.0 com.alibaba.testable - parent + testable-parent 1.0.0-SNAPSHOT pom diff --git a/testable-agent/pom.xml b/testable-agent/pom.xml index 3515566..0bce414 100755 --- a/testable-agent/pom.xml +++ b/testable-agent/pom.xml @@ -5,7 +5,7 @@ 4.0.0 com.alibaba.testable testable-agent - 0.3.1-SNAPSHOT + 0.3.1 jar testable-agent Unit test enhancement toolkit @@ -35,7 +35,7 @@ UTF-8 8.0.1 5.6.2 - 0.3.1-SNAPSHOT + 0.3.1 3.8.1 3.0.0-M5 3.2.0 diff --git a/testable-agent/src/main/java/com/alibaba/testable/agent/util/LogUtil.java b/testable-agent/src/main/java/com/alibaba/testable/agent/util/LogUtil.java index dfe64d3..3f304ff 100644 --- a/testable-agent/src/main/java/com/alibaba/testable/agent/util/LogUtil.java +++ b/testable-agent/src/main/java/com/alibaba/testable/agent/util/LogUtil.java @@ -7,20 +7,20 @@ public class LogUtil { private static final int LEVEL_ERROR = 0; private static final int LEVEL_WARN = 1; - private static final int LEVEL_DEBUG = 2; + private static final int LEVEL_DIAGNOSE = 2; private static final ThreadLocal LEVEL = new ThreadLocal(); public static boolean globalDebugEnable = false; public static void debug(String msg, Object... args) { - if (LEVEL.get() >= LEVEL_DEBUG) { - System.err.println(String.format("[DEBUG] " + msg, args)); + if (LEVEL.get() >= LEVEL_DIAGNOSE) { + System.out.println(String.format("[DIAGNOSE] " + msg, args)); } } public static void enableDebugLog() { LEVEL.remove(); - LEVEL.set(LEVEL_DEBUG); + LEVEL.set(LEVEL_DIAGNOSE); } public static void disableDebugLog() { @@ -29,7 +29,7 @@ public class LogUtil { } public static void resetDebugLog() { - LEVEL.set(globalDebugEnable ? LEVEL_DEBUG : LEVEL_WARN); + LEVEL.set(globalDebugEnable ? LEVEL_DIAGNOSE : LEVEL_WARN); } } diff --git a/testable-core/pom.xml b/testable-core/pom.xml index 9cf7004..68c3dbb 100644 --- a/testable-core/pom.xml +++ b/testable-core/pom.xml @@ -5,7 +5,7 @@ 4.0.0 com.alibaba.testable testable-core - 0.3.1-SNAPSHOT + 0.3.1 jar testable-core Unit test enhancement toolkit diff --git a/testable-maven-plugin/pom.xml b/testable-maven-plugin/pom.xml index 50b886f..e7a7da9 100644 --- a/testable-maven-plugin/pom.xml +++ b/testable-maven-plugin/pom.xml @@ -5,7 +5,7 @@ 4.0.0 com.alibaba.testable testable-maven-plugin - 0.3.1-SNAPSHOT + 0.3.1 maven-plugin testable-maven-plugin Unit test enhancement toolkit @@ -30,7 +30,7 @@ - 0.3.1-SNAPSHOT + 0.3.1 1.6 1.6 UTF-8 diff --git a/testable-processor/pom.xml b/testable-processor/pom.xml index 4dce6fb..b377753 100644 --- a/testable-processor/pom.xml +++ b/testable-processor/pom.xml @@ -5,7 +5,7 @@ 4.0.0 com.alibaba.testable testable-processor - 0.3.1-SNAPSHOT + 0.3.1 jar testable-processor Unit test enhancement toolkit @@ -34,7 +34,7 @@ 1.6 UTF-8 5.6.2 - 0.3.1-SNAPSHOT + 0.3.1 3.8.1 3.0.0-M5 3.2.0