ux-audit

Deterministic UI/UX testing and evidence platform for AI-assisted remediation.

ux-audit audits one or more URLs using deterministic checks (Axe + Lighthouse), then writes a structured evidence bundle your AI agent (or team) can use to prioritize and implement fixes.

Features

• Deterministic checks for accessibility and performance
• Flexible scope: single URL, URL list, or base URL + paths
• Pattern opt-in for targeted UX guidance (for example auth, forms, crud)
• Evidence bundle with JSON/Markdown report and per-page artifacts
• Optional screenshots and DOM snapshots for debugging
• Authenticated page support via Playwright storage state

Requirements

• Node.js >=18
• Chrome/Chromium available for Lighthouse
• Playwright Chromium browser installed for Axe runner

Install

npm install ux-audit

If you are developing this repo locally:

npm install
npm run build
npm run install:browsers

Quick Start

Audit a single page:

npx ux-audit audit https://example.com

Audit multiple URLs:

npx ux-audit audit --urls https://example.com/,https://example.com/docs --out ./test-run

Audit with base URL + paths:

npx ux-audit audit --base-url https://example.com --paths /,/pricing,/docs --patterns auth,forms

Show CLI help:

npx ux-audit --help

CLI Usage

ux-audit audit [url] [options]

Scope (choose one):

• url (positional) or --url <url>
• --urls <url1,url2,...>
• --base-url <url> --paths <path1,path2,...>

Options:

• --out <dir> output directory (default: ./ux-audit-bundle)
• --patterns <id,id,...> enable pattern-specific checks
• --include-screenshots include screenshots (default: enabled)
• --no-screenshots disable screenshots
• --include-dom-snapshot include page HTML snapshots
• --storage-state <path> Playwright auth state JSON
• --config <path> config file path override
• --help, -h

Exit codes:

• 0 success with no critical findings
• 1 critical findings exist (or runtime failure)

Configuration

By default, the CLI looks for:

• ux-audit.config.json
• ux-audit.config.js
• .ux-audit.json

Recommended config format (ux-audit.config.json):

{
  "baseUrl": "https://example.com",
  "paths": ["/", "/docs"],
  "patterns": ["auth", "forms"],
  "out": "./custom-out",
  "auth": {
    "storageState": "./playwright-auth.json"
  }
}

Supported fields:

• urls: string[]
• baseUrl: string
• paths: string[]
• patterns: string[]
• out: string
• auth.storageState: string

CLI arguments override config values.

Pattern IDs

Available pattern IDs:

• auth
• forms
• crud
• navigation
• onboarding
• search-filter
• empty-error-loading
• settings
• dashboards
• checkout
• content-display
• modals-overlays
• data-tables

Auditing Authenticated Pages

1. Create a Playwright storage state file from a logged-in session:

// Example snippet
await context.storageState({ path: "playwright-auth.json" });

2. Run audit with that state:

npx ux-audit audit https://yourapp.com/dashboard --storage-state ./playwright-auth.json --out ./test-run

Security note: storage state contains session data. Never commit it.

Output Bundle

For each run, ux-audit writes:

• ux-audit-report.json machine-readable findings
• ux-audit-report.md human-readable summary
• index.json manifest with scope, patterns, and artifact paths
• a11y/*.json per-page Axe + heuristics artifacts
• metrics/*.json per-page Lighthouse artifacts
• screenshots/*.png when screenshots are enabled
• snapshots/*.html when --include-dom-snapshot is enabled
• patterns.json when pattern IDs are enabled
• AGENT_PROMPT.md guide for consuming findings in an AI workflow

NPM Scripts (repo)

• npm run build compile TypeScript
• npm run test run Jest tests
• npm run test:node run Node test runner
• npm run install:browsers install Playwright Chromium
• npm run audit -- <args> run CLI through package script
• npm run audit:demo run demo audit against https://example.com

Programmatic API

The package currently exports:

• runAudit from src/pipeline/runAudit.ts
• getPatternIds from src/patterns/catalog.ts
• report/finding types from src/report/types.ts

License

MIT