Getting Started
UI QA is a command-line tool for automated UI/UX testing. It uses browser automation and LLM analysis to identify issues across your website.
Prerequisites
- Node.js 18 or later (or Bun)
- OpenRouter API key
Installation
Using npx (Recommended)
Run without installation:
bash
npx @usharma124/ui-qa https://example.comGlobal Installation
Install for repeated use:
bash
npm install -g @usharma124/ui-qabash
bun add -g @usharma124/ui-qabash
pnpm add -g @usharma124/ui-qaThen run from any directory:
bash
ui-qa https://example.comProject Dependency
Add to your project for CI/CD integration:
bash
npm install --save-dev @usharma124/ui-qabash
bun add -D @usharma124/ui-qaAdd a script to package.json:
json
{
"scripts": {
"test:ui": "ui-qa https://staging.example.com"
}
}Browser Setup
Install Chromium on first run:
bash
npx playwright install chromiumRunning Your First Test
- Set your API key:
bash
export OPENROUTER_API_KEY=sk-or-v1-your-key-here- Run a test:
bash
# UI/UX testing mode (default)
npx @usharma124/ui-qa https://example.com
# Business logic validation mode
npx @usharma124/ui-qa validate --spec requirements.md --url https://app.example.com- View results:
Test Mode - Results in .ui-qa-runs/:
| File | Contents |
|---|---|
events.jsonl | Streaming JSON event log for the run |
run.json | Run metadata plus embedded report and evidence |
report.md | Human-readable report |
llm-fix.txt | Plain-text fix guide for LLMs |
screenshots/ | Visual evidence |
Validation Mode - Run artifacts in .ui-qa-runs/validation-<run-id>/ and reports in output directory (default: ./reports):
| File | Contents |
|---|---|
.ui-qa-runs/validation-<run-id>/events.jsonl | Streaming phase-by-phase validation events |
.ui-qa-runs/validation-<run-id>/run.json | Validation run metadata |
traceability-report-<timestamp>.json | Full validation report |
traceability-report-<timestamp>.md | Human-readable summary |