大家好，我是[晚风依旧似温柔]，新人一枚，欢迎大家关注~

前言

在应用开发过程中，日期计算、金额格式化、折扣转换等纯业务逻辑工具类（Utils）往往是 bug 的高发区。许多开发者习惯把这类计算逻辑直接堆砌在 ArkUI 的 @Component 页面组件中，或者写完工具类后仅靠真机运行点按界面来验证。这种方式不仅难以覆盖边界条件，还会让排查问题的成本随着项目迭代成倍增加。

本文将基于 HarmonyOS 官方单元测试框架 Hypium（@ohos/hypium），以一个典型的日期与价格计算工具类为例，从 UI 与逻辑解耦开始，完整演示如何针对正常输入、边界条件与异常场景编写高价值的单元测试，并进行覆盖率分析。

一、为什么 UI 页面不应该承担业务逻辑

在 ArkUI 开发中，视图层（View）应当只关注渲染与用户交互。如果将大量的计算逻辑直接写入 @Component 内部，会带来以下几个典型问题：

1. 测试成本高昂：想要验证一个简单的“满减折算逻辑”，不得不启动模拟器或真机，经过多次点击导航进入特定页面，效率极其低下。
2. 状态耦合严重：组件内部的状态变量（如 @State、@Prop）与计算逻辑交织在一起，导致逻辑无法单独抽取重用。
3. 边界隐患隐藏：诸如除零、极值、非法日期字符串等异常输入，很难通过手点 UI 完全覆盖，极易将隐患带入生产环境。

解决这一问题的标准做法是：将纯逻辑解耦为无状态的工具类或纯函数，并用自动化单元测试进行质量兜底。

二、HarmonyOS 测试框架 Hypium 与官方规范

HarmonyOS 提供了官方测试框架 Hypium（@ohos/hypium），用于支持 ArkTS 单元测试（UnitTest）与 UI 自动化测试（UITest）。

在针对工具类的单元测试中，我们主要使用 Hypium 的核心接口：

• describe(testSuiteName, callback)：定义一个测试套件（Test Suite）。
• it(testCaseName, testLevel, callback)：定义一个具体的测试用例（Test Case）。
• expect(actualValue)：断言工具，提供诸如 .assertEqual()、.assertTrue()、.assertNull()、.assertThrowError() 等多种匹配方法。

官方建议将测试文件放置于工程的 entry/src/test/（本地单元测试）或 entry/src/ohosTest/（端侧自动化测试）目录下。对于不依赖系统能力（System Capability / Native API）的纯逻辑工具类，优先采用本地单元测试，可在开发机上快速批量执行。

三、搭一个最小实践：纯逻辑工具类

下面设计一个常见的业务工具类 PriceCalculator，负责处理商品打折计算、优惠券抵扣以及日期范围校验。

在 entry/src/main/ets/utils/PriceCalculator.ets 中定义如下代码：

/**
 * 价格与优惠计算工具类
 */
export class PriceCalculator {
  /**
   * 计算折后最终价格
   * @param originalPrice 原价（单位：分）
   * @param discountRatio 折扣率（0 到 1 之间，例如 0.8 表示 8 折）
   * @returns 折后价格（单位：分，向下取整）
   */
  public static calculateDiscount(originalPrice: number, discountRatio: number): number {
    if (originalPrice < 0) {
      throw new RangeError('Original price cannot be negative.');
    }
    if (discountRatio < 0 || discountRatio > 1) {
      throw new RangeError('Discount ratio must be between 0 and 1.');
    }
    return Math.floor(originalPrice * discountRatio);
  }

  /**
   * 判断当前日期是否落在促销活动周期内
   * @param currentDateStr 当前日期格式 ISO 8601 (YYYY-MM-DD)
   * @param startDateStr 开始日期
   * @param endDateStr 结束日期
   */
  public static isWithinPromotionPeriod(currentDateStr: string, startDateStr: string, endDateStr: string): boolean {
    const current = Date.parse(currentDateStr);
    const start = Date.parse(startDateStr);
    const end = Date.parse(endDateStr);

    if (Number.isNaN(current) || Number.isNaN(start) || Number.isNaN(end)) {
      throw new TypeError('Invalid date string format.');
    }

    if (start > end) {
      throw new RangeError('Start date cannot be later than end date.');
    }

    return current >= start && current <= end;
  }
}

