@qflow/cli

The qflow CLI binary. All commands a user interacts with live here.

Help

Every command supports --help, auto-generated by commander:

qflow --help              # list every command with a one-line description
qflow <command> --help    # show options + flags for a specific command, e.g.
qflow run --help
qflow init --help

Use qflow --version to print the installed version.

Commands

qflow init

Interactive setup wizard. Auto-detects what it can; prompts for the rest:

• Test modes (multi-select): ui, api, unit, component
• sourcePath (required when unit or component is selected) — default detected from src / lib / app
• Test runner — default detected from your package.json (@playwright/test, vitest, jest) or playwright.config.ts
• JIRA / Azure DevOps connection (optional)
• LLM provider (default true; powers generate, heal, review)
• Notification channels (Slack / Teams / JIRA)
• GitHub Pages dashboard
• CI workflow — generates .github/workflows/qflow-test.yml with PR comments + artifact upload + browser cache

Outputs:

• framework.config.ts in the current directory
• .qflow/ directory (gitignored)
• .github/workflows/qflow-test.yml (if GitHub Actions selected)
• Updates .gitignore
• Runs qflow doctor --quick at the end to verify the result

qflow doctor [--quick]

Diagnose your qflow setup. Verifies:

• package.json and framework.config.ts exist and load cleanly
• Git repository + gh CLI presence
• Configured runner is installed in package.json
• Playwright browsers are installed (when applicable)
• testingContext.sourcePath exists when unit / component modes are configured
• Test files exist for each configured mode

Without --quick, also performs network checks: LLM ping, JIRA /myself, ADO /projects, Slack/Teams webhook URL shape, GITHUB_TOKEN. Exits with code 1 on any failure — safe in CI.

qflow run [options]

| Flag | Description | |---|---| | -s, --suite <suite> | regression (default) | smoke | pr-smart | | -l, --local | Skip all notifications, LLM calls, and gh-pages publishing | | -e, --env <name> | Apply an environments.<name> profile from framework.config.ts — overrides runner.baseUrl and merges runner.env |

Behaviour:

1. Loads and validates framework.config.ts
2. Calls the Orchestrator, which runs the configured test suite
3. Reporter Agent persists results, fires notifications, publishes to gh-pages
4. Exits with code 1 if any tests fail (safe for CI)

--local mode is fast and offline — no tokens spent, no webhooks fired. Useful for developer feedback loops.

qflow generate --ticket <key>

Generates UI / API / unit / component tests from a JIRA or Azure DevOps ticket's acceptance criteria and opens a Draft PR. The Generator embeds repo context (existing POMs, fixtures, example tests) into the prompt; the Reviewer scores the result and rejects PRs that duplicate existing helpers.

qflow heal [--apply] [--run-id <id>]

Reads the latest run report (or a specific --run-id) and asks the LLM to repair broken Playwright selectors. Defaults to a dry-run that prints the proposed - old / + new diff. Pass --apply to write the patches to disk; if selfHealing.autoCommit is true in your config, healed files are committed to the current branch.

qflow watch [--suite] [--env] [--paths]

Re-runs the suite (default pr-smart) every time a watched file changes. Debounced 400ms. Defaults to watching src,tests. Ctrl+C to exit.

qflow list <target>

Lists qflow assets discovered in the current project:

| Target | Output | |---|---| | tests | Discovered test files grouped by mode (ui / api / unit / component) | | suites | Built-in suites + your tags.smoke / tags.regression overrides | | runs | Last 20 run reports from .qflow/data/ | | page-objects | Page Object classes the Generator will reuse | | fixtures | Fixture / factory exports the Generator will reuse | | tickets | (placeholder — use your provider UI) |

qflow record <url> [-o <path>]

Wraps playwright codegen --target=playwright-test and saves the recorded spec under tests/ui/ (default tests/ui/recorded-<timestamp>.spec.ts). The spec is meant as a starting point — review and replace hard-coded selectors with getByRole / getByLabel before committing.

qflow replay [runId]

Re-runs only the failed tests from a previous run (default: latest) by passing their names through the configured runner's filter flag (--grep / --testNamePattern / pytest node-ids). Inherits the run's exit code.

qflow upgrade [--dry-run]

Fetches the latest published versions of @qflow/core and @qflow/cli from npm and bumps the pinned ranges in your package.json. Use --dry-run to preview without writing.

qflow dashboard [--port <port>]

Starts a local HTTP server (default port 3000) that serves the dashboard SPA reading from .qflow/data/. Useful when the GitHub Pages site is not set up or when working offline.

qflow costs

Prints LLM token usage and estimated cost per agent, per run, and monthly total.

qflow flakiness

Prints current flakiness stats and quarantine status for all tracked tests.

qflow coverage-check

Checks JIRA or Azure DevOps "Done" user stories against test files. Reports stories that shipped without tests.

Commands directory structure

src/
├── index.ts               Commander program — registers all commands
└── commands/
    ├── init.ts            Interactive wizard + file generation + mini-doctor
    ├── doctor.ts          Local + network health checks
    ├── run.ts             Orchestrator invocation + result printer (--env support)
    ├── generate.ts        LLM test generation from JIRA / ADO ticket
    ├── heal.ts            LLM-driven Playwright selector repair (dry-run / --apply)
    ├── watch.ts           File-watcher loop
    ├── list.ts            tests | suites | runs | page-objects | fixtures
    ├── record.ts          playwright codegen wrapper
    ├── replay.ts          Re-run failed tests from a previous run
    ├── upgrade.ts         Bump @qflow packages to latest
    ├── dashboard.ts       Local dashboard server + /api/manifest endpoint
    ├── costs.ts           LLM token usage + cost summary
    ├── flakiness.ts       Flakiness stats + quarantine status
    └── coverage-check.ts  Ticket coverage drift report

Build

pnpm build    # compile to dist/ (shebang auto-prepended)
pnpm dev      # run directly via tsx (no compile step)