@healflow/cli

Command-line interface for HealFlow — initialize projects, validate setup, view reports, and sync to cloud.

Overview

Provides the healflow binary for the Install → Run Tests → Review Fixes workflow. Works standalone in any Playwright project after npm install.

Published to npm.

Installation

npm install @healflow/cli @healflow/playwright @playwright/[email protected]

Commands

healflow init

Scaffold HealFlow in the current directory:

npx healflow init

Creates:

• healflow.yml — configuration
• healflow.fixtures.ts — auto-healing test fixtures (re-exports Playwright types)
• Patches or creates playwright.config.ts with @healflow/playwright

Init flags (Phase 8):

| Flag | Description | | -------------------------------- | ---------------------------------------------------- | | --no-codemod / --config-only | Scaffold only — no spec import changes | | --codemod-dir <path> | Rewrite imports under one directory | | --codemod-dry-run | List files that would change | | --alias | Add tsconfig paths alias to healflow.fixtures.ts |

By default, init codemods specs under Playwright testDir values discovered from playwright.config.* (root + projects[].testDir).

Large suites — config-only rollout:

npx healflow init --config-only
# opt in one folder later:
npx healflow init --codemod-dir e2e/healing

Cloud registration:

npx healflow init --cloud \
  --url https://api.healflow.example \
  --org my-org \
  --repo my-repo \
  --token hf_...

healflow doctor

Validate config, Playwright setup, adoption ratio, and optional backend connectivity:

npx healflow doctor
npx healflow doctor --strict          # exit 1 if 0/N specs wired
npx healflow doctor --file tests/foo.spec.ts

Reports: Healing fixture: N/M spec files and up to five unwired examples.

healflow report

Open the local HTML report from the last test run:

npx healflow report

Requires .healflow/report.html (created by npx playwright test).

healflow ingest

Upload Playwright JSON report failures to the HealFlow API:

npx healflow ingest test-results/results.json

Requires backend.url, organizationId, and repositoryId in healflow.yml.

healflow analyze report

Parse a Playwright JSON report, test-results/, HTML report folder (with sidecar JSON), or zip — then plan failed-only replay. With --heal-all, re-runs only failed tests so the existing runtime healing engine can act.

npx healflow analyze report test-results/results.json
npx healflow analyze report test-results/ --heal-all
npx healflow analyze report playwright-report.zip --heal-all --dry-run

Requires HealFlow wired in playwright.config.* for --heal-all. Writes .healflow/session/<id>/, .healflow/report.json, and .healflow/report.html. See docs/product/REPORT_ANALYZE.md.

healflow apply

Preview permanent fix proposals from .healflow/fixes.json (dry-run by default):

npx healflow apply

Typical workflow

npx healflow init --config-only
npx healflow init --codemod-dir tests/healing   # gradual rollout
npx healflow doctor --strict
npx playwright test
npx healflow report

Configuration

Reads healflow.yml from the project root (walks up parent directories; override with HEALFLOW_CONFIG). See @healflow/shared for the full config schema.

Development

From the monorepo root:

pnpm healflow doctor
pnpm --filter @healflow/cli build
pnpm --filter @healflow/cli test

Related packages

• @healflow/playwright — runtime plugin wired by init
• @healflow/ingestion — report parsing for ingest

License

MIT