四、使用 Hypium 编写高质量单元测试

编写单元测试时，不可仅覆盖“正常跑通”的代码，必须包含 正常输入、边界输入 与 异常抛出 三个维度。

在 entry/src/test/PriceCalculator.test.ets（或对应 ohosTest 目录）中创建测试脚本：

import { describe, it, expect } from '@ohos/hypium';
import { PriceCalculator } from '../../main/ets/utils/PriceCalculator';

export default function priceCalculatorTest() {
  describe('PriceCalculatorTest', () => {

    // ----------------------------------------------------
    // 1. 正常输入测试（Normal Inputs）
    // ----------------------------------------------------
    it('calculateDiscount_normalInput_returnsCorrectPrice', 0, () => {
      // 原价 10000 分（100元），打 8 折，期望返回 8000 分
      const result = PriceCalculator.calculateDiscount(10000, 0.8);
      expect(result).assertEqual(8000);
    });

    it('isWithinPromotionPeriod_validDateInRange_returnsTrue', 0, () => {
      const isVal = PriceCalculator.isWithinPromotionPeriod(
        '2026-05-15',
        '2026-05-01',
        '2026-05-31'
      );
      expect(isVal).assertTrue();
    });

    // ----------------------------------------------------
    // 2. 边界输入测试（Boundary Inputs）
    // ----------------------------------------------------
    it('calculateDiscount_boundaryRatioZeroAndOne_returnsExpected', 0, () => {
      // 折扣率为 0（免费）
      const freeResult = PriceCalculator.calculateDiscount(5000, 0);
      expect(freeResult).assertEqual(0);

      // 折扣率为 1（不打折）
      const fullResult = PriceCalculator.calculateDiscount(5000, 1);
      expect(fullResult).assertEqual(5000);
    });

    it('isWithinPromotionPeriod_boundaryDates_returnsTrue', 0, () => {
      // 刚好等于开始日期或结束日期
      const startBoundary = PriceCalculator.isWithinPromotionPeriod('2026-05-01', '2026-05-01', '2026-05-31');
      const endBoundary = PriceCalculator.isWithinPromotionPeriod('2026-05-31', '2026-05-01', '2026-05-31');

      expect(startBoundary).assertTrue();
      expect(endBoundary).assertTrue();
    });

    // ----------------------------------------------------
    // 3. 异常输入测试（Exception Inputs）
    // ----------------------------------------------------
    it('calculateDiscount_negativePrice_throwsRangeError', 0, () => {
      expect(() => {
        PriceCalculator.calculateDiscount(-100, 0.8);
      }).assertThrowError('RangeError');
    });

    it('calculateDiscount_invalidDiscountRatio_throwsRangeError', 0, () => {
      expect(() => {
        PriceCalculator.calculateDiscount(1000, 1.5);
      }).assertThrowError('RangeError');
    });

    it('isWithinPromotionPeriod_invalidDateFormat_throwsTypeError', 0, () => {
      expect(() => {
        PriceCalculator.isWithinPromotionPeriod('invalid-date', '2026-05-01', '2026-05-31');
      }).assertThrowError('TypeError');
    });

    it('isWithinPromotionPeriod_startDateAfterEndDate_throwsRangeError', 0, () => {
      expect(() => {
        PriceCalculator.isWithinPromotionPeriod('2026-05-15', '2026-06-01', '2026-05-31');
      }).assertThrowError('RangeError');
    });

  });
}

五、批量运行与测试覆盖率分析

在 DevEco Studio 中执行测试并查看覆盖率的步骤如下：

1. 执行单元测试

右键点击测试文件或测试套件函数，选择 Run ‘PriceCalculator.test.ets’ 或通过 Run with Coverage 模式启动。

