Sui 覆盖率技能（Sui Coverage Skill）

分析并自动提升 Sui Move 的测试覆盖率，同时集成安全分析能力。

GitHub： https://github.com/EasonC13-agent/sui-skills/tree/main/sui-coverage

前提条件

安装 Sui CLI

# macOS（推荐）
brew install sui

# 其他平台：参见官方文档
# https://docs.sui.io/guides/developer/getting-started/sui-install

验证安装：

sui --version

快速参考

# 工具所在路径（请根据你的技能安装路径调整）
SKILL_DIR=/skills/sui-coverage

# 完整工作流
cd /path/to/move/package
sui move test --coverage --trace
python3 $SKILL_DIR/analyze_source.py -m  -o coverage.md

工作流：自动提升测试覆盖率

步骤 1：运行覆盖率分析

cd 
sui move test --coverage --trace
python3 $SKILL_DIR/analyze_source.py -m  -o coverage.md

步骤 2：阅读覆盖率报告

阅读生成的 coverage.md 文件，识别以下问题：

• 🔴 未调用的函数 —— 从未被执行的函数
• 🔴 未覆盖的断言 —— assert!() 的失败路径未被测试
• 🔴 未覆盖的分支 —— if/else 分支中未被执行的路径

步骤 3：编写缺失的测试

针对每一项未覆盖内容，编写对应测试：

A. 未调用的函数

#[test]
fun test_() {
    // 初始化
    let mut ctx = tx_context::dummy();
    // 调用该未覆盖函数
    (...);
    // 断言预期行为
}

B. 断言失败路径（expect_failure）

#[test]
#[expected_failure(abort_code = )]
fun test__fails_when_() {
    let mut ctx = tx_context::dummy();
    // 构造触发断言失败的状态
    ();
}

C. 分支覆盖率（if/else）

#[test]
fun test__when_() { ... }

#[test]  
fun test__when_() { ... }

步骤 4：验证覆盖率是否提升

sui move test --coverage --trace
python3 $SKILL_DIR/analyze_source.py -m 

工具

1. analyze_source.py（主工具）

python3 $SKILL_DIR/analyze_source.py --module  [options]

选项：
  -m, --module    模块名（必需）
  -p, --path      包路径（默认：.）
  -o, --output    输出文件（例如：coverage.md）
  --json          输出 JSON 格式
  --markdown      输出 Markdown 到标准输出

2. analyze.py（LCOV 统计分析）

sui move coverage lcov
python3 $SKILL_DIR/analyze.py lcov.info -f "" -s sources/

选项：
  -f, --filter       按路径模式过滤
  -s, --source-dir   提供上下文的源码目录
  -i, --issues-only  仅显示存在问题的文件
  -j, --json         输出 JSON 格式

3. parse_bytecode.py（底层字节码解析）

sui move coverage bytecode --module  | python3 $SKILL_DIR/parse_bytecode.py

常见测试模式

测试断言失败路径

// 源码：
public fun withdraw(balance: &mut u64, amount: u64) {
    assert!(*balance >= amount, EInsufficientBalance);  // ← 此失败路径
    *balance = *balance - amount;
}

// 测试该失败路径：
#[test]
#[expected_failure(abort_code = EInsufficientBalance)]
fun test_withdraw_insufficient_balance() {
    let mut balance = 50;
    withdraw(&mut balance, 100);  // 应失败：50 < 100
}

测试所有分支路径

// 源码：
public fun classify(value: u64): u8 {
    if (value == 0) {
        0
    } else if (value < 100) {
        1
    } else {
        2
    }
}

// 所有分支的测试：
#[test]
fun test_classify_zero() {
    assert!(classify(0) == 0, 0);
}

#[test]
fun test_classify_small() {
    assert!(classify(50) == 1, 0);
}

#[test]
fun test_classify_large() {
    assert!(classify(100) == 2, 0);
}

测试对象生命周期

#[test]
fun test_full_lifecycle() {
    let mut ctx = tx_context::dummy();
    
    // 创建
    let obj = create(&mut ctx);
    assert!(get_value(&obj) == 0, 0);
    
    // 修改
    increment(&mut obj);
    assert!(get_value(&obj) == 1, 0);
    
    // 销毁
    destroy(obj);
}

错误码参考

编写 #[expected_failure] 测试时，请使用错误常量名称：

// 若模块中定义了：
const EInvalidInput: u64 = 1;
const ENotAuthorized: u64 = 2;

// 在测试中使用：
#[expected_failure(abort_code = EInvalidInput)]
fun test_invalid_input() { ... }

// 或使用模块限定名称：
#[expected_failure(abort_code = my_module::EInvalidInput)]
fun test_invalid_input() { ... }

示例：完整的自动覆盖率会话

