What if UI tests validated user experience instead of selectors?

Ali Eissa — Thu, 28 May 2026 12:01:30 +0000

Most UI testing today focuses on validating implementation details, whether DOM structure, selectors, or UI hooks.

But teams don’t ship implementations. They ship user experiences.

That gap is what I started building VizQA for.

It’s a lightweight UI testing framework that evaluates applications through visual perception and behavioral expectations. It runs fully locally, without runtime LLM calls.

The goal is simple:
Validate whether the product behaves the way it was intended to be experienced.

What this actually means

Instead of testing how the UI is built, VizQA focuses on how it is perceived and used.

That includes things like:

expected flows completing end-to-end
visibility of key elements during flows
layout correctness across screen sizes
alignment between intended and actual UX behavior

For example, a traditional E2E test may pass because a button exists in the DOM. VizQA can fail the test if the button is visually obscured, off-screen, or appears in the wrong context.

Test sample:

name: "Dependency Checkout"
url: "https://site.com/"
description: "Creates an order that downstream return tests can consume."

requires:
  - dependency_login_mfa

artifacts:
  item_name: "Widget Pro Secure Key"

steps:
  - action: "Click the 'Catalog and Checkout' navigation button"
    expect: "The 'Catalog and Checkout' view should load"
  - action: "Click the 'Add Widget Pro Secure Key to Cart' button"
    expect: "A success banner should confirm that {item_name} was added to the cart"
  - action: "Click the 'Complete Checkout' button"
    expect: "The 'Orders and Returns' view should load and show a new order with item {item_name}"

👥 Designed for more than just developers

Because tests are behavioral, not implementation-specific, they can be authored or derived from:

product specs
UX flows
QA scenarios
acceptance criteria

This reduces the translation layer between:
“what was designed” → “what gets tested”

And because the same behavioral definitions are used for execution, VizQA allows them to remain stable across runs, being:

fully local
deterministic (no runtime LLM calls or random AI seeds)
repeatable in CI and local environments
lightweight and fast

👁️ Visual execution

VizQA relies on UI-Atlas, a local CPU-based perception engine that evaluates what is actually rendered on screen rather than relying only on selectors or DOM structure.

Under the hood, VizQA evaluates:

rendered UI visibility
flow correctness
viewport-specific layout behavior
alignment between expected and actual UI state

This allows it to detect issues like:

elements not visible in context
broken flows that still technically “work”
layout issues across different viewports
mismatches between expected and actual UI state

🧪 Additional capabilities

Beyond core execution, VizQA also supports:

Multi-viewport regression testing
Test prerequisites: flow sections as reusable blocks to build maintainable test suites.
Library API for embedding into Playwright-based tests, or general automation.

Try it:

docker run -d -p 8228:8000 --name ui-atlas tinyreasonlabs/ui-atlas:latest
pip install vizqa
vizqa install
vizqa run tests/

VizQA on Github
UI Atlas on Dockerhub