Rust智能合约养成日记：编写Rust智能合约单元测试用例

2024.07.21 BlockSec

    往期回顾： Rust 智能合约养成日记（1）合约状态数据定义与方法实现
    在上一期 BlockSec 针对 Rust 智能合约开发的文章中，我们介绍了如何为合约 StatusMessage 定义合约状态，并为该合约实现了不同的方法。本期我们将继续基于该合约展开叙述，详细介绍编写单元测试用例的方法，并在本地进行合约的测试。
    1. 准备单元测试环境
    为编写单元测试，首先我们需要在 src/lib.rs 中加入如下代码，对单元测试进行环境设置：

1?#[cfg(not(target_arch = "wasm32"))]
    2?#[cfg(test)]
    3?mod?tests?{
    4?? ??use?super::*;
    5?? ??use?near_sdk::MockedBlockchain;
    6?? ??use?near_sdk::{testing_env,?VMContext};
    7
    8?? ? ...
    9}
    ?

    在上述代码的第 1-3 行中，我们为 StatusMessage 添加了 tests 子模块 (使用 mod 关键字声明该新模块)，并在该模块的代码片段之前标注了 cfg 属性宏 #[cfg(test)]。此外，由于 Rust 的本地单元测试无需获得 Wasm 代码，因此可为该测试模块配置 Rust 编译条件 #[cfg(not(target_arch = "wasm32"))]。
    代码第 4-6 行从 near_sdk （NEAR 的软件开发工具包）中导入了合约测试环境的相关依赖项。具体观察代码的每一行中，use 关键词的用法类似于 python 语言代码在导入其他所依赖的模块时所使用的 import。use 声明可创建一个或多个与其他路径同义的局部名称绑定，即通常可使用 use 关键词来声明引用模块项所需的路径，且这些声明通常可能出现在 Rust 模块或代码块的顶部。
    在第 4 行中，super 关键字可用于从当前模块访问父模块 StatusMessage，使得能够访问父模块中所定义的功能与方法，如之前我们为 StatusMessage 合约所定义的方法函数 set_status 与 get_status。第 5 行使用 use 关键词引用了 nearsdk 所提供的模拟区块链 MockedBlockchain 支持模块，可用于智能合约的测试。第 6 行则从 nearsdk 引入了合约测试执行的环境，以及有关测试环境上下文信息格式的支持。
    在导入支持 NEAR 智能合约单元测试所需的外部依赖模块后，我们还需要在测试模块中定义如下函数 get_context()，用于配置并返回测试环境中所需使用的上下文信息：VMContext。

1?? ??fn?get_default_context(view_call:?bool)?->?VMContext?{
    2?? ? ? ??VMContext?{
    3?? ? ? ? ? ??current_account_id:?"alice_near".to_string(),
    4?? ? ? ? ? ??signer_account_id:?"bob_near".to_string(),
    5?? ? ? ? ? ??signer_account_pk:?vec!,
    6?? ? ? ? ? ??predecessor_account_id:?"carol_near".to_string(),
    7?? ? ? ? ? ??input:?vec!,
    8?? ? ? ? ? ??block_index:?0,
    9?? ? ? ? ? ??block_timestamp:?0,
    10?? ? ? ? ? ?account_balance:?0,
    11?? ? ? ? ? ?account_locked_balance:?0,
    12?? ? ? ? ? ?storage_usage:?0,
    13?? ? ? ? ? ?attached_deposit:?0,
    14?? ? ? ? ? ?prepaid_gas:?10u64.pow(18),
    15?? ? ? ? ? ?random_seed:?vec!,
    16?? ? ? ? ? ?is_view:?view_call，
    17?? ? ? ? ? ?output_data_receivers:?vec!,
    18?? ? ? ? ? ?epoch_height:?0,
    19?? ? ? }
    20?? }
    ?

    VMContext 设定了多个模拟的，合约用户账户信息，以及包括区块高度，区块时间戳，合约存储用量等在内的区块链底层相关的上下文配置信息。
    下面首先对 VMContext 中几处关键的属性配置加以说明：
    current_account_id: 执行当前合约的帐户。
    signer_account_id: 触发当前合约函数调用执行的交易签名者。所有的合约调用都是某个交易的结果，且该交易由某个帐户使用其访问密钥 (Access Key) 签署，该账户即为 signer_account_id。
    signer_account_pk: 交易签名者所使用的 Access Key 公钥 (Public Key)。
    predecessor_account_id: 当合约的执行属于跨合约调用或回调时，该属性指代了该调用的发起者帐户。而当进行单一的合约内部函数调用时，该值将与 signer_account_id 一致。
    prepaid_gas: 在区块链中执行合约时存在一个特点，即用户需要支付一定的交易执行费用 (gas fee)。这里的 prepaid_gas 设定了可供当前交易合约函数调用时所能扣除的 Gas 最大值，并附加到当前的合约调用中。
    is_view: 该参数 is_view(类型为 bool) 可设置合约函数的调用能否对合约的状态数据进行修改。若该值为 ture，则合约函数执行时，合约的状态数据是只读的。反之如果该值为 false，则合约的执行环境将允许对合约数据进行修改。
    VMContext 中其余属性的内容和用法将在后续的文章中详细展开描述。
    当执行 NEAR 合约时，程序可配合一些 NEAR SDK 所提供的相关 API 读取这些已设置的上下文信息。例如：

