阅读时长：约 18 分钟 | 难度：★★★☆☆ | 篇章：第 1 篇 · 项目架构与设计哲学
对应源码：xuanxiang_ohos_app/oh-package.json5、entry/oh-package.json5、entry/src/ohosTest/、entry/src/test/

前言

在大型 HarmonyOS 应用中，依赖管理与测试体系是工程化质量的两块基石。玄象项目通过 OpenHarmony Package Manager（.ohpm）管理三方库依赖，并通过@ohos/hypium单元测试框架与@ohos/hamockMock 框架构建完整的测试体系。本篇将深入剖析玄象项目的 .ohpm 依赖配置与测试体系搭建方式，让您掌握在 HarmonyOS 项目中实施工业级测试驱动开发的路径。

提示：玄象项目的命理算法（八字排盘、神煞查法）、历法算法（农历转换、节气计算）涉及大量复杂逻辑，单元测试是保证算法正确性的必备手段。

一、.ohpm 依赖管理体系

1.1 .ohpm 概述

OpenHarmony Package Manager（简称 .ohpm）是 HarmonyOS 的官方包管理工具，类似 npm 之于 Node.js。

1.2 玄象项目 oh-package.json5 全貌

工程级oh-package.json5：

{ "modelVersion": "6.0.2", "description": "Please describe the basic information.", "dependencies": { }, "devDependencies": { "@ohos/hypium": "1.0.25", "@ohos/hamock": "1.0.0" } }

模块级entry/oh-package.json5：

{ "name": "entry", "version": "1.0.0", "description": "Please describe the basic information.", "main": "", "author": "", "license": "", "dependencies": {} }

1.3 字段解析

工程级oh-package.json5字段：

模块级entry/oh-package.json5字段：

1.4 依赖版本规范

玄象项目使用精确版本号：

"@ohos/hypium": "1.0.25", "@ohos/hamock": "1.0.0"

而非范围版本（如^1.0.25），原因：

1. 可复现构建：精确版本确保不同时间构建产物一致。
2. 避免隐式升级：范围版本可能引入不兼容的新版本。
3. 锁定文件保障：oh-package-lock.json5已锁定传递依赖。

提示：玄象项目若引入更多三方库（如@ohos/net-http网络请求库），应同样使用精确版本号。

二、@ohos/hypium 单元测试框架

2.1 hypium 简介

@ohos/hypium是 HarmonyOS 官方单元测试框架，特性包括：

• BDD 风格 API：describe/it/expect
• 异步测试支持：async函数测试
• 断言库：丰富的expect断言方法
• Mock 集成：与@ohos/hamock无缝协作

2.2 玄象项目测试目录结构

entry/src/ ├── main/ # 主代码 ├── ohosTest/ # 仪器化测试（在设备上运行） │ ├── ets/ │ │ └── test/ │ │ ├── Ability.test.ets │ │ └── List.test.ets │ └── module.json5 └── test/ # 单元测试（在本地 JVM 运行） ├── List.test.ets └── LocalUnit.test.ets

2.3 Ability.test.ets 示例

import{describe,it,expect}from'@ohos/hypium';import{UIAbility}from'@kit.AbilityKit';exportdefaultfunctionabilityTest(){describe('AbilityTest',()=>{it('assertContain',0,()=>{consta='abc';constb='b';expect(a).assertContain(b);});it('assertEqual',0,()=>{consta=1;constb=1;expect(a).assertEqual(b);});});}

2.4 List.test.ets 测试入口

importabilityTestfrom'./Ability.test';exportdefaultfunctiontestsuite(){abilityTest();}

2.5 hypium 核心 API

describe：测试套件

