update doc of test api

docs/in_depth/event.md

@@ -25,7 +25,7 @@ struct Foo {
 }
 ```
 
-被索引的参数本身不会被保存，但是Dapp应用可以通过被索引参数的值来对事件进行检索。在Liquid中，一个事件最多可有四个值用于被索引，但是第一个索引值恒定为事件签名（事件名及其参数类型）的哈希值，因此在事件定义中，您最多可以将三个参数被标注为`#[liquid(indexed)]`。
+被索引的参数本身不会被保存，但是Dapp应用可以通过被索引参数的值来对事件进行检索。在Liquid中，一个事件最多可有四个值用于被索引，但是第一个索引恒定为事件签名（事件名及其参数类型）的哈希值，因此在事件定义中，您最多可以将三个参数被标注为`#[liquid(indexed)]`。
 
 与状态变量定义类似，不能为定义事件的结构体添加可见性声明或模板参数，但和状态变量定义不同的时，其内部每个字段也不允许添加可见性声明。事件参数及索引参数的类型均受到限制，具体的限制可参考[类型](../types.html)一节。
 
@@ -55,7 +55,7 @@ self.env().emit(Foo {
 ]
 ```
 
-其中，`address`字段是合约地址；`data`字段中保存了非索引参数的[ABI编解码](https://solidity.readthedocs.io/en/v0.7.1/abi-spec.html#formal-specification-of-the-encoding)，此处因为我们只有一个非索引参数`i`，因此`data`字段中只保存了它的值42；`topics`字段包含了两个可用于索引该事件的值，其中第一个是事件签名的哈希值，而第二个值则是事件中索引参数`s`的值的哈希值。对于`String`这类动态对象，Liquid会将它们的哈希值作为索引值，以提高检索效率及减少存储空间占用。因此若您需要在应用中按照字符串检索事件，您需要在本地计算待检索字符串的哈希值。
+其中，`address`字段是合约地址；`data`字段中保存了非索引参数的[ABI编解码](https://solidity.readthedocs.io/en/v0.7.1/abi-spec.html#formal-specification-of-the-encoding)，此处因为我们只有一个非索引参数`i`，因此`data`字段中只保存了它的值42；`topics`字段包含了两个可用于索引该事件的值，其中第一个是事件签名的哈希值，而第二个值则是事件中索引参数`s`的值的哈希值。对于`String`这类动态对象，Liquid会将它们的哈希值作为事件索引，以提高检索效率及减少存储空间占用。因此若您需要在应用中按照字符串检索事件，您需要在本地计算待检索字符串的哈希值。
 
 ```eval_rst
 .. admonition:: 注意

docs/in_depth/test_api.md

@@ -0,0 +1,99 @@
+# 测试专用API
+
+Liquid的特色功能之一是能够在合约中编写单元测试。但是在单元测试中，有时除了需要对合约方法的输出、状态变量的值等进行测试，还需要测试区块链的状态，甚至需要改变区块链的状态来观察对合约方法执行逻辑的影响。Liquid提供了一组测试专用的API，使得在本地运行合约的单元测试时，您能够基于这些API获取或改变模拟区块链环境中的状态，从而对合约进行更深入一步的测试。
+
+```eval_rst
+.. admonition:: 注意
+
+   本节所述的API仅能够在单元测试中使用，请不要在合约逻辑中使用这些API，否则会引发编译报错。
+```
+
+## 使用方式
+
+使用测试专用API前，需要导入位于`liquid_core::env`模块中的`test`模块，所有的测试专用API均位于`test`模块中：
+
+```rust
+// 导入`test`模块
+use liquid_core::env::test;
+
+#[test]
+fn foo() {
+    // 在单元测试中使用测试专用API
+    let events = test::get_events();
+    // ...
+}
+```
+
+## push_execution_context
+
+- 签名：`push_execution_context(caller: Address)`
+
+- 功能：在合约的调用栈的栈顶压入一个新的合约执行环境，目前执行环境中仅包括当前合约的调用者地址。通过该API可以影响环境模块中`get_caller`接口的返回值。
+
+## pop_execution_context
+
+- 签名：`pop_execution_context()`
+
+- 功能：从合约的调用栈的栈顶弹出一个合约执行环境，需要和`push_execution_context`配合使用
+
+## default_accounts
+
+- 签名：`default_accounts() -> DefaultAccounts`
+
+- 功能：合约的测试过程中需要经常使用一些虚拟的账户地址，本API可以返回一组固定的虚拟地址，从而免去每次手工创建合约地址的麻烦，使得单元测试具有更好的可读性。返回值中`DefaultAccounts`的定义如下：
+
+  ```rust
+  pub struct DefaultAccounts {
+    pub alice: Address,
+    pub bob: Address,
+    pub charlie: Address,
+    pub david: Address,
+    pub eva: Address,
+    pub frank: Address,
+  }
+  ```
+
+  您和可以通过如下方式使用这些虚拟地址：
+
+  ```rust
+  let accounts = test::default_accounts();
+  let alice = accounts.alice;
+  // ...
+  ```
+
+## get_events
+
+- 签名：`get_events() -> Vec<Event>`
+
+- 功能：当单元测试开始运行后，本地模拟区块链环境中会维护一个事件记录器，每当合约方法触发事件时，事件记录器中会增加一条事件记录，您可以获取这些事件记录以测试您的合约方法是否触发了正确的事件。返回值中表示事件的`Event`的定义是：
+
+  ```rust
+  pub struct Event {
+    pub data: Vec<u8>,
+    pub topics: Vec<Hash>,
+  }
+  ```
+
+  其中，`data`为事件中经过编码后的数据，您可以调用`Event`的`decode_data`接口对数据进行解码，其签名为：
+
+  ```rust
+  decode_data<R>(&self) -> R
+  ```
+
+  其中泛型参数`R`是事件定义中各个非索引的字段的类型所组成的元组类型，您可以使用如下的方式调用该接口：
+
+  ```rust
+  #[liquid(event)]
+  struct foo {
+      x: u128,
+      y: bool,
+  }
+
+  // ...
+
+  let event = test::get_events()[0];
+  let (x, y) = event.decode_data<(u128, bool)>();
+  // ...
+  ```
+
+  除`data`外，`Event`中还包括一个由事件索引组成的数组`topics`。每个索引的类型为`Hash`，其内部是一个长度为32的字节数组。`Hash`类型能够方便与字节数组、字符串互相转换，其接口与[`Address`类型](./types.html#Address)类似。

index.md

@@ -25,6 +25,7 @@ Liquid是一种专用于为区块链底层平台[FISCO BCOS](https://fisco-bcos-
    docs/in_depth/types.md
    docs/in_depth/env_and_intrinsics.md
    docs/in_depth/compile_options.md
+   docs/in_depth/test_api.md
    docs/in_depth/complicated_contract.md
 
 .. toctree::