UI QA

Appearance

Automated UI/UX Testing

Test websites with intelligent browser automation and LLM-powered analysis

Get Started
GitHub

Intelligent Scenario Generation

LLM generates test scenarios per page from DOM snapshots and screenshots

Sitemap + Link Discovery

Finds pages via sitemap/robots.txt with link-crawling fallback

Real Browser Automation

Executes tests using Playwright with real clicks, fills, and navigation

Parallel Scenario Execution

Runs scenarios concurrently across multiple browser instances

Business Logic Validation

Validates websites against specifications with requirement traceability

Screenshot Evidence

Captures screenshots for every step and issue

Scored Reports + LLM Fix Guide

Generates a scored report and a plain-text fix guide for LLMs

Local Run History

Stores runs in .ui-qa-runs with events.jsonl, run.json, report.md, and screenshots

TUI Progress + Logs

Live terminal UI with phases, progress bars, and log streaming

Update Notifications

Checks for new versions and prompts when updates are available

Quick Start ​

UI/UX Testing ​

bash
npx @usharma124/ui-qa https://example.com

Business Logic Validation ​

bash
npx @usharma124/ui-qa validate --spec requirements.md --url https://app.example.com

Prerequisites

An OpenRouter API key is required. See Configuration for setup details.

How It Works ​

UI QA offers two modes:

Test Mode (Default) ​

Processes websites through four phases:

PhaseDescription
DiscoveryIdentifies pages via sitemap.xml, robots.txt, or link crawling
AnalysisLLM analyzes each page (DOM + screenshot) to generate test scenarios
ExecutionRuns scenarios concurrently using Playwright with real browser automation
EvaluationLLM evaluates evidence and produces scored reports with categorized issues

Validation Mode ​

Validates websites against specification documents through eight phases:

PhaseDescription
ParsingParses specification document (markdown format)
ExtractionExtracts testable requirements using LLM with MoSCoW priorities
RubricGenerates evaluation rubric with pass/fail conditions and weights
DiscoveryDiscovers site structure (same as test mode)
PlanningCreates requirement-linked test plan mapping requirements to pages
ExecutionRuns tests with browser automation and captures evidence
Cross-ValidationValidates test results against requirements and rubric criteria
ReportingGenerates traceability report linking requirements to evidence

Output ​

┌─────────────────────────────────────────┐
│  UI/UX QA Agent                         │
├─────────────────────────────────────────┤
│  ✓ Discovery   → Found 5 pages          │
│  ✓ Analysis    → 12 scenarios           │
│  ● Execution   → Running scenarios...   │
│  ○ Evaluation  → Pending                │
└─────────────────────────────────────────┘

Results include markdown reports, run metadata, streaming JSON logs, and screenshots saved to .ui-qa-runs/.

TUI UX Notes ​

  • Adaptive density by terminal height:
    • >= 40 rows: rich mode
    • 30-39 rows: standard mode
    • 24-29 rows: compact mode
    • < 24 rows: minimal mode (phase + progress + logs)
  • Log navigation shortcuts:
    • ↑/↓ or k/j for line scroll
    • PgUp/PgDn for page scroll
    • g/G for top/bottom (G re-enables live follow)

Released under the MIT License.