# nativelibs-UTSkills

**Repository Path**: HMPC2Dtest/nativelibs-utskills

## Basic Information

- **Project Name**: nativelibs-UTSkills
- **Description**: 单元测试skills，分析库的对外接口函数，对接口函数进行单元测试，覆盖接口函数的输入输出参数和异常值/边界值，输出测试用例表和单元测试代码，并对覆盖情况输出自检表。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-04-23
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NativeLibs-UT 项目

## 项目概述

本项目是一个专门用于生成鸿蒙（HarmonyOS）三方库单元测试的AI技能工具。按照HWTEST_F框架约定，为鸿蒙三方库源文件自动生成高质量的单元测试用例和测试脚本，并输出覆盖情况的自检表。
不仅适用于native三方库，对于python等三方库也可以基于该skills的规则进行单元测试，生成对应的测试脚本。

## 技能介绍

### Skill名称
`nativelibs-UT`

## 使用方法

### 重要说明

**如果三方库自带测试套，请优先使用自带的测试套进行测试**。只有当三方库没有自带测试套时，才使用本 skill 生成单元测试。

### 测试框架准备

如果需要使用 Google Test (gtest) 框架，可以通过以下命令安装：

```bash
brew install googletest
```

安装成功后即可使用 gtest 框架进行测试。

### 提示词参考

将 skill 加载到 AI agent 中，使用以下提示词：

```
请执行这个安装命令：curl -fsSL https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs/releases/download/pkgs/install.sh | sh -s -- argon2 20190702
 安装成功后,请使用nativelibs-ut skill对该三方库进行单元测试，生成单元测试用例和测试脚本，覆盖全部的接口函数，包括输入输出参数和异常值/边界值的覆盖，输出测试用例表格和自检表。然后完成相关的测试，输出xlsx格式的测试报告。注意，测试fail的，报错的，不要屏蔽，在测试结果中返回失败及报错信息。
```

### 调用步骤

1. 在AI agent中调用技能 `@skill nativelibs-UT`
2. 指定需要测试的三方库或源文件
3. AI会自动分析代码并生成测试用例
4. 执行测试脚本，自动修复脚本错误（但不屏蔽测试失败）
5. 输出包括：
   - 测试用例表格（xlsx格式）
   - 测试源代码文件
   - 测试执行脚本
   - 接口覆盖自检表（xlsx格式）
   - BUILD.gn配置文件
   - 测试报告（xlsx格式）

### 核心功能

- **自动测试生成**：为正常/异常/边界场景创建测试用例
- **Mock对象支持**：自动创建Mock类并配置EXPECT_CALL/ON_CALL
- **BUILD.gn配置**：自动匹配源文件依赖关系
- **覆盖率优化**：确保100%的分支和行覆盖率
- **代码风格一致性**：与现有测试模式保持一致（≥70%阈值）
- **NDK/NAPI支持**：针对NDK接口（7088+ OH_xxx）和NAPI函数（302+ napi_xxx）的特殊处理
- **CJSON测试**：完整支持CJSON库的测试模式
- **测试执行与报告**：自动执行测试脚本并生成xlsx格式测试报告

### 支持场景

1. **单元测试**：为源文件中的所有函数生成测试
2. **特定函数测试**：只为特定函数生成测试
3. **测试文件扩展**：向现有测试文件追加新的测试用例
4. **Mock生成**：自动为依赖项创建Mock类

## 实现说明

### 目录结构

```
nativelibs-UTSkills/
├── SKILL.md                    # 技能定义文件
├── README.md                   # 项目说明文档
├── 提示词参考                  # 提示词示例
├── examples/                   # 示例代码
│   ├── basic-test-example.cpp  # 基本测试示例
│   ├── mock-test-example.cpp   # Mock使用示例
│   ├── ndk-test-example.cpp    # NDK接口测试示例
│   ├── argon2-test-example.cpp # Argon2密码哈希库测试示例
│   ├── argon2-test-script.sh   # Argon2测试执行脚本示例
│   └── argon2-report-generator.py # Argon2测试报告生成脚本示例
└── references/                 # 规范文档
    ├── framework-specs.md      # HWTEST_F框架规范
    ├── mock-strategies.md      # Mock策略文档
    ├── coverage-requirements.md # 覆盖率要求
    ├── build-gn-rules.md       # BUILD.gn规则
    ├── assertion-standards.md  # 断言标准
    ├── code-style-consistency.md # 代码风格一致性
    ├── smart-pointer-usage.md  # 智能指针使用
    ├── ndk-napi-testing.md     # NDK/NAPI测试
    ├── cjson-testing.md        # CJSON测试
    └── security-coding.md      # 安全编码
```

### 工作流程

