# Android BFS Crawl Tools

This folder contains standalone runtime UI crawl utilities for Android apps.
`android_viewtree_bfs_crawler.ts` is the crawler used by the
`hmos-test-case-generation` skill when it needs to produce Android runtime
view-tree dumps.

## `android_viewtree_bfs_crawler.ts`

`android_viewtree_bfs_crawler.ts` uses ADB + `uiautomator dump` to traverse
reachable pages, write page snapshots, and record crawl diagnostics.

Typical command:

```powershell
node .\tools\bfs-crawl\android_viewtree_bfs_crawler.ts `
  --package com.example.app `
  --device <adb-serial> `
  --output C:\path\to\bfs_output `
  --max-depth 6 `
  --max-pages 500 `
  --max-scrolls 10 `
  --skip-same-activity
```

Main outputs:

- `index.json`: committed page metadata.
- `page_*/meta.json`, `page_*/view.xml`, `page_*/screenshot.png`: per-page evidence.
- `gaps.json`: explicit coverage gaps such as input-required controls, skipped destructive actions, weak locators, and external-app blocks. This is a manual-review supplement, not part of `ui_elements.json`.
- `crawl_stats.json`: crawl counters, termination reason, and persisted learned root recovery paths with success/failure scores.
- `crawl_decisions.jsonl`: append-only decision trace for skipped, merged, or navigated queue items.

The crawler is pure script execution. It does not require an AI model.

## Convert Crawl Output To `ui_elements.json`

The mapping conversion is handled by the TCG tool:

```powershell
node .\skills\hmos-test-case-generation\tools\convert_to_ui_elements.ts `
  --dump C:\path\to\bfs_output `
  --out C:\path\to\bfs_output\ui_elements.json `
  --package com.example.app
```

`convert_to_ui_elements.ts` reads the crawler dump directly from `meta.json` and
`view.xml`. No extra parser script is required between crawler output and
`ui_elements.json`. The converter targets the common dump contract
(`page_*/meta.json` + `view.xml`) and preserves the existing `ui_elements.json`
shape. It does not consume crawler diagnostics such as `gaps.json`,
`crawl_stats.json`, or `crawl_decisions.jsonl`; treat those files as
supplementary reports for manual follow-up.

## Relationship To The TCG Skill

When `ui-elements-path` is absent but `package` or `android-project-dir` is
provided, the `hmos-test-case-generation` skill uses:

```text
tools/bfs-crawl/android_viewtree_bfs_crawler.ts
```

The skill then converts the dump with:

```text
skills/hmos-test-case-generation/tools/convert_to_ui_elements.ts
```

The crawler produces the common dump contract consumed by
`convert_to_ui_elements.ts`. Diagnostics (`gaps.json`, `crawl_stats.json`,
`crawl_decisions.jsonl`) remain supplementary reports for manual follow-up and
are not inlined into `ui_elements.json`.