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.
Top comments (1)
Selector-based tests are great for structure, but they miss a lot of the stuff users actually notice: broken image crops, wrong aspect ratios, blurry thumbnails, video posters not loading, or a hero image that shifts the whole layout.
For media-heavy apps, that gap gets painful fast because the UI can be "technically green" while visually broken.
The interesting part is that visual/behavioral testing pairs really well with deterministic media delivery. If your app generates responsive variants, crops, or format changes on the fly, you want your tests to assert the rendered experience, not just that an
<img>tag exists.