QA & Testing — UIX Docs

Overview

UIX Protocol treats QA as a first-class concern — not a bolt-on. The Immune System embeds testing metadata directly in the schema, and the QA engine detects regressions at the semantic level.

Regression detection

The @uix/qa-engine compares two UIXDocuments and detects regressions across 8 categories:

Category	What it detects
Layout	Width, height, padding, gap changes
Color	Background, foreground, border color shifts
Typography	Font size, weight, family, line height
Visibility	Opacity, display, hidden state changes
Semantic	Type changes, role changes, name changes
Accessibility	Missing labels, contrast degradation, role removal
Spacing	Margin, gap, padding inconsistencies
Interaction	Event handler changes, disabled state

typescript

import { RegressionDetector } from '@uix/qa-engine';

const detector = new RegressionDetector();
const regressions = detector.detect(oldDoc, newDoc);
// [{ category: 'color', severity: 'high', nodeId: 'btn-1', ... }]

Test generation

The engine generates Playwright test code from document comparisons:

typescript

import { TestGenerator } from '@uix/qa-engine';

const generator = new TestGenerator();
const tests = generator.generate(regressions, document);
// Playwright test script as string

Selector strategy

4-tier selector generation for reliable test targeting:

data-testid — most stable
ARIA role + label — accessible and meaningful
CSS selector — fallback
XPath — last resort

Immune System

QA metadata lives in the schema itself:

json

{
  "extensions": {
    "qa": {
      "coverageStatus": "covered",
      "regressionRisk": "high",
      "lastTestedVersion": "1.2.0",
      "testIds": ["test-btn-click", "test-btn-disabled"]
    }
  }
}

Blueprint-level test hints guide test generators:

typescript

const hints = getTestHints(registry, 'Button');
// { selector, properties, assertions, interaction }

QA Dashboard (Catalyst)

@uix/catalyst is a visual dashboard for QA:

Overview — total regressions, coverage %, health score
Regressions — filterable list with severity and category
Tests — generated test suites with copy-to-clipboard
Coverage — per-node coverage heat map
Telemetry — OTEL-aligned spans, logs, and metrics
CI — pipeline status, quality gate, deployment health