From 8a3a0cf6bfd63cbc1f15871bb9948466e841f512 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=87=91=E6=88=9F?= Date: Tue, 1 Jun 2021 10:58:00 +0800 Subject: [PATCH] add with thread pool doc --- docs/en-us/doc/setup.md | 3 +- docs/en-us/doc/with-thread-pool.md | 4 +++ docs/en-us/sidebar.md | 1 + docs/zh-cn/doc/javaagent-args.md | 2 +- docs/zh-cn/doc/setup.md | 5 +-- docs/zh-cn/doc/with-thread-pool.md | 52 ++++++++++++++++++++++++++++++ docs/zh-cn/sidebar.md | 1 + 7 files changed, 64 insertions(+), 4 deletions(-) create mode 100644 docs/en-us/doc/with-thread-pool.md create mode 100644 docs/zh-cn/doc/with-thread-pool.md diff --git a/docs/en-us/doc/setup.md b/docs/en-us/doc/setup.md index 62e790e..487a424 100644 --- a/docs/en-us/doc/setup.md +++ b/docs/en-us/doc/setup.md @@ -100,6 +100,7 @@ See the [build.gradle](https://github.com/alibaba/testable-mock/blob/master/demo > For Maven project, add `` and `` properties inside the `pom.xml` file, e.g. > ```xml > +> > 1.6 > 1.6 > @@ -107,7 +108,7 @@ See the [build.gradle](https://github.com/alibaba/testable-mock/blob/master/demo > > For Gradle project, add a `sourceCompatibility` property inside the `build.gradle` file, e.g. > ```groovy -> sourceCompatibility = '6' +> sourceCompatibility = '6' // or 7/8/9/... > ``` > > See project `demo/spock-demo` for a complete example. diff --git a/docs/en-us/doc/with-thread-pool.md b/docs/en-us/doc/with-thread-pool.md new file mode 100644 index 0000000..5567011 --- /dev/null +++ b/docs/en-us/doc/with-thread-pool.md @@ -0,0 +1,4 @@ +Mock Invocation In Thread Pool +--- + +TO BE TRANSLATED diff --git a/docs/en-us/sidebar.md b/docs/en-us/sidebar.md index 5cd1d8f..51b5927 100644 --- a/docs/en-us/sidebar.md +++ b/docs/en-us/sidebar.md @@ -12,6 +12,7 @@ - [Use MockWith Annotation](en-us/doc/use-mock-with.md) - [Use Package Mapping](en-us/doc/use-package-mapping.md) - [Frequently Asked Questions](en-us/doc/frequently-asked-questions.md) + - [Mock Invocation In Thread Pool](zh-cn/doc/with-thread-pool.md) - [Use TestableMock In IDE](en-us/doc/use-in-ide.md) - [Self-Help Troubleshooting](en-us/doc/troubleshooting.md) - [Testable Maven Plugin](en-us/doc/use-maven-plugin.md) diff --git a/docs/zh-cn/doc/javaagent-args.md b/docs/zh-cn/doc/javaagent-args.md index 7532232..016ac76 100644 --- a/docs/zh-cn/doc/javaagent-args.md +++ b/docs/zh-cn/doc/javaagent-args.md @@ -58,4 +58,4 @@ 若项目测试中，既包含真实的单元测试，又包含了使用单元测试框架编写的集成测试时。为了让集成测试的执行过程不受Mock影响，可能需要使用`mock.scope.default`将默认的Mock方法范围限制为仅对所属类型的单元测试用例生效。 -若被测的逻辑是在线程池中执行的，且遇到`verify()`结果不正确的时候，则可能需要开启`thread.pool.enhance.enable`配置，这种情况极少见，通常无需关注。 +若需Mock的调用发生在线程池中，且遇到`verify()`结果或`MOCK_CONTEXT`内容不正确的时候，则需考虑开启`thread.pool.enhance.enable`配置，详见[Mock线程池内的调用](zh-cn/doc/with-thread-pool.md)。 diff --git a/docs/zh-cn/doc/setup.md b/docs/zh-cn/doc/setup.md index 6f2aeb9..5da6546 100644 --- a/docs/zh-cn/doc/setup.md +++ b/docs/zh-cn/doc/setup.md @@ -95,11 +95,12 @@ test { > > 完整代码可参考`demo/android-demo`示例项目。 -> 若项目使用`Spock`测试框架，需指定`Groovy`编译生成的JVM 1.6或以上版本字节码，方法如下（请根据实际使用的JVM版本修改属性值）。 +> 若项目使用`Spock`测试框架，需指定`Groovy`编译生成的JVM **1.6或以上**版本字节码，方法如下（请根据实际使用的JVM版本修改属性值）。 > > Maven项目在`pom.xml`中添加``和``属性，例如： > ```xml > +> > 1.6 > 1.6 > @@ -107,7 +108,7 @@ test { > > Gradle项目在`build.gradle`中添加`sourceCompatibility`属性，例如： > ```groovy -> sourceCompatibility = '6' +> sourceCompatibility = '6' // 或7/8/9/... > ``` > > 完整代码可参考`demo/spock-demo`示例项目。 diff --git a/docs/zh-cn/doc/with-thread-pool.md b/docs/zh-cn/doc/with-thread-pool.md new file mode 100644 index 0000000..ef65c71 --- /dev/null +++ b/docs/zh-cn/doc/with-thread-pool.md @@ -0,0 +1,52 @@ +Mock线程池内的调用 +--- + +`TestableMock`采用来自[transmittable-thread-local](https://github.com/alibaba/transmittable-thread-local)项目的`TransmittableThreadLocal`类型存储测试用例运行期的`MOCK_CONTEXT`内容和Mock方法调用过程。 + +当线程池中的执行对象未经过`TtlRunnable`或`TtlCallable`处理时，`TransmittableThreadLocal`将自动降级为与`InheritableThreadLocal`等效的类型，即只对父子线程有效，无法在线程池上下文中正常传递存储数据。因而会导致`MOCK_CONTEXT`内容丢失和`verify()`方法校验结果不正确的情况。 + +为此，可以启用[Testable全局配置](zh-cn/doc/javaagent-args.md)`thread.pool.enhance.enable=true`，来自动在测试启动时自动封装程序中的普通`Runnable`和`Callable`对象，使`TransmittableThreadLocal`恢复跨线程池存储数据的能力。 + +同时还需要配合修改项目`pom.xml`或`build.gradle`文件，将`transmittable-thread-local`中的类型增加到`TestableMock`运行的Classpath里，具体方法如下。 + +### 使用Maven构建 + +首先增加一个属性，以便将来修改该依赖的版本值： + +```xml + + 2.12.1 + +``` + +然后，在`maven-surefire-plugin`插件的`argLine`参数中添加运行参数`-Xbootclasspath/a:${settings.localRepository}/com/alibaba/transmittable-thread-local/${transmittable.thread.local.version}/transmittable-thread-local-${transmittable.thread.local.version}.jar`。 + +添加后的完整`maven-surefire-plugin`配置参考： + +```xml + + + + org.apache.maven.plugins + maven-surefire-plugin + + -Xbootclasspath/a:${settings.localRepository}/com/alibaba/transmittable-thread-local/${transmittable.thread.local.version}/transmittable-thread-local-${transmittable.thread.local.version}.jar -javaagent:${settings.localRepository}/com/alibaba/testable/testable-agent/${testable.version}/testable-agent-${testable.version}.jar + + + + +``` + +### 使用Gradle构建 + +在`test`区块内添加测试参数`jvmArgs "-Xbootclasspath/a:${classpath.find { it.name.contains("transmittable-thread-local") }.absolutePath}"` + +添加后的完整`test`区块配置参考： + +```groovy +test { + jvmArgs "-javaagent:${classpath.find { it.name.contains("testable-agent") }.absolutePath}" + jvmArgs "-Xbootclasspath/a:${classpath.find { it.name.contains("transmittable-thread-local") }.absolutePath}" + ... // 其他测试配置 +} +``` diff --git a/docs/zh-cn/sidebar.md b/docs/zh-cn/sidebar.md index 1747a41..bb47d0e 100644 --- a/docs/zh-cn/sidebar.md +++ b/docs/zh-cn/sidebar.md @@ -12,6 +12,7 @@ - [使用MockWith注解](zh-cn/doc/use-mock-with.md) - [使用包路径映射](zh-cn/doc/use-package-mapping.md) - [常见使用问题](zh-cn/doc/frequently-asked-questions.md) + - [Mock线程池内的调用](zh-cn/doc/with-thread-pool.md) - [在IDE运行单元测试](zh-cn/doc/use-in-ide.md) - [自助问题排查](zh-cn/doc/troubleshooting.md) - [使用Maven插件](zh-cn/doc/use-maven-plugin.md)