2. 测试覆盖率图表解析

单元测试的质量不能仅靠用例数量衡量，关键在于代码覆盖率（Code Coverage）。常见的统计维度包括：

+-----------------------------------------------------------------------+
|                       Code Coverage Metrics                           |
+-------------------+---------------------------------------------------+
| Metric            | Meaning                                           |
+-------------------+---------------------------------------------------+
| Statement Coverage| Percentage of executed code statements            |
| Branch Coverage   | Percentage of executed control structure branches |
| Function Coverage | Percentage of executed functions/methods          |
+-------------------+---------------------------------------------------+

通过覆盖率报告，能够直观定位到哪些 if/else 分支未被用例触及。例如，若未针对 discountRatio > 1 编写测试用例，分支覆盖率就会报告缺口，提示开发者补充相应的边界测试。

六、关键点拆解与踩坑点

1. 浮点数精度陷阱

在 ArkTS / JavaScript 中，直接进行浮点数运算可能带来精度丢失（例如 0.1 + 0.2 === 0.30000000000000004）。

• 规避方案：在涉及金额计算时，建议内部统一使用**最小货币单位（分）**作为整型进行运算，或者引入高精度计算库，避免在断言中直接使用 assertEqual 对两个浮点数进行绝对等值比较。

2. 异常断言的函数包装

使用 expect(...).assertThrowError() 断言异常时，受测试调用的函数必须被包裹在一个闭包函数中：

// 正确写法：包裹在匿名函数中
expect(() => {
  PriceCalculator.calculateDiscount(-100, 0.8);
}).assertThrowError('RangeError');

// 错误写法：直接调用会导致错误在断言捕获前抛出，引发测试奔溃
// expect(PriceCalculator.calculateDiscount(-100, 0.8)).assertThrowError('RangeError');

3. 日期解析跨平台差异

在 ArkTS 中，Date.parse() 对非标准日期格式（如 2026/05/01 或带有时区的格式）在不同运行环境下的解析行为可能存在微小差异。建议工具类内部统一约定标准 ISO 格式，或结合系统 @ohos.i18n 模块处理国际化日期。

七、实际项目中的测试排查清单

在为 HarmonyOS 项目建立工具类自动化测试体系时，可按照以下流程进行检查：

[步骤 1: 架构检查] -> 确认逻辑是否已从 UI 组件（@Component）中剥离为独立模块
       │
[步骤 2: 规范检查] -> 检查工具类方法是否为纯函数（无全局状态依赖、无隐式侧效应）
       │
[步骤 3: 用例覆盖] -> 验证测试用例是否包含：正常路径、边界值（0、最值、空值）、异常断言
       │
[步骤 4: 执行验证] -> 在 DevEco Studio 中以 Coverage 模式批量运行测试套件
       │
[步骤 5: 覆盖率核验] -> 检查分支覆盖率（Branch Coverage）是否达到团队既定指标（建议 > 85%）

八、总结

把业务逻辑从 ArkUI 视图组件中剥离，并为工具类编写严谨的单元测试，是保障 HarmonyOS 应用质量最划算的投资。利用 Hypium 框架提供的断言能力，可以极低成本地在开发阶段扑灭绝大多数隐藏缺陷，避免把简单的逻辑问题演变成难以定位的 UI 异常。

在你的实际项目中，是否也存在因 ArkUI 组件内嵌入过多计算逻辑而难以测试的痛点？欢迎在评论区分享你在鸿蒙单元测试实践中的心得或遇到过的奇葩边界问题！

参考资料

1. 《ArkTS 自动化测试框架 Hypium 使用指南》
   华为开发者联盟
   链接：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hypium-guide

2. 《ArkTS 语法与语言规范》
   华为开发者联盟
   链接：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-coding-style

3. 《DevEco Studio 单元测试与覆盖率统计说明》
   华为开发者联盟
   链接：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/deveco-unit-test

如果觉得有帮助，别忘了点个赞+关注支持一下~
喜欢记得关注，别让好内容被埋没～