github-repos/testable-mock
1
0
Fork 0
mirror of https://github.com/alibaba/testable-mock.git synced 2026-08-23 03:33:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

update docs and release 0.3.1

Browse Source
This commit is contained in:
金戟
2020-11-24 23:18:12 +08:00
parent df9da81f75
commit d75fdcd4e9
17 changed files with 151 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/zh-cn/README.md
View File

@@ -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)

46
docs/zh-cn/doc/known-issues.md
View File

@@ -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
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<argLine>-javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/0.2.2/testable-agent-0.2.2.jar</argLine>
</configuration>
</plugin>
```
用这种方法需要注意，如果项目同时还使用了`Jacoco`的`on-the-fly`模式（默认模式）统计单元测试覆盖率，则需要在参数中再添加一个`@{argLine}`参数，完整配置如下：
```xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<argLine>@{argLine} -javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/0.2.2/testable-agent-0.2.2.jar</argLine>
</configuration>
</plugin>
```

2
docs/zh-cn/doc/private-accessor.md
View File

@@ -10,6 +10,6 @@
访问和修改私有、常量成员时，IDE可能会提示语法有误，但编译器将能够正常运行测试。
若不希望看到IDE的语法错误提醒，或是在基于JVM的非Java语言项目里（譬如Kotlin语言），也可以借助`PrivateAccessor`工具类来实现私有成员的访问。
若不希望看到IDE的语法错误提醒，或是在非Java语言的JVM项目里（譬如Kotlin语言），也可以借助`PrivateAccessor`工具类来实现私有成员的访问。
效果见`java-demo`和`kotlin-demo`示例项目`DemoPrivateAccessTest`测试类中的用例。

2
docs/zh-cn/doc/release-note.md
View File

@@ -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

38
docs/zh-cn/doc/troubleshooting.md
View File

@@ -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 <init>
[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替换的调用和相应代码行号。

60
docs/zh-cn/doc/usage.md
View File

@@ -8,38 +8,50 @@
## 在Maven项目中使用
在`pom.xml`文件中添加`testable-processor`依赖：
在项目`pom.xml`文件中，增加`testable-processor`依赖和`maven-surefire-plugin`配置，具体方法如下。
建议先添加一个标识TestableMock版本的`property`，便于统一管理：
```xml
<dependency>
<groupId>com.alibaba.testable</groupId>
<artifactId>testable-processor</artifactId>
<version>${testable.version}</version>
<scope>provided</scope>
</dependency>
<properties>
<testable.version>0.3.1</testable.version>
</properties>
```
以及`testable-maven-plugin`插件：
在`dependencies`列表添加`testable-processor`依赖：
```xml
<plugin>
<groupId>com.alibaba.testable</groupId>
<artifactId>testable-maven-plugin</artifactId>
<version>${testable.version}</version>
<executions>
<execution>
<id>prepare</id>
<goals>
<goal>prepare</goal>
</goals>
</execution>
</executions>
</plugin>
<dependencies>
<dependency>
<groupId>com.alibaba.testable</groupId>
<artifactId>testable-processor</artifactId>
<version>${testable.version}</version>
<scope>provided</scope>
</dependency>
</dependencies>
```
> 其中`${testable.version}`需替换为具体版本号，当前最新版本为`0.3.0`
最后在`build`区域的`plugins`列表里添加`maven-surefire-plugin`插件（如果已有此插件则只需添加`<argLine>`部分配置）：
若仅需使用单元测试随意访问被测类私有字段和方法的能力，不使用Mock功能，则`testable-maven-plugin`插件可以省略。
```xml
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<argLine>-javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/${testable.version}/testable-agent-${testable.version}.jar</argLine>
</configuration>
</plugin>
</plugins>
</build>
```
若项目同时还使用了`Jacoco`的`on-the-fly`模式（默认模式）统计单元测试覆盖率，则需在`<argLine>`配置中添加一个`@{argLine}`参数，添加后的配置如下：
```xml
<argLine>@{argLine} -javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/${testable.version}/testable-agent-${testable.version}.jar</argLine>
```
## 在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')
}
```

34
docs/zh-cn/doc/use-maven-plugin.md Normal file
View File

@@ -0,0 +1,34 @@
使用Testable Maven插件
---
在使用Maven构建的项目里，除了直接修改`maven-surefire-plugin`插件的运行参数，也可通过`testable-maven-plugin`插件获得相同效果：
```xml
<plugin>
<groupId>com.alibaba.testable</groupId>
<artifactId>testable-maven-plugin</artifactId>
<version>${testable.version}</version>
<executions>
<execution>
<id>prepare</id>
<goals>
<goal>prepare</goal>
</goals>
</execution>
</executions>
</plugin>
```
> 当使用`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`插件配置的方案。

4
docs/zh-cn/sidebar.md
View File

@@ -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)