add with thread pool doc

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 `<maven.compiler.source>` and `<maven.compiler.target>` properties inside the `pom.xml` file, e.g.
 > ```xml
 > <properties>
+>   <!-- or 1.7/1.8/... -->
 >   <maven.compiler.source>1.6</maven.compiler.source>
 >   <maven.compiler.target>1.6</maven.compiler.target>
 > </properties>
@@ -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.

docs/en-us/doc/with-thread-pool.md

@@ -0,0 +1,4 @@
+Mock Invocation In Thread Pool
+---
+
+TO BE TRANSLATED

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)

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

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`中添加`<maven.compiler.source>`和`<maven.compiler.target>`属性，例如：
 > ```xml
 > <properties>
+>   <!-- 或 1.7/1.8/... -->
 >   <maven.compiler.source>1.6</maven.compiler.source>
 >   <maven.compiler.target>1.6</maven.compiler.target>
 > </properties>
@@ -107,7 +108,7 @@ test {
 > 
 > Gradle项目在`build.gradle`中添加`sourceCompatibility`属性，例如：
 > ```groovy
-> sourceCompatibility = '6'
+> sourceCompatibility = '6'  // 或7/8/9/...
 > ```
 > 
 > 完整代码可参考`demo/spock-demo`示例项目。

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
+<properties>
+    <transmittable.thread.local.version>2.12.1</transmittable.thread.local.version>
+</properties>
+```
+
+然后，在`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
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+                <argLine>-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</argLine>
+            </configuration>
+        </plugin>
+    </plugins>
+</build>
+```
+
+### 使用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}"
+  ... // 其他测试配置
+}
+```

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)