describe('MansionDataTest',()=>{// 测试用例});

it：测试用例

it('should return 28 mansions',0,()=>{constcount=MansionData.getTotalCount();expect(count).assertEqual(28);});

第二个参数0是测试用例的过滤参数，0表示不过滤。

expect：断言

hypium 提供丰富的断言方法：

2.6 异步测试

it('async test',0,async()=>{constresult=awaitsomeAsyncFunction();expect(result).assertEqual('expected');});

2.7 beforeAll / beforeEach 钩子

describe('MansionDataTest',()=>{letdata:MansionData;beforeAll(()=>{// 套件开始前执行一次data=newMansionData();});beforeEach(()=>{// 每个用例前执行data.reset();});it('test1',0,()=>{// ...});});

三、@ohos/hamock Mock 框架

3.1 hamock 简介

@ohos/hamock是 HarmonyOS 官方 Mock 框架，用于在单元测试中模拟依赖：

• Mock 类：替换被测对象的依赖
• Stub 方法：模拟方法返回值
• Spy 方法：监听方法调用

3.2 hamock 基本 Mock

import{Mock,MockKit,when}from'@ohos/hamock';@MockclassMockLunarCalendar{getTodayHeavenlyStems():string{return'甲子';}}

3.3 when-thenReturn 模式

constmockData=mock(LunarCalendar);when(mockData.getTodayHeavenlyStems()).thenReturn('甲子');// 在被测对象中使用 mockDataconstresult=mockData.getTodayHeavenlyStems();expect(result).assertEqual('甲子');

3.4 verify 验证调用

constmockData=mock(LunarCalendar);// ... 调用 mockData 的方法verify(mockData,'getTodayHeavenlyStems').called(1);

3.5 Spy 监听

constspy=spy(LunarCalendar,'getTodayHeavenlyStems');// ... 触发调用verify(spy,1).called();

四、玄象项目测试实战

4.1 历法算法测试

玄象项目的LunarCalendar.ets包含农历转换、节气计算等核心算法，应有完整的单元测试覆盖：

import{describe,it,expect}from'@ohos/hypium';import{LunarCalendar}from'../../../../main/ets/common/utils/LunarCalendar';exportdefaultfunctionlunarCalendarTest(){describe('LunarCalendarTest',()=>{// 测试农历转公历it('lunarToSolar_2024_chineseNewYear',0,()=>{constsolar=LunarCalendar.lunarToSolar(2024,1,1);expect(solar.year).assertEqual(2024);expect(solar.month).assertEqual(2);expect(solar.day).assertEqual(10);});// 测试二十四节气it('getSolarTerm_2024_lichun',0,()=>{constlichun=LunarCalendar.getSolarTerm(2024,'立春');expect(lichun.month).assertEqual(2);expect(lichun.day).assertEqual(4);});// 测试干支计算it('getHeavenlyStems_2024_jiaChen',0,()=>{constganzhi=LunarCalendar.getYearGanZhi(2024);expect(ganzhi).assertEqual('甲辰');});});}

4.2 八字命理测试

玄象项目的命理算法应有独立的测试套件：

describe('MingliAlgorithmTest',()=>{it('should calculate correct day master',0,()=>{constbazi=newBazi(1990,5,15,10,30);constdayMaster=bazi.getDayMaster();expect(dayMaster).assertEqual('庚');});it('should calculate correct ten gods',0,()=>{consttenGods=MingliAnalyzer.calculateTenGods('甲','丙');expect(tenGods).assertEqual('食神');});it('should find Tianyi nobleman correctly',0,()=>{constnobleman=ShenShaFinder.findTianyiNobleman('甲');expect(nobleman).assertContain('丑');expect(nobleman).assertContain('未');});});

4.3 卦象起卦测试

describe('HexagramDivinationTest',()=>{it('should produce valid hexagram from coins',0,()=>{constcoins=[3,3,2];// 三次铜钱正反面constyao=HexagramDivination.castYao(coins);expect(yao).assertContain('阴');// 2+3+3=8，少阴});it('should calculate changing lines correctly',0,()=>{constoriginal=[1,1,1,0,0,0];// 上乾下坤constchanged=HexagramDivination.calculateChanged(original);expect(changed.length).assertEqual(6);});});

4.4 Mock 网络请求测试

玄象项目的 AI 取名功能依赖网络请求，应通过 Mock 测试：

import{Mock,when}from'@ohos/hamock';@MockclassMockHttpClient{post(url:string,data:object):Promise<response>{returnPromise.resolve({code:200,data:{names:['玄道']}});}}describe('AiNamingServiceTest',()=>{it('should return name suggestions',0,async()=>{constmockClient=newMockHttpClient();constservice=newAiNamingService(mockClient);constresult=awaitservice.suggestNames('1990-05-15','male');expect(result.names[0]).assertEqual('玄道');});});

五、玄象项目测试覆盖规划

5.1 测试覆盖目标

5.2 测试分层策略

玄象项目采用三层测试金字塔：

E2E 测试（设备端真实测试） ↑ 集成测试（模块间协作测试） ↑ 单元测试（算法/逻辑测试）

5.3 测试运行方式

# 运行所有单元测试hvigorwtest--modemodule-pmodule=entry@default# 运行仪器化测试（需连接设备）hvigorw ohosTest--modemodule-pmodule=entry@default

六、玄象项目测试目录规划

6.1 完整测试目录结构

entry/src/ ├── test/ # 单元测试（本地运行） │ ├── utils/ │ │ ├── LunarCalendar.test.ets │ │ ├── MansionData.test.ets │ │ ├── HexagramData.test.ets │ │ └── HeavenlyStems.test.ets │ └── services/ │ ├── AiNamingService.test.ets │ └── DivinationService.test.ets └── ohosTest/ # 仪器化测试（设备运行） └── ets/test/ ├── Ability.test.ets # Ability 生命周期测试 ├── pages/ │ ├── HomePage.test.ets │ └── MansionListPage.test.ets └── ui/ # UI 交互测试 └── FeatureGrid.test.ets

6.2 测试文件命名规范

玄象项目测试文件命名规范：

• 测试文件：被测类名.test.ets，如LunarCalendar.test.ets
• 测试套件：被测类名Test，如LunarCalendarTest
• 测试用例：should_期望行为_when_前置条件，如should_return_28_mansions

提示：规范的命名让测试结果可读性更高，便于排查失败用例。

七、持续集成中的测试

7.1 CI 流水线集成

玄象项目的 CI 流水线应包含测试环节：

# .github/workflows/ci.yml (示意)jobs:test:steps:-uses:actions/checkout@v3-name:Setup HarmonyOS SDKrun:|# 安装 HarmonyOS SDK-name:Install Dependenciesrun:ohpm install-name:Run Unit Testsrun:hvigorw test--mode module-p module=entry@default-name:Run Lintrun:hvigorw codeLinter--mode module-p module=entry@default

7.2 测试覆盖率报告

# 生成覆盖率报告hvigorwtest--coverage--modemodule-pmodule=entry@default

生成的 HTML 覆盖率报告位于build/reports/coverage/。

总结

本篇以玄象项目oh-package.json5配置与测试目录结构为蓝本，系统剖析了 HarmonyOS 应用的 .ohpm 依赖管理与测试体系：从依赖版本规范、@ohos/hypium单元测试 API、@ohos/hamockMock 框架，到玄象项目历法算法、命理算法、卦象起卦的测试实战，再到测试覆盖规划、CI 集成方案。掌握这套测试驱动开发体系，是构建高质量 HarmonyOS 应用的核心能力。

下一篇：《10 · 项目目录约定：common/components/constants/utils/pages 六层架构》，将带您深入玄象项目的分层架构设计。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• HarmonyOS 官方文档：ohpm 包管理
• HarmonyOS 官方文档：@ohos/hypium 单元测试
• HarmonyOS 官方文档：@ohos/hamock Mock 框架
• HarmonyOS 官方文档：自动化测试框架使用指南
• 开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net