HumanQA documentation

From intent to inspectable proof

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

Quick start

Run the included deterministic fixture before adapting a real target.

Install
Use Node.js 20 or newer, pnpm, and Chromium.
Start the fixture
The default mode contains deliberate, reproducible defects.
Audit the journey
HumanQA writes evidence and reports under humanqa-output/.

corepack enable
pnpm install --frozen-lockfile
pnpm humanqa install-browser
pnpm demo
pnpm humanqa audit http://127.0.0.1:4173 --offline --journey packs/journeys/saas-project-creation.yaml

Expected broken-fixture result

Block release, score 0/100, eight deterministic findings, seven screenshots, and a Playwright trace.

Quality contracts

Version product intent beside the journey that can prove it.

project:
  name: Example SaaS
  baseUrl: http://127.0.0.1:4173
defaults:
  safeMode: true
  redact: true
  screenshots: true
quality_contracts:
  - id: project-creation
    persona: first-time-saas-user
    journey: packs/journeys/saas-project-creation.yaml
    acceptance_criteria:
      - User can create a project
      - User sees persistent success confirmation
    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 doctorhumanqa 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@v4
- 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.