# 1. 分析当前覆盖率
cd /path/to/my_package
sui move test --coverage --trace
python3 $SKILL_DIR/analyze_source.py -m my_module -o coverage.md

# 2. 查看缺失项
cat coverage.md
# 输出显示：
# - decrement() 未被调用
# - assert!(value > 0, EValueZero) 的失败路径未被测试

# 3. 在 sources/my_module.move 或 tests/my_module_tests.move 中添加测试
# （编写缺失的测试）

# 4. 验证覆盖率是否提升
sui move test --coverage --trace
python3 $SKILL_DIR/analyze_source.py -m my_module

# 5. 重复上述步骤直至达到 100% 覆盖率

与 Agent 工作流集成

当被要求提升测试覆盖率时，请执行以下步骤：

1. 运行分析 —— 获取当前覆盖率状态
2. 阅读源码 —— 理解模块逻辑
3. 识别缺口 —— 列出未覆盖的函数/分支/断言
4. 安全审查 —— 在编写测试过程中同步分析潜在漏洞
5. 编写测试 —— 针对每个缺口及安全边界场景编写测试
6. 报告发现 —— 记录所发现的安全问题
7. 验证结果 —— 重新运行覆盖率检查以确认改进效果

请始终提交测试改进：

git add sources/ tests/
git commit -m "Improve test coverage for "

测试过程中的安全分析

编写测试 = 理解合约逻辑 = 发现漏洞

在编写测试时，请主动关注以下几类问题：

1. 访问控制

需提出的问题：
- 哪些主体可调用该函数？
- 是否应加入所有者/管理员校验？
- 未授权用户能否篡改状态？

高危信号：
- 修改关键状态的 public 函数缺乏访问控制
- 缺失 capability/witness 模式

2. 整数溢出/下溢

需提出的问题：
- 在 u64::MAX 边界处会发生什么？
- 对 0 执行减法操作时会发生什么？
- 算术运算是否经过校验？

测试模式：
#[test]
fun test_overflow_boundary() {
    // 使用最大值进行测试
}

3. 状态篡改

需提出的问题：
- 状态是否可能处于不一致状态？
- 所有状态变更是否具备原子性？
- 局部失败是否会破坏数据完整性？

高危信号：
- 多次状态变更未提供回滚机制
- 共享对象未采用恰当的锁机制

4. 经济类攻击

需提出的问题：
- 是否存在超额提取价值的可能？
- 是否存在可被利用的舍入误差？
- 是否存在闪电贷攻击向量？

高危信号：
- 价格计算未启用滑点保护
- 对用户可控数据执行无界循环

5. 拒绝服务（DoS）

需提出的问题：
- 是否存在阻塞合法用户的可能？
- 是否存在无界操作？
- 存储空间是否可被恶意填满？

高危信号：
- 导致资源无界增长的向量
- 对外部输入数据执行循环操作

安全报告模板

分析模块时，请生成如下格式的安全报告：

## 安全分析：

### 概要
- 风险等级：[低/中/高/严重]
- 发现问题数：X

### 发现项

#### [严重程度] 问题标题
- **位置：** 第 XX 行
- **描述：** 问题具体表现
- **影响：** 可能导致的后果
- **建议修复方式：** 推荐的修复方案

### 已测试的边界场景
- [ ] 最大值处的溢出测试
- [ ] 零值处的下溢测试
- [ ] 未授权访问尝试
- [ ] 空值/空输入测试
- [ ] 重入场景测试

示例：具备安全意识的测试

// 安全考量：测试非所有者无法执行提现操作
#[test]
#[expected_failure(abort_code = ENotOwner)]
fun test_unauthorized_withdraw() {
    // 初始化：创建由 ALICE 拥有的金库
    // 执行：BOB 尝试提现
    // 预期：应因 ENotOwner 报错失败
}

// 安全考量：测试溢出防护机制
#[test]
fun test_deposit_overflow_protection() {
    // 向接近 u64::MAX 的余额中充值
    // 验证未发生溢出
}

// 安全考量：测试经济不变量
#[test]
fun test_total_supply_invariant() {
    // 在任意操作后验证：
    // sum(all_balances) == total_supply
}

融合安全分析的完整工作流

# 1. 执行覆盖率分析
sui move test --coverage --trace
python3 $SKILL_DIR/analyze_source.py -m  -o coverage.md

# 2. 编写测试的同时记录安全发现
# 在 coverage.md 同级目录下创建 SECURITY.md

# 3. 测试通过后汇总输出：
# - 覆盖率：X% → 100%
# - 发现安全问题数：N
# - 建议措施：...

相关技能

本技能属于 Sui 开发技能套件的一部分：

典型工作流：

sui-decompile → sui-move → sui-coverage → sui-agent-wallet
    研究        编写       测试与审计     构建 DApp

全部技能地址：https://github.com/EasonC13-agent/sui-skills