HumanQA documentation

From intent to inspectable proof

Configure one safe journey, run it locally, and carry the evidence into review or CI.

Quick start

Create a self-contained starter, then point it at an authorized local target.

Install
Use Node.js 20 or newer, pnpm, and Chromium.
Initialize
Generate a safe Quality Contract and local smoke journey.
Audit the journey
HumanQA writes evidence and reports under humanqa-output/.

npx humanqa install-browser
npx humanqa init --name "My web application" --url http://127.0.0.1:3000
npx humanqa verify --config humanqa.yml

Self-contained npm onboarding

The generated contract references humanqa/journeys/smoke.yaml, not a repository-only pack. Review the URL and journey before running it.

Quality contracts

Version product intent beside the journey that can prove it.

project:
  name: Example SaaS
  baseUrl: http://127.0.0.1:3000
defaults:
  safeMode: true
  redact: true
  screenshots: true
quality_contracts:
  - id: application-smoke
    journey: humanqa/journeys/smoke.yaml
    acceptance_criteria:
      - Application document is visible
    thresholds:
      max_critical_findings: 0
      min_quality_score: 80

Unmapped prose is marked for review. HumanQA does not infer that an acceptance criterion passed merely because the page loaded.

CLI commands

Every external or mutation-capable boundary remains explicit.

humanqa inithumanqa audit <url>humanqa verify --config humanqa.ymlhumanqa generate-test <report.json>humanqa list-packshumanqa validate-pack <path>humanqa install-browser [--with-deps]humanqa doctor [--json]humanqa github comment --report <report.json> --dry-run

--offline

Require a loopback target and block cross-origin requests.

--no-screenshots

Avoid visual artifacts on sensitive targets.

--mobile

Use touch and a 390x844 default viewport.

--allow-mutations

Explicitly permit reviewed mutation-capable steps.

Report contract

One normalized report object drives every format.

JSONMarkdownHTMLSARIFJUnit XML

Every finding includes a stable ID, category, severity, confidence, user impact, effort, journey criticality, priority, release risk, reproduction, evidence, remediation, regression candidacy, and limitations.

Priority(reach × impact × confidence) / max(effort, 1)

Release riskΣ severity_weight × confidence × journey_criticality

Safety and privacy

Local-first is an execution boundary, not a marketing phrase.

Blocked by default

Payments, deletion, account changes, messages, private uploads, and high-impact actions.

Redacted by default

Emails, bearer tokens, API keys, passwords, secret query parameters, and authorization headers.

Never automatic

Artifact uploads, telemetry, LLM enrichment, GitHub writes, severity upgrades, and compliance claims.

Manual review remains required.

Automated axe and keyboard checks do not establish WCAG conformance, legal compliance, or usability across untested states.

Packs and agent skills

Extend product knowledge without introducing executable pack code.

27 YAML packs

Personas, journeys, heuristics, product frameworks, and industries.

5 portable skills

UX audit, PRD verification, accessibility gate, regression generation, and release readiness.

pnpm humanqa list-packs
pnpm humanqa validate-pack packs
pnpm humanqa validate-pack path/to/new-pack.yaml

CI and GitHub

Use report artifacts for review while keeping writes dry-run in v0.1.

- uses: pnpm/action-setup@v6
- run: pnpm install --frozen-lockfile
- run: pnpm humanqa install-browser --with-deps
- run: pnpm humanqa verify --config humanqa.yml

SARIF, JUnit XML, concise pull-request Markdown, and GitHub annotations all derive from the same evidence-backed report.

Package publishing

Release only from a clean, validated commit with provenance.

pnpm release:validateGitHub trusted publisherhumanqa + @humanqa/cli

The short package preserves npx humanqa; the same validated bundle is published under the HumanQA npm organization as @humanqa/cli. A release or manual publish workflow action is still required.