# haptest

> HapTest is an OpenHarmony application UI automated testing framework.

Latest version **0.2.3** (published 2026-01-30) · Apache License, Version 2.0 license · 0 weekly downloads

## Install

```sh
npm install haptest
pnpm add haptest
yarn add haptest
bun add haptest
```

Provides the command `haptest`.

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.3 |
| Published | 2026-01-30 |
| First published | 2024-07-27 |
| Weekly downloads | 0 |
| License | Apache License, Version 2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 16 |
| Unpacked size | 2.4 MB |
| Known vulnerabilities | 0 (+8 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | code-sunbo |

## Links

- npm: https://www.npmjs.com/package/haptest
- npm.io page: https://npm.io/package/haptest

## Dependencies (16)

- [ws](https://npm.io/package/ws.md) ^8.18.0
- [bjc](https://npm.io/package/bjc.md) ^1.0.22
- [log4js](https://npm.io/package/log4js.md) ^6.9.1
- [moment](https://npm.io/package/moment.md) ^2.30.1
- [openai](https://npm.io/package/openai.md) ^5.12.2
- [adm-zip](https://npm.io/package/adm-zip.md) ^0.5.15
- [express](https://npm.io/package/express.md) ^4.19.2
- [@types/ws](https://npm.io/package/@types/ws.md) ^8.5.12
- [commander](https://npm.io/package/commander.md) ^12.1.0
- [graphology](https://npm.io/package/graphology.md) ^0.25.4
- [image-hash](https://npm.io/package/image-hash.md) ^5.3.2
- [ts-graphviz](https://npm.io/package/ts-graphviz.md) ^2.1.2
- [promise-socket](https://npm.io/package/promise-socket.md) 7.0.0
- [class-transformer](https://npm.io/package/class-transformer.md) ^0.5.1
- [@ts-graphviz/adapter](https://npm.io/package/@ts-graphviz/adapter.md) ^2.0.3
- [graphology-shortest-path](https://npm.io/package/graphology-shortest-path.md) ^2.1.0

## Recent versions

- 0.2.3 (latest) — 2026-01-30
- 0.2.2 — 2025-12-23
- 0.2.1 — 2025-12-05
- 0.2.0 — 2025-08-20
- 0.1.9 — 2025-04-22
- 0.1.8 — 2025-04-17
- 0.1.7 — 2025-01-02
- 0.1.6 — 2024-11-13
- 0.1.5 — 2024-11-08
- 0.1.4 — 2024-11-08
- 0.1.3 — 2024-08-14
- 0.1.2 — 2024-07-30
- 0.1.1 — 2024-07-27
- 0.1.0 — 2024-07-27

## README

# HapTest

## Description
HapTest is an OpenHarmony application UI automated testing framework. It supports a variety of testing strategies and can effectively automate UI testing, thereby improving the stability and quality of applications.

## Installation
```
npm install haptest
```

## Build
Install dependencies
```
npm i
```
Build & Pack
```
npm run build
npm pack
```

## Static Analysis Setup
If you want to use the static analysis module (```--policy static_guided```), you need to install its dependencies first:
```
cd static/test-demo
npm install
```

## Instructions

### 1. Usage 
```
haptest [options]

Options:
  -V, --version                              output the version number
  -i, --hap <file/bundleName/sourceRoot>     HAP bundle name or HAP file path or HAP project source root
  -o, --output <dir>                         output dir (default: "out")
  --policy <policyName>                      policy name (default: "manu")
  -t, --target [connectkey]                  hdc connectkey
  -c, --coverage                             enable coverage (default: false)
  --llm                                      enable LLM-guided exploration (default: false)
  --simk <number>                            set similarity threshold K for tarpit detection (default: 3)
  --staticConfig <file>                      path to static analysis configuration file (required when policy=static_guided)
  -h, --help                                 display help for command

```

#### Note:
- ```--policy static_guided:``` Enable the static-analysis-guided exploration policy (requires ```--staticConfig``` to specify the static module configuration file).
-``` --llm:``` Enable the LLM-based enhanced exploration module; can be combined with static_guided policy for a hybrid strategy.
- ```--simk:``` Set the UI similarity threshold for tarpit detection.

### 2. Using DevEco simulator to run HAP  

1.  download DevEco: https://developer.huawei.com/consumer/cn/deveco-studio/  
2.  Refer to the link to run the emulator: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-run-emulator-0000001582636200-V5
3.  test HAP photos
```
haptest -i com.huawei.hmos.photos -o out
```

### 3. Build & Test your Hap Build Hap & Instrument coverage
1. download Command Line Tools: https://developer.huawei.com/consumer/cn/download/
2. add ${command-line-tools}/bin to PATH
3. using haptest cmd to build instrument and test your Hap. 
```
haptest -i {Hap project root } --policy greedy_dfs -o out
```

### 4. Run Hap & dump mem
```
haptest --policy perf_start_hap -i ALL --exclude com.huawei.* com.ohos.* -o out
```

### 5. Run with static analysis and LLM enabled
```
haptest -i com.example.demo --policy static_guided --staticConfig config.json --llm --simk 3 -o out
```

### 6. Inspect UI hierarchy with the web viewer
1. Ensure your HarmonyOS device or emulator is reachable through `hdc`.
2. Start the UI viewer service (all arguments are optional unless you need to force a specific target):
   ```
   haptest ui-viewer
   ```
   - `--target`: optional connect key when multiple devices are attached; the service auto-detects when omitted.
   - `-p`: HTTP port for the local Express server (default `7789`).
   - `-o`: output directory for session artifacts.
3. Browse to `http://localhost:7789/ui-viewer`.
4. Click **Connect Device** to let the backend auto-detect the connected device. Once connected, click **Fetch Current Page** to capture the latest screenshot and hierarchy for the active foreground app.
5. Explore the hierarchy tree, inspect widget metadata, or copy XPath snippets as needed. Use **Fetch Current Page** again any time you want to refresh the view.
6. Press `Ctrl+C` in the terminal to stop the service when finished.

## Contribution

1.  Fork the repository
2.  Create Feat_xxx branch
3.  Commit your code
4.  Create Pull Request

---
_Source: https://npm.io/package/haptest · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