#### Step 1: 分析待测代码
- 识别函数的所有输入参数及其类型
- 识别函数的返回值类型
- 识别函数内部的分支逻辑和依赖
- 读取目标函数/类及其依赖

#### Step 2: 设计测试用例
基于等价类划分和边界值分析法，新建libstest目录，输出xlsx格式的测试用例，文件名称格式`libcase-【库名】-【版本号】`，表头包含测试用例编号，测试用例描述，涉及的接口函数，输入参数，预期输出，测试类型。覆盖以下场景：

| 用例类型 | 覆盖内容 | 最少数量 |
|---------|---------|---------|
| 正常路径 | 函数设计场景下的典型输入 | 1-2个 |
| 边界条件 | 空值、零值、最大/最小值、数组首尾 | 2-3个 |
| 异常路径 | 无效输入、依赖失败、超时 | 2-3个 |
| 并发场景 | 如有状态，考虑竞态 | 按需 |

#### Step 3: 生成测试代码
- 使用HWTEST_F框架创建测试文件，在libstest目录下，与被测试文件保持一致的文件名，后缀为_test.cpp
- 注意测试如果使用google test（gtest），请先使用brew命令安装 `brew install googletest`
- 遵循AAA模式：Arrange（准备）、Act（执行）、Assert（断言）
- 每个测试用例独立，不依赖执行顺序
- Mock外部依赖，不发起真实网络请求
- 不要依赖未鸿蒙化的三方库或编译工具对其进行测试，是否鸿蒙化可以在此网页查询并安装 https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs
如果测试依赖的三方库或工具没有鸿蒙化，请考虑其它方案
- 生成测试脚本，包含所有测试用例的执行顺序和依赖关系；测试脚本的执行说明,测试脚本将测试结果保存在当前目录下的test_execution.log文件。注意，鸿蒙当前支持的zsh脚本。
- 如果三方库是python三方库，可以不用生成cpp文件，可以直接生成可在终端命令行运行的zsh脚本或python脚本，但规范可以同样适用。Python 三方库的源码版本获取、依赖与 C 库预装、测试资源预下载、鸿蒙临时目录适配、跨平台失败用例判定，须额外遵循下文「Python 三方库测试规范」小节。

#### Step 4: 测试脚本执行
- 使用脚本执行上述步骤生成的测试代码，如果出现运行脚本或测试执行导致的错误可自动修复
- **重要：测试用例本身fail报错的，不要屏蔽，在测试结果中返回失败及报错信息**
- **禁止修改库的源码，或屏蔽测试用例**
- Python 三方库失败用例的跨平台复跑判定、社区 issue 查询、平台特有用例 SKIP 处理，须遵循下文「Python 三方库测试规范 > 5. 跨平台用例处理与失败结果判定」
- 测试完成后，基于测试用例表格生成测试报告（测试条目与测试用例一致，表头：测试用例编号、测试用例描述、涉及的接口函数、输入参数、预期输出、测试类型、测试结果、测试分析说明）
- 测试报告表头要带上被测三方库的名称，版本，测试系统的版本信息，测试时间

#### Step 5: 质量自查
- 每个用例是否有明确的预期结果？
- 测试命名是否清晰描述场景？
- 是否有冗余的测试用例？

### 测试覆盖要求

| 用例类型 | 覆盖内容 | 最少数量 |
|---------|---------|---------|
| 正常路径 | 函数设计场景下的典型输入 | 1-2个 |
| 边界条件 | 空值、零值、最大/最小值、数组首尾 | 2-3个 |
| 异常路径 | 无效输入、依赖失败、超时 | 2-3个 |
| 并发场景 | 如有状态，考虑竞态 | 按需 |

### Python 三方库测试规范

针对 Python 三方库的单元测试，除遵循通用工作流程外，还需遵循以下专项规范（详见 SKILL.md 同名小节）。

