UX Usability Auditor

Automated usability and UX inspection for web applications. Navigates target app pages, captures screenshots and UI element metadata, then generates a structured audit report mapped to a usability checklist.

Quick Start

Minimal workflow — 4 steps:

1. Prepare config — create a config.json (see Configuration)
2. Run inspection — node scripts/inspect.js config.json
3. Review results — check results/inspection_results.json and screenshots
4. Generate report — node scripts/generate_report.js config.json

Configuration

Create a config.json in the working directory:

{
  "name": "My App Usability Audit",
  "targetUrl": "https://example.com/#/login",
  "login": {
    "username": "admin",
    "password": "123456",
    "usernameSelector": "input[type='text'], input[placeholder*='账号'], input[placeholder*='用户名']",
    "passwordSelector": "input[type='password'], input[placeholder*='密码']",
    "submitSelector": "button:has-text('登录'), button:has-text('Login'), .login-btn"
  },
  "pages": [],
  "checklist": "references/checklist-default.md",
  "outputDir": "./results",
  "screenshotDir": "./results/screenshots",
  "headless": false
}

pages field (auto-discovery if empty):

• [] — auto-discover pages by clicking through sidebar/menu after login
• explicit list — provide known page URLs:

{
  "pages": [
    { "name": "Dashboard", "url": "/#/dashboard" },
    { "name": "User List", "url": "/#/users" }
  ]
}

Login selectors — customize if the target app uses non-standard login form. Default works for most Element UI / Ant Design apps.

Scripts

scripts/inspect.js — Main Inspection Runner

Navigates pages, captures screenshots and UI metadata.

node scripts/inspect.js path/to/config.json

Output: results/inspection_results.json + results/screenshots/*.png

The script:

1. Launches Chromium via Playwright
2. Logs in using credentials from config
3. Discovers pages (auto from sidebar, or from config)
4. For each page: waits for load, screenshots, extracts UI stats (button/input/table counts, empty states, breadcrumbs, action buttons)
5. Writes results to JSON

scripts/generate_report.js — Report Generator

Generates a markdown audit report from inspection results + checklist.

node scripts/generate_report.js path/to/config.json

Output: results/usability_audit_report.md

The script:

1. Loads inspection_results.json
2. Parses the checklist (markdown file, supports the standard 6-category format)
3. Evaluates each checklist item against inspection data
4. Generates a structured report with: summary table, detailed findings per category, evidence screenshots, priority-ranked issue list

Checklist Format

The default checklist is at references/checklist-default.md. It follows this format (compatible with the 易用性专项检查项清单 Excel):

# Usability Checklist

## Category 1: Navigation & Layout
### 1.1 Menu Hierarchy
- **Standard**: menu depth ≤ 3 levels, high-frequency entries prioritized
- **Applicable to**: All modules

To use a custom checklist, point checklist in config.json to your own markdown file, or pass a path to generate_report.js:

node scripts/generate_report.js config.json --checklist my_checklist.md

Advanced: Tuning Page Discovery

If auto-discovery misses pages, manually list them in config.json pages field. The inspector will navigate to each URL and capture data.

For single-page apps (SPA) with hash routing (like the one we audited), make sure URLs include the #/ fragment.

Output Structure

results/
├── inspection_results.json      # Raw inspection data per page
├── usability_audit_report.md   # Final report (markdown)
├── screenshots/
│   ├── 01_dashboard.png
│   ├── 02_user_list.png
│   └── ...
└── report_assets/              # Copied screenshots for report embedding

Notes

• Playwright required: npm install playwright before first run
• Chromium bundled: Playwright downloads its own Chromium; no local Chrome needed
• Headless mode: Set "headless": true in config for CI/batch runs
• Chinese UI: Default selectors and checklist support Chinese enterprise web apps (Element UI, Ant Design)
• SPA support: Handles hash-based routing (#/) and pushState routing