mirror of
https://github.com/alibaba/testable-mock.git
synced 2025-02-13 21:31:08 +08:00
add description of global properties configurations
This commit is contained in:
金戟
parent
d2944a88fb
commit
31140bef87
@ -35,7 +35,11 @@ Parent parent = OmniConstructor.newInstance(Parent.class);
|
||||
parent.getChild().getGrandChild().getContent();
|
||||
```
|
||||
|
||||
> **Note**: In the `0.6.0` version, the member fields of type interface or abstract class will still be initialized to `null`, this problem will be fixed in subsequent versions
|
||||
> **Note 1**: In the current version, the member fields of type interface or abstract class will still be initialized to `null`, this problem will be fixed in the future.
|
||||
>
|
||||
> **Note 2**: Based on the light-weight principle, in the default mode, `OmniConstructor` will only uses the original constructor of the class to create objects. For POJO and most model layer objects, this mode has been able to meet the needs.
|
||||
> But for more complex situations, such as when certain class have constructors throwing exceptions or contain other statements that hinder the normal execution of the construction, the object construction may fail.
|
||||
> In those situations, you can use the [Testable global configuration](en-us/doc/javaagent-args.md) `omni.constructor.enhance.enable = true` to enable bytecode enhancement mode of `OmniConstructor`, in this mode, any Java class can be constructed.
|
||||
|
||||
In addition to use as input parameters of the method under test, `OmniConstructor` can also be used to quickly construct the return value of the mock method. Compared to using `null` as the return value of the mock method, using a fully initialized object can better guarantee the reliability of the test .
|
||||
|
||||
|
||||
@ -1,12 +1,39 @@
|
||||
全局运行参数
|
||||
---
|
||||
|
||||
`TestableMock`的许多功能采用了基于JavaAgent的运行时字节码修改实现。在JavaAgent启动时，可以通过额外的全局参数来调整`TestableMock`的执行过程。
|
||||
`TestableMock`的许多功能采用了基于JavaAgent的运行时字节码修改实现。在JavaAgent启动时，可以通过两种方式调整`TestableMock`的执行过程。
|
||||
|
||||
## 1.使用全局配置文件
|
||||
|
||||
在项目的`src/test/resources`目录下创建一个名为`testable.properties`的文本文件，其中每行为一条配置项，配置项的名称与值之间用`=`连接。
|
||||
|
||||
对于大多数情况，我们更推荐使用配置文件来调节`TestableMock`的行为，这种方式相比Agent参数更加易读。
|
||||
|
||||
### 可用配置项
|
||||
|
||||
| 配置项 | 描述 | 可用值和示例（`N/A`表示无需赋值） |
|
||||
| ---- | ---- | ---- |
|
||||
| dump.path | 将修改过后的字节码保存到本地指定目录（用于排查问题） | 相对项目根目录的位置，例如：`target/bytecode` |
|
||||
| enhance.pkgPrefix.includes | 限定`TestableMock`仅对部分包生效 | 使用`,`分隔的包路径前缀列表，例如：`com.demo.svc,com.demo.dao` |
|
||||
| log.file | 指定TestableAgent日志文件位置 | 相对项目根目录的位置，例如：`target/testable/agent.log`，特殊值`null`表示禁用日志文件 |
|
||||
| log.level | 修改全局日志级别 | 可用值为：`mute`（禁止打印警告） / `debug`（打印调试信息） / `verbose`（打印非常详细的调试信息） |
|
||||
| mock.innerClass.name | 修改测试类中的内置Mock容器类名 | 任意符合Java类名的值，默认值为`Mock` |
|
||||
| mock.scope.default | 修改默认的Mock生效范围（详见[Mock生效范围](zh-cn/doc/scope-of-mock)） | 可用值为：`global`（全局生效） / `associated`（只对关联的测试用例生效） |
|
||||
| omni.constructor.enhance.enable | 是否启用`OmniConstructor`的字节码增强模式 | 可用值为：`true` / `false` |
|
||||
| omni.constructor.enhance.pkgPrefix.excludes | 对特定包禁用`OmniConstructor`的字节码增强模式 | 使用`,`分隔的包路径前缀列表，例如：`com.demo.model` |
|
||||
| thread.pool.enhance.enable | 是否启用基于`TransmittableThreadLocal`的Mock上下文存储 | 可用值为：`true` / `false` |
|
||||
|
||||
示例见`java-demo`和`kotlin-demo`项目中的`testable.properties`文件。
|
||||
|
||||
## 2.使用全局Agent参数
|
||||
|
||||
与其它基于JavaAgent的工具相似，`TestableMock`也支持通过在引入`testable-agent`包时，在末尾加上一个`=`符号，然后连接额外参数来传递用户的自定义参数。
|
||||
|
||||
### 可用参数清单
|
||||
|
||||
| 参数 | 描述 | 可用值和示例（`N/A`表示无需赋值） |
|
||||
| ---- | ---- | ---- |
|
||||
| configFile | 修改全局配置文件位置 | 相对项目根目录的位置，默认值为`src/test/resources/testable.properties` |
|
||||
| logLevel | 修改全局日志级别 | 可用值为：`mute`（禁止打印警告） / `debug`（打印调试信息） / `verbose`（打印非常详细的调试信息） |
|
||||
| logFile | 指定TestableAgent日志文件位置 | 相对项目根目录的位置，例如：`target/testable/agent.log`，特殊值`null`表示禁用日志文件 |
|
||||
| dumpPath | 将修改过后的字节码保存到本地指定目录（用于排查问题） | 相对项目根目录的位置，例如：`target/bytecode` |
|
||||
@ -26,8 +53,6 @@
|
||||
|
||||
### 添加运行参数
|
||||
|
||||
与其他基于JavaAgent的工具相似，`TestableMock`通过在单元测试引入`testable-agent`包的末尾加上一个`=`符号，然后连接额外参数来传递用户的自定义参数。
|
||||
|
||||
对于Maven项目，可将参数追加到`maven-surefire-plugin`参数`testable-agent`包尾部，紧接着`.jar`的位置。例如：
|
||||
|
||||
```xml
|
||||
@ -40,7 +65,6 @@
|
||||
|
||||
对于Gradle项目，同样是直接将参数追加到引入`testable-agent`的配置末尾。例如：
|
||||
|
||||
|
||||
```groovy
|
||||
jvmArgs "-javaagent:${classpath.find { it.name.contains("testable-agent") }.absolutePath}=mockScope=associated&pkgPrefix=com.demo"
|
||||
```
|
||||
|
||||
@ -35,7 +35,11 @@ Parent parent = OmniConstructor.newInstance(Parent.class);
|
||||
parent.getChild().getGrandChild().getContent();
|
||||
```
|
||||
|
||||
> **注意**：在`0.6.0`版本中，类型为接口或抽象类的成员字段依然会被初始化为`null`，此问题将在后续版本中修复
|
||||
> **注意 1** ：在当前版本中，类型为接口或抽象类的成员字段依然会被初始化为`null`，此问题将在后续版本修复
|
||||
>
|
||||
> **注意 2** ：基于轻量优先原则，默认模式下，`OmniConstructor`仅利用类型原有的构造方法来创建对象，对于绝大多数POJO和`Model`层对象而言这种模式已经能够满足需要。
|
||||
> 但对于更复杂的情形，譬如遇到某些类型的构造方法会抛出异常或包含其他妨碍构造正常执行的语句时，对象构造可能会失败。
|
||||
> 此时可通过[Testable全局配置](zh-cn/doc/javaagent-args.md)`omni.constructor.enhance.enable = true`启用`OmniConstructor`的字节码增强模式，在该模式下，任何Java类型皆可构造。
|
||||
|
||||
除了用于构造方法的入参，`OmniConstructor`也可以用于快速构造Mock方法的返回值，相比将`null`作为Mock方法的返回值，使用完全初始化的对象能够更好保障测试的可靠性。
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user