diff --git a/README.md b/README.md index ab65154..9a3ce22 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # TestableMock -基于代码和字节码增强的Java单元测试辅助工具，包含以下功能： +换种思路写Mock，让单元测试更简单。 -- 使单元测试能直接调用和访问被测类的私有成员，解决私有方法无法测试的问题 -- 使被测类的任意方法调用快速替换为Mock，实现"指哪换哪"，解决传统Mock工具使用繁琐的问题 +无需初始化，不挑测试框架，甭管要换的方法是被测类的私有方法、静态方法还是其他任何类的成员方法，也甭管要换的对象是怎么创建的。写好Mock方法，加个@TestableMock注解，一切统统搞定。 + +文档：https://alibaba.github.io/testable-mock/ ## 目录结构 @@ -25,3 +26,12 @@ ```bash mvn clean install ``` + +## 本地生成文档 + +```bash +docsify serve docs +``` + +> Testable文档使用`docsify`工具生成，构建前请安装[nodejs](https://nodejs.org/en/download/)运行时，并使用`npm install -g docsify`命令安装文档生成工具。 + diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..61f49a2 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,40 @@ + + + + + + TestableMock + + + + + + + +
Loading...
+ + + + + + + diff --git a/docs/introduction.md b/docs/introduction.md deleted file mode 100644 index 7416dfc..0000000 --- a/docs/introduction.md +++ /dev/null @@ -1,14 +0,0 @@ -TestableMock简介 ---- - -换种思路写Mock，让单元测试更简单。 - -单元测试中的Mock方法，通常是为了绕开那些依赖**外部资源**或**无关功能**的方法调用，使得测试重点能够集中在**需要验证和保障的代码逻辑**上。 - -在定义Mock方法时，开发者真正关心的只有一件事：这个调用，在测试的时候要换成那个假的Mock方法。 - -然而当下主流的Mock框架在实现Mock功能时，需要开发者操心的事情实在太多：Mock框架如何初始化、与所用的单元测试框架是否兼容、要被Mock的方法是不是私有的、是不是静态的、被Mock对象是new出来的还是注入的、怎样把被测对象送回被测类里...这些非关键的额外工作极大分散了使用Mock工具应有的乐趣。 - -为此，我们开发了`TestableMock`，**一款与众不同的轻量Mock工具**。 - -无需初始化，不挑测试框架，甭管要换的方法是被测类的私有方法、静态方法还是其他任何类的成员方法，也甭管要换的对象是怎么创建的。写好Mock方法，加上`@TestableMock`注解，一切统统搞定。 diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md new file mode 100644 index 0000000..59587cf --- /dev/null +++ b/docs/zh-cn/README.md @@ -0,0 +1,10 @@ +TestableMock简介 +--- + +单元测试中的Mock方法，通常是为了绕开那些依赖外部资源或无关功能的方法调用，使得测试重点能够集中在需要验证和保障的代码逻辑上。 + +在定义Mock方法时，开发者真正关心的只有一件事："这个调用，在测试的时候要换成那个假的Mock方法"。 + +然而当下主流的Mock框架在实现Mock功能时，需要开发者操心的事情实在太多：Mock框架如何初始化、与所用的单元测试框架是否兼容、要被Mock的方法是不是私有的、是不是静态的、被Mock对象是new出来的还是注入的、怎样把被测对象送回被测类里...这些非关键的额外工作极大分散了使用Mock工具应有的乐趣。 + +为此，我们开发了`TestableMock`，**一款特立独行的轻量Mock工具**。 diff --git a/docs/frequency-asked-questions.md b/docs/zh-cn/doc/frequency-asked-questions.md similarity index 92% rename from docs/frequency-asked-questions.md rename to docs/zh-cn/doc/frequency-asked-questions.md index 7bfd4f4..d499e58 100644 --- a/docs/frequency-asked-questions.md +++ b/docs/zh-cn/doc/frequency-asked-questions.md @@ -19,4 +19,4 @@ 结合[Roboelectric](https://github.com/robolectric/robolectric)测试框架可使用。 -Android系统的`Dalvik`和`ART`虚拟机采用了与标准JVM不同的字节码体系，会影响`TestableMock`的正常工作。`Roboelectric`框架能在普通JVM虚拟机上运行Android单元测试，其速度比通过Android虚拟机运行单元测试快非常多，当下绝大多数Android App的单元测试都使用了`Roboelectric`框架。 +Android系统的`Dalvik`和`ART`虚拟机采用了与标准JVM不同的字节码体系，会影响`TestableMock`的正常工作。`Roboelectric`框架能在普通JVM虚拟机上运行Android单元测试，其速度比通过Android虚拟机运行单元测试快非常多，绝大多数Android App的单元测试都在使用`Roboelectric`框架。 diff --git a/docs/known-issues.md b/docs/zh-cn/doc/known-issues.md similarity index 99% rename from docs/known-issues.md rename to docs/zh-cn/doc/known-issues.md index 4f30642..2cf83d7 100644 --- a/docs/known-issues.md +++ b/docs/zh-cn/doc/known-issues.md @@ -1,4 +1,4 @@ -已知问题 +已知缺陷 --- #### 1. 访问私有方法或私有成员代码在IDE提示语法错误 diff --git a/docs/matcher.md b/docs/zh-cn/doc/matcher.md similarity index 100% rename from docs/matcher.md rename to docs/zh-cn/doc/matcher.md diff --git a/docs/zh-cn/doc/private-accessor.md b/docs/zh-cn/doc/private-accessor.md new file mode 100644 index 0000000..3cec22e --- /dev/null +++ b/docs/zh-cn/doc/private-accessor.md @@ -0,0 +1,15 @@ +访问私有成员字段和方法 +--- + +只需为测试类添加`@EnablePrivateAccess`注解，即可在测试用例中获得以下增强能力： + +- 调用被测类的私有方法 +- 读取被测类的私有成员 +- 修改被测类的私有成员 +- 修改被测类的常量成员（使用final修饰的成员） + +访问和修改私有、常量成员时，IDE可能会提示语法有误，但编译器将能够正常运行测试。 + +若不希望看到IDE的语法错误提醒，或是在基于JVM的非Java语言项目里（譬如Kotlin语言），也可以借助`PrivateAccessor`工具类来实现私有成员的访问。 + +效果见`java-demo`和`kotlin-demo`示例项目`DemoPrivateAccessTest`测试类中的用例。 diff --git a/docs/release-note.md b/docs/zh-cn/doc/release-note.md similarity index 100% rename from docs/release-note.md rename to docs/zh-cn/doc/release-note.md diff --git a/docs/troubleshooting.md b/docs/zh-cn/doc/troubleshooting.md similarity index 100% rename from docs/troubleshooting.md rename to docs/zh-cn/doc/troubleshooting.md diff --git a/docs/zh-cn/doc/usage.md b/docs/zh-cn/doc/usage.md new file mode 100644 index 0000000..e236684 --- /dev/null +++ b/docs/zh-cn/doc/usage.md @@ -0,0 +1,62 @@ +使用TestableMock +--- + +`TestableMock`是基于源码和字节码增强的Java单元测试辅助工具，包含以下功能： + +- [访问被测类私有成员](zh-cn/doc/private-accessor.md)：使单元测试能直接调用和访问被测类的私有成员，解决私有成员初始化和私有方法测试的问题 +- [快速Mock任意方法](zh-cn/doc/use-mock.md)：使被测类的任意方法调用快速替换为Mock方法，实现"指哪换哪"，解决传统Mock工具使用繁琐的问题 + +## 在Maven项目中使用 + +在`pom.xml`文件中添加`testable-processor`依赖： + +```xml + + com.alibaba.testable + testable-processor + ${testable.version} + provided + +``` + +以及`testable-maven-plugin`插件： + +```xml + + com.alibaba.testable + testable-maven-plugin + ${testable.version} + + + prepare + + prepare + + + + +``` + +> 其中`${testable.version}`需替换为具体版本号，当前最新版本为`0.3.0` + +若仅需使用单元测试随意访问被测类私有字段和方法的能力，不使用Mock功能，则`testable-maven-plugin`插件可以省略。 + +## 在Gradle项目中使用 + +在`build.gradle`文件中添加`testable-processor`依赖： + +```groovy +dependencies { + testCompile('com.alibaba.testable:testable-processor:0.3.0') +} +``` + +然后在测试配置中添加javaagent： + +```groovy +test { + jvmArgs "-javaagent:${classpath.find { it.name.contains("testable-agent") }.absolutePath}" +} +``` + +> 该配置尚未在Gradle项目上经过实际验证，可行性待确认。 diff --git a/docs/usage.md b/docs/zh-cn/doc/use-mock.md similarity index 67% rename from docs/usage.md rename to docs/zh-cn/doc/use-mock.md index f54c4fa..a2c8939 100644 --- a/docs/usage.md +++ b/docs/zh-cn/doc/use-mock.md @@ -1,63 +1,7 @@ -使用说明 +快速Mock被测类的任意方法调用 --- -## 引入TestableMock - -在项目的`pom.xml`文件中添加`testable-processor`依赖： - -```xml - - com.alibaba.testable - testable-processor - ${testable.version} - provided - -``` - -以及`testable-maven-plugin`插件： - -```xml - - com.alibaba.testable - testable-maven-plugin - ${testable.version} - - - prepare - - prepare - - - - -``` - -> 其中`${testable.version}`需替换为具体版本号，当前最新版本为`0.3.1-SNAPSHOT` - -若仅需使用单元测试随意访问被测类私有字段和方法的能力，不使用Mock功能，则`testable-maven-plugin`插件可以省略。 - -## 使用TestableMock - -`TestableMock`目前能为测试类提供两项增强能力：__直接访问被测类的私有成员__ 和 __极速Mock被测方法中的调用__ - -### 访问私有成员字段和方法 - -只需为测试类添加`@EnablePrivateAccess`注解，即可在测试用例中获得以下增强能力： - -- 调用被测类的私有方法 -- 读取被测类的私有成员 -- 修改被测类的私有成员 -- 修改被测类的常量成员（使用final修饰的成员） - -访问和修改私有、常量成员时，IDE可能会提示语法有误，但编译器将能够正常运行测试。 - -若不希望看到IDE的语法错误提醒，或是在基于JVM的非Java语言项目里（譬如Kotlin语言），也可以借助`PrivateAccessor`工具类来实现私有成员的访问。 - -效果见`java-demo`和`kotlin-demo`示例项目中`DemoPrivateAccessTest`测试类的用例。 - -### Mock被测类的任意方法调用 - -**1. 覆写任意类的方法调用** +#### 1. 覆写任意类的方法调用 在测试类里定义一个有`@TestableMock`注解的普通方法，使它与需覆写的方法名称、参数、返回值类型完全一致，然后在其参数列表首位再增加一个类型为该方法原本所属对象类型的参数。 @@ -80,7 +24,7 @@ private String substring(String self, int i, int j) { 完整代码示例见`java-demo`和`kotlin-demo`示例项目中的`should_able_to_mock_common_method()`测试用例。(由于Kotlin对String类型进行了魔改，故Kotlin示例中将被测方法在`BlackBox`类里加了一层封装) -**2. 覆写被测类自身的成员方法** +#### 2. 覆写被测类自身的成员方法 有时候，在对某些方法进行测试时，希望将被测类自身的另外一些成员方法Mock掉。 @@ -99,7 +43,7 @@ private String innerFunc(DemoMock self, String text) { 完整代码示例见`java-demo`和`kotlin-demo`示例项目中的`should_able_to_mock_member_method()`测试用例。 -**3. 覆写任意类的静态方法** +#### 3. 覆写任意类的静态方法 对于静态方法的Mock与普通方法相同。但需要注意的是，对于静态方法，传入Mock方法的第一个参数实际值始终是`null`。 @@ -117,7 +61,7 @@ private BlackBox secretBox(BlackBox ignore) { 完整代码示例见`java-demo`和`kotlin-demo`示例项目中的`should_able_to_mock_static_method()`测试用例。 -**4. 覆写任意类的new操作** +#### 4. 覆写任意类的new操作 在测试类里定义一个有`@TestableMock`注解的普通方法，将注解的`targetMethod`参数写为""，然后使该方法与要被创建类型的构造函数参数、返回值类型完全一致，方法名称随意。 @@ -137,15 +81,14 @@ private BlackBox createBlackBox(String text) { 完整代码示例见`java-demo`和`kotlin-demo`示例项目中的`should_able_to_mock_new_object()`测试用例。 -**5. 识别当前测试用例和调用来源** +#### 5. 识别当前测试用例和调用来源 在Mock方法中可以通过`TestableTool.TEST_CASE`和`TestableTool.SOURCE_METHOD`来识别**当前运行的测试用例名称**和**进入该Mock方法前的被测类方法名称**，从而区分处理不同的调用场景。 完整代码示例见`java-demo`和`kotlin-demo`示例项目中的`should_able_to_get_source_method_name()`和`should_able_to_get_test_case_name()`测试用例。 -**6. 验证Mock方法被调用的顺序和参数** +#### 6. 验证Mock方法被调用的顺序和参数 在测试用例中可用通过`TestableTool.verify()`方法，配合`with()`、`withInOrder()`、`without()`、`withTimes()`等方法实现对Mock调用情况的验证。 -详见`java-demo`和`kotlin-demo`示例项目中的相关测试用例。 - +详见[校验Mock调用](zh-cn/doc/matcher.md)文档。 diff --git a/docs/zh-cn/navbar.md b/docs/zh-cn/navbar.md new file mode 100644 index 0000000..f64f3c9 --- /dev/null +++ b/docs/zh-cn/navbar.md @@ -0,0 +1,2 @@ +* [首页](/zh-cn/) +* [问题和反馈](https://github.com/alibaba/testable-mock/issues) diff --git a/docs/zh-cn/sidebar.md b/docs/zh-cn/sidebar.md new file mode 100644 index 0000000..ef5a8b1 --- /dev/null +++ b/docs/zh-cn/sidebar.md @@ -0,0 +1,11 @@ +- 使用指南 + - [使用TestableMock](zh-cn/doc/usage.md) + - [直接访问私有成员](zh-cn/doc/private-accessor.md) + - [快速Mock任意方法](zh-cn/doc/use-mock.md) + - [校验Mock调用](zh-cn/doc/matcher.md) + - [自助问题排查](zh-cn/doc/troubleshooting.md) + +- 其他文档 + - [常见问题](zh-cn/doc/frequency-asked-questions.md) + - [已知缺陷](zh-cn/doc/known-issues.md) + - [Release Note](zh-cn/doc/release-note.md)