everything-claude-code/rules/arkts/testing.md

paths

paths
**/*.ets **/*.ts **/ohosTest/**

HarmonyOS / ArkTS Testing

This file extends common/testing.md with HarmonyOS-specific testing practices.

Test Framework

HarmonyOS uses the built-in test framework with @ohos.test capabilities:

• Unit tests: Located in src/ohosTest/ets/test/
• UI tests: Use @ohos.UiTest for component testing
• Instrument tests: Run on device/emulator

Test Directory Structure

module/
  |-- src/
  |   |-- main/ets/          # Production code
  |   |-- ohosTest/ets/      # Test code
  |       |-- test/
  |       |   |-- Ability.test.ets
  |       |   |-- List.test.ets
  |       |-- TestAbility.ets
  |       |-- TestRunner.ets

Running Tests

# Run all tests for a module
hvigorw testHap -p product=default

# Run tests on connected device
hdc shell aa test -b com.example.app -m entry_test -s unittest /ets/TestRunner/OpenHarmonyTestRunner

Unit Test Example

import { describe, it, expect } from '@ohos/hypium';

export default function UserViewModelTest() {
  describe('UserViewModel', () => {
    it('should_initialize_with_empty_state', 0, () => {
      const vm = new UserViewModel();
      expect(vm.userName).assertEqual('');
      expect(vm.isLoading).assertFalse();
    });

    it('should_update_user_name', 0, () => {
      const vm = new UserViewModel();
      vm.updateUserName('Alice');
      expect(vm.userName).assertEqual('Alice');
    });

    it('should_handle_empty_input', 0, () => {
      const vm = new UserViewModel();
      vm.updateUserName('');
      expect(vm.userName).assertEqual('');
      expect(vm.hasError).assertFalse();
    });
  });
}

UI Test Example

import { describe, it, expect } from '@ohos/hypium';
import { Driver, ON } from '@ohos.UiTest';

export default function HomePageUITest() {
  describe('HomePage_UI', () => {
    it('should_display_title', 0, async () => {
      const driver = Driver.create();
      await driver.delayMs(1000);

      const title = await driver.findComponent(ON.text('Home'));
      expect(title !== null).assertTrue();
    });

    it('should_navigate_to_detail_on_click', 0, async () => {
      const driver = Driver.create();
      const button = await driver.findComponent(ON.id('detailButton'));
      await button.click();
      await driver.delayMs(500);

      const detailTitle = await driver.findComponent(ON.text('Detail'));
      expect(detailTitle !== null).assertTrue();
    });
  });
}

TDD Workflow for HarmonyOS

Follow the standard TDD cycle adapted for HarmonyOS:

1. RED: Write a failing test in ohosTest/ets/test/
2. GREEN: Implement minimal code in main/ets/ to pass
3. REFACTOR: Clean up while keeping tests green
4. BUILD: Run hvigorw assembleHap to verify compilation
5. VERIFY: Run tests on device/emulator

Test Coverage Requirements

• Minimum 80% coverage for all critical application code (ViewModels, services, utilities)
• Unit tests: All utility functions, ViewModel logic, data models
• Integration tests: API calls, database operations, cross-module interactions
• E2E / UI tests: Critical user flows (login, navigation, data submission)
• Test edge cases: empty data, network errors, permission denials

Testing Best Practices

• Keep tests independent - no shared mutable state between tests
• Mock network calls and system APIs in unit tests
• Use meaningful test names: should_[expected_behavior]_when_[condition]
• Test V2 state management reactivity: verify @Trace properties trigger UI updates
• Test Navigation flows: verify NavPathStack push/pop/replace operations
• Avoid testing framework internals - focus on business logic and user-visible behavior