1. **源码与版本获取**：从 [PyPI](https://pypi.org) 获取与被测版本完全一致的源码（sdist），`pip3 download <库名>==<版本号> --no-binary :all: -d ./sources`，或访问 `https://pypi.org/project/<库名>/<版本号>/` 下载 tarball，禁止用本地不匹配版本生成用例。
2. **依赖安装顺序**：
   - Python 依赖优先 `pip3 install <依赖>`，其次从 PyPI 下载源码包本地 `pip3 install ./<包>.tar.gz`。
   - 若依赖独立 C 库，提前 `conan download <库名>/<版本号> -r=openharmonypcdeveloper-conan` 安装鸿蒙化 C 库，并配置头文件/库文件路径。
   - 依赖须在测试前全部装好，校验 `python3 -c "import <库名>"` 通过。
3. **测试资源预下载**：fixtures、样例数据等资源常在 GitHub Release 或仓库 `test/data` 目录，须在执行前下载到本地，禁止测试运行时实时拉取；路径用相对路径。
4. **鸿蒙临时目录适配**：鸿蒙存在临时目录权限问题，pytest 须加 `--basetemp=./tmp_test`，脚本执行前 `mkdir -p ./tmp_test`。
5. **跨平台失败用例判定**（仅标记不屏蔽）：

   | 失败类型 | 处理方式 |
   |---------|---------|
   | 鸿蒙未通过且 Mac/Windows 同样未通过 | 仅标记，不作为有效问题 |
   | 社区已有 issue 说明不通过 | 仅标记，不作为有效问题，附 issue 链接 |
   | Windows/macOS/Linux 平台特有用例 | 标记并 `SKIP` 跳过，注明原因 |

   跳过用例在 `test_execution.csv` 以 `SKIP` 记录；失败用例须查询官方仓库 issue 并在报告注明结果。

### 核心规范

- **HWTEST_F框架**：使用标准测试夹具和宏定义
- **覆盖率**：最低100%的分支和行覆盖率
- **Mock使用**：创建Mock必须配合EXPECT_CALL/ON_CALL使用
- **安全编码**：内存管理、变量初始化、边界检查、空指针检查

### 输出格式

- 按文件组织测试代码，与源码目录结构保持一致
- 为每个测试用例添加简短中文注释说明测试意图
- 如涉及Mock，使用项目已有的Mock库和风格
- 最后输出一个接口测试自检表，xlsx格式，表头包含库的所有接口函数/对应的测试用例编号/覆盖类型/是否已有用例覆盖，对于未覆盖的接口标注标注原因。最后统计总覆盖率（已覆盖数/总接口数）

### 禁止行为

| 禁止行为 | 说明 |
|---------|---------|
| 删除/跳过失败测试 | 禁止 @Disabled、@Ignore、删除测试方法 |
| 注释掉断言 | 禁止注释或移除 assert* 语句 |
| 降低断言强度 | 禁止 assertEquals → assertNotNull |
| 篡改期望值 | 业务应返回 5 实际返回 3，禁止把期望改成 3 |
| 加 try-catch 吞异常 | 为让测试不抛异常而包裹 catch |
| 修改库源码 | 禁止修改三方库的源代码 |
| 屏蔽测试用例 | 禁止屏蔽或跳过失败的测试用例 |
| 静默跳过平台用例 | Python 平台特有用例 SKIP 须注明原因，禁止无记录跳过 |
| 使用不匹配版本源码 | Python 三方库须从 PyPI 获取与被测版本一致的源码 |

---

# 测试示例

## 1. Native库 Argon2密码哈希库单元测试

### 库概述

Argon2是密码哈希竞赛（PHC）的获胜者，是一个现代、安全的密码哈希算法。该库提供三种变体：
- **Argon2d**：最大化抵抗GPU破解攻击
- **Argon2i**：最大化抵抗侧信道攻击
- **Argon2id**：混合模式，兼顾两者优势

### 测试方法

#### 1.1 分析待测接口

Argon2库共有21个公开接口函数，按功能分类：

| 类别 | 接口函数 |
|------|---------|
| 哈希编码 | argon2i_hash_encoded, argon2d_hash_encoded, argon2id_hash_encoded |
| 原始哈希 | argon2i_hash_raw, argon2d_hash_raw, argon2id_hash_raw |
| 验证功能 | argon2i_verify, argon2d_verify, argon2id_verify |
| 上下文操作 | argon2i_ctx, argon2d_ctx, argon2id_ctx, argon2_ctx |
| 上下文验证 | argon2i_verify_ctx, argon2d_verify_ctx, argon2id_verify_ctx, argon2_verify_ctx |
| 通用函数 | argon2_hash, argon2_verify, argon2_verify_ctx |
| 辅助函数 | argon2_type2string, argon2_error_message, argon2_encodedlen |

#### 1.2 设计测试用例

基于等价类划分和边界值分析，设计80个测试用例：

- **正常路径**：覆盖典型使用场景（密码哈希、验证成功）
- **异常路径**：验证失败、无效参数、指针不匹配
- **边界条件**：输出长度最小值、盐值最小长度、内存/时间成本边界、空密码、长密码

#### 1.3 生成测试代码

使用C++编写测试代码，遵循HWTEST_F框架风格：

```cpp
// 测试夹具结构
class Argon2Test : public testing::Test {
public:
    static void SetUpTestCase(void);
    static void TearDownTestCase(void);
    void SetUp() override;
    void TearDown() override;
};

// 测试用例格式示例
HWTEST_F(Argon2Test, HashEncoded_001, TestSize.Level1) {
    // Arrange - 准备测试数据
    const char* password = "password";
    const char* salt = "somesalt12345678";
    
    // Act - 执行测试
    int ret = argon2i_hash_encoded(2, 64, 1, password, 8, salt, 16, 32, encoded, encodedlen);
    
    // Assert - 断言验证
    EXPECT_EQ(ret, ARGON2_OK);
}
```

#### 1.4 执行测试脚本

测试脚本执行流程：

```zsh
# 1. 检查依赖库
# 2. 编译测试程序 (clang++ -std=c++11)
# 3. 执行测试
# 4. 生成CSV格式测试报告
# 5. 生成xlsx格式测试报告
# 6. 输出测试统计
```

#### 1.5 生成测试报告

xlsx测试报告包含：

| 表头 | 内容 |
|------|------|
| 被测库信息 | argon2, 版本20190702, 测试系统信息 |
| 测试统计 | 总测试数73, 通过数71, 失败数2, 通过率97.26% |
| 测试用例详情 | 编号、描述、接口函数、输入参数、预期输出、类型、结果、分析说明 |

### 测试结果示例

| 指标 | 数值 |
|------|------|
| **总测试数** | 73 |
| **通过数** | 71 |
| **失败数** | 2 |
| **通过率** | 97.26% |
| **接口覆盖率** | 100% (21/21) |

### 发现的问题

| 测试编号 | 函数 | 问题描述 |
|----------|------|----------|
| TC_029 | argon2_error_message | 返回"OK"而非"Success"，不影响功能 |
| TC_039 | argon2i_hash_raw | 未检测NULL输出指针，潜在安全隐患 |

### 文件说明

Argon2单元测试位于测试工程目录下：

```
argon2_test/
├── include/argon2.h           # 头文件
├── lib/libargon2.so           # 动态库
├── test/
│   ├── argon2_test.cpp        # 测试代码
│   ├── run_argon2_test.sh     # 测试执行脚本
│   ├── generate_report.py     # 报告生成脚本
│   ├── libcase-argon2-20190702.csv # 测试用例表格
│   └── interface_coverage_checklist.csv # 接口覆盖自检表
└── test_output/
    ├── test_report.csv        # CSV测试报告
    └── argon2_test_report.xlsx # xlsx测试报告
```

### 快速开始

```bash
# 安装argon2三方库
curl -fsSL https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs/releases/download/pkgs/install.sh | sh -s -- argon2 20190702

# 进入测试目录
cd argon2_test/test

# 执行测试脚本
bash run_argon2_test.sh

# 查看测试报告
# - test_output/test_report.csv
# - test_output/argon2_test_report.xlsx
```

### 测试特点

- **100%接口覆盖**：所有21个公开API均有测试用例
- **边界条件全覆盖**：参数最小值、最大值、空值等边界场景
- **异常路径验证**：错误密码验证、无效参数、指针不匹配
- **真实结果呈现**：失败测试不屏蔽，显示真实错误信息
- **xlsx格式报告**：包含库信息、系统信息、测试时间、详细分析

---

## 2. Python库 Pandas单元测试

### 项目统计

| 项目 | 数值 |
|------|------|
| **AI新增生成的代码行数累计** | 1240 |
| **项目新增代码行数累计（不含so等二进制）** | 1240 |
| **AI占比** | 100% |
| **本次新增AI代码行数时间** | 2026-04-23 |

### 文件说明

Pandas单元测试位于 `pandastest/` 目录下：

- `test_pandas.py` - 主测试文件，包含8个测试类，79个测试方法
- `run_tests.py` - 测试运行脚本，提供详细报告
- `test_cases.xlsx` - 120+测试用例表格
- `interface_checklist.xlsx` - 50+接口函数覆盖自检表
- `README.md` - 使用说明文档
- `项目统计.md` - 详细统计文档

### 快速开始

```bash
# 进入pandas测试目录
cd pandastest

# 安装依赖
pip install pandas numpy

# 运行测试（推荐方式）
python run_tests.py

# 或直接运行主测试文件
python test_pandas.py
```

### 测试覆盖

- **接口函数覆盖率**：100% (50+接口)
- **测试用例数**：120+
- **测试方法数**：79
- **测试类型**：正常路径、边界条件、异常路径

---

## 变更记录

### 2026-07-15 17:38 — Skill 文档优化（Python 三方库测试规范）

- 优化内容：在 SKILL.md 与 README.md 新增「Python 三方库测试规范」小节，覆盖 PyPI 源码版本获取、依赖与 C 库（conan）预装、测试资源预下载、鸿蒙 `--basetemp` 临时目录适配、跨平台失败用例分级判定（跨平台同样失败/社区已知 issue 仅标记、平台特有用例 SKIP）。
- 本次为文档优化，无新增代码（无 `//created by AI` 代码块）。

AI新增生成的代码行数累计：1240
项目新增代码行数累计（不含so等二进制）:1240
AI占比:100%
本次新增AI代码行数：0（2026-07-15 17:38，文档优化无代码生成）