near_sdk::env::current_account_id()
    near_sdk::env::predecessor_account_id()
    near_sdk::env::signer_account_pk()
    near_sdk::env::input()
    near_sdk::env::predecessor_account_id()
    ?

    上述 API 均可返回上下文具体属性的值，这些 API 可以使用前文所述的 use 声明导入。
    在定义完函数 get_context() 后，我们便可以在 test 模块中逐个地编写单元测试的内容了。
    2. 单元测试一
    如下是单元测试 1 的代码片段：

1?? ?#[test]
    2?? ?fn?set_get_message() {
    3?? ? ? ?let?context?=?get_default_context(false);
    4?? ? ? ?testing_env!(context);
    5?? ? ? ?let mut?contract?=?StatusMessage::default();
    6?? ? ? ?contract.set_status("hello".to_string());
    7?? ? ? ?assert_eq!(
    8?? ? ? ? ? ?"hello".to_string(),
    9?? ? ? ? ? ?contract.get_status("bob_near".to_string()).unwrap()
    10?? ? ? );
    11?? }
    ?

    现在我们对测试用例的具体写法展开描述：
    上述代码片段的第 1 行，我们为该单元测试函数标注了 #[test] 宏，表明这是该单元测试的起点。紧接着第 2 行，便是该单元测试函数 set_get_message() 的声明。
    代码的 3-10 行即该单元测试函数内部的主要测试逻辑，其中的代码实现首先将调用前面所定义的 get_context 初始化一个测试环境中所使用的上下文 context。此外值得一提的是，由于本单元测试需要向合约的状态数据中写入数据，因此需要为 get_context 设置参数，将前文所述 VMContext 中的 is_view 属性设置为 false，否则单元测试内部将引发 panic 导致测试无法通过。
    在设置得到一个合理的合约执行上下文后，代码的第 4 行将利用该上下文 VMContext，使用 testing_env! 宏 初始化一个用于智能合约交互的 MockedBlockchain 实例。代码的第 5 行将调用父模块中定义的 StatusMessage::default() 生成初始化后的合约对象 contract。
    在后续的代码中，测试会首先调用父模块 StatusMessage 所定义的 set_status 方法，在合约状态数据中保存字符串 "Hello"。随后再利用 get_status 从合约状态数据中读取该条数据，并与期望所获得内容进行对比。如果内容相互匹配，则通过该单元测试，若不匹配则会在该测试线程中触发 "assertion failed" 类型的 panic。
    有关单元测试中利用断言 assert 进行校验的写法描述如下：

assert!(expression) 宏可检验 boolean 值，当且仅当 expression 表达式所指代的内容为 true 时则通过检验；
assert_eq!(left, right) 宏常用于校验是否相等，当且仅当 left 和 right 表达式所指代的内容一致时通过校验 ;
assert_ne!(left, right) 宏常用于校验是否不同，当且仅当 left 和 right 表达式所指代的内容不同时通过校验 ;

    3. 单元测试二
    如下是单元测试 2 的代码片段：

1???#[test]
    2???fn?get_nonexistent_message() {
    3?? ? ??let?context?=?get_default_context(true);
    4?? ? ? ?testing_env!(context);
    5?? ? ? ?let?contract?=?StatusMessage::default();
    6?? ? ? ?assert_eq!(None,?contract.get_status("francis.near".to_string()));
    7?? }
    ?

    在第 6 行的测试中，assert_eq 右边的表达式利用合约方法 get_status 尝试从合约状态数据中查询 StatusMessage 合约用户 francis.near 所对应的 message 信息。但是由于代码的第 5 行仅仅初始化了整个合约的状态，因此此时的合约数据整体为空，因此其返回值将是 None。最终由于该结果符合预期，因此断言正确，可以通过该单元测试。
    4. 执行测试用例
    在编写完上述单元测试后，我们还需要在该 StatusMessage Rust 项目中配置该合约的 Cargo.toml 文件，即在该文件的 [dependencies] 小节中添加对 near-sdk 的依赖（版本号具体为 3.1.0）。

[dependencies]
    near-sdk?=?"3.1.0"
    ?

同时我们还需要在 src/lib.rs 文件的开头处导入这些来自于 near_sdk 所提供的模块或包：

use?near_sdk::borsh::{self,?BorshDeserialize,?BorshSerialize};
    use?near_sdk::collections::LookupMap;
    use?near_sdk::{env,?near_bindgen};
    ?

在配置完合约项目的依赖后，我们便可以利用 cargo 执行所有的单元测试用例。具体的命令如下：

$ cargo?test?--package?status-message
    ?

测试将返回具体的测试结果：

test result: ok.?2?passed;?0?failed;?0?ignored;?0?measured;?0?filtered out; finished?in0.00s
    ?

此外，我们还可以单独指定单元测试的运行：

$ cargo?test?--package?status-message set_get_message
    ?

同样地，我们可以获得单独测试的结果：

test result: ok.?1?passed;?0?failed;?0?ignored;?0?measured;?1?filtered out; finished?in0.00s
    ?

    本期总结和预告
    这是 BlockSec 针对 Rust 合约开发的第二期 blog，本期我们介绍了如何编写单元测试用例，以及在本地进行测试的方法。下一期我们将进一步描述如何编译合约代码生成 WASM 目标代码，并最终部署到 NEAR 测试链 (testnet) 上运行。