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

If you try it out, I’d genuinely love feedback. Curious what people think about this approach to UI testing.