vizQA 0.1.0__tar.gz

vizqa-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TinyReasonLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vizqa-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: vizQA
+Version: 0.1.0
+Summary: Vision-driven UI Testing Framework
+License-File: LICENSE.md
+Author: Spospider
+Author-email: 64846609+Spospider@users.noreply.github.com
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click (>=8.1.7)
+Requires-Dist: httpx (>=0.27.0)
+Requires-Dist: onnxruntime (>=1.24.3,<2.0.0)
+Requires-Dist: playwright (>=1.58.0,<2.0.0)
+Requires-Dist: pydantic (>=2.6.0)
+Requires-Dist: pyyaml (>=6.0.1)
+Requires-Dist: rich (>=13.7.0)
+Requires-Dist: tokenizers (>=0.22.2,<0.23.0)
+Requires-Dist: tomli (>=2.0.0,<3.0.0) ; python_version < "3.11"
+Description-Content-Type: text/markdown
+
+# vizQA: Vision-Driven Web UI Testing Framework
+
+[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
+[![Code Coverage](https://img.shields.io/badge/coverage-55%25-orange.svg)]()
+
+**vizQA** is a lightweight, next-generation UI testing framework that "sees" and interacts with your application like a human does. By combining Playwright's robust automation with advanced visual perception and semantic search, vizQA allows you to write tests in natural language without brittle CSS selectors or XPath—all running efficiently on **CPU** without the need for LLMs.
+
+> [!IMPORTANT]
+> **vizQA is currently in its early alpha stage.** We are actively developing and refining the framework. Feedback, bug reports, and contributions are highly encouraged and welcome! Please review our [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
+
+
+---
+
+## 👁️ Why Vision-Driven?
+
+Traditional UI testing relies on the underlying DOM structure. When a developer changes a class name or wraps an element in a new `div`, tests break—even if the UI looks identical to the user.
+
+**vizQA changes the paradigm by focusing on the visual reality:**
+- **Natural Language**: Write tests like "Click the login button" or "Verify the error message appears in red".
+- **Visual Intelligence**: Understands visual rules such as **contrast** against background, **salience** (how much an element stands out), and **spatial semantics** ("the button at the top right").
+- **Real-World Verification**: Verifies **reachability**, **visibility**, and detects **obstruction** (e.g., an element being covered by a modal or tooltip).
+- **Semantic Understanding**: Finds elements based on intent and visual appearance, not just hidden attributes.
+
+---
+
+## Key Features
+
+- **Natural Language Steps**: Define your test flow in simple YAML instructions.
+- **Advanced Interactions**: Supports `click`, `hover`, `type`, `scroll`, and even `drag and drop`.
+- **Visual Assertions**: Verify UI state, colors, positions, and visibility.
+- **Artifact Variables**: Load strings, file contents, or paths as variables (e.g., `{user_name}`) for dynamic test data.
+- **Lightweight & Fast**: CPU-only execution with a minimal **~250 MB** memory footprint and sub-second latency.
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- **Python 3.11+**
+- **Playwright**
+- **UI Perception Backend**: vizQA requires a perception backend. You can run the official lightweight UI-Atlas docker image for cully local operation:
+  ```bash
+  docker run -d -p 8228:8000 --name ui-atlas tinyreasonlabs/ui-atlas:latest
+  ```
+  Learn more about [UI-Atlas on Dockerhub](https://hub.docker.com/r/tinyreasonlabs/ui-atlas)
+
+  vizQA connects to the backend using the `PERCEPTION_BACKEND` environment variable:
+  - Default: `localhost:8228`
+  - Example:
+    ```bash
+    export PERCEPTION_BACKEND=localhost:8228
+    ```
+
+### Installation
+
+```bash
+pip install vizqa
+vizqa install
+```
+
+---
+
+## 📝 Usage
+
+### Define a Test (`login_test.yaml`)
+
+```yaml
+name: "User Login Flow"
+url: "https://example.com/login"
+description: "Verify that a user can log in with valid credentials."
+
+steps:
+  - action: "Type 'admin' into the username field"
+    expect: "The username field should contain 'admin'"
+  - action: "Type 'password123' into the password field"
+  - action: "Click the 'Login' button"
+    expect: "Should redirect to the dashboard and show 'Welcome back!'"
+```
+
+### Run the Test
+
+```bash
+# Run all tests in a directory
+vizqa tests/
+```
+
+### CLI Arguments
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| `paths` | One or more paths to test files or directories. | (Required) |
+| `--headless / --no-headless` | Run browser in headless mode. | `True` |
+| `-v, --verbose` | Increase output verbosity (-v, -vv). | `0` |
+| `-x, --interactive` | Stop and enter interactive mode on first failure. | `False` |
+| `--report` | Generate a visual HTML report after execution. | `False` |
+
+---
+
+## Configuration
+
+vizQA supports global and per-test configuration, including custom HTTP headers for authentication or specialized testing.
+
+### Global Configuration
+You can define global headers in your `pyproject.toml` or any common `.ini` file (e.g., `pytest.ini`, `tox.ini`).
+
+**`pyproject.toml`**
+```toml
+[tool.vizqa.headers]
+Authorization = "Bearer global-api-token"
+X-Custom-Header = "GlobalValue"
+```
+
+**`pytest.ini` / `vizqa.ini`**
+```ini
+[vizqa.headers]
+Authorization = Bearer global-api-token
+X-Custom-Header = GlobalValue
+```
+
+### Per-Test Overrides
+You can specify or override headers directly in your test YAML file. These take precedence over global settings.
+
+**`my_test.yaml`**
+```yaml
+name: "Protected API Test"
+url: "https://example.com/api"
+headers:
+  Authorization: "Bearer test-specific-token"
+steps:
+  - VERIFY: "Welcome" should appear
+```
+
+---
+
+## Methodology
+
+vizQA follows a three-stage execution cycle for every step:
+
+1.  **Perception**: Takes a screenshot and sends it to the Perception API to identify all visual elements and their properties (bounds, text, color, state).
+2.  **Planning**: Uses semantic matching to understand intent and internally breaks down high-level instructions into atomic `find`, `do`, and `verify` commands to handle complex interactions.
+3.  **Execution**: Performs the interaction via Playwright using precise pixel coordinates, ensuring we interact exactly with what was "seen."
+
+---
+
+## Contributing
+
+We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for details on setting up the environment and submitting PRs.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+

vizqa-0.1.0/README.md

@@ -0,0 +1,153 @@
+# vizQA: Vision-Driven Web UI Testing Framework
+
+[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
+[![Code Coverage](https://img.shields.io/badge/coverage-55%25-orange.svg)]()
+
+**vizQA** is a lightweight, next-generation UI testing framework that "sees" and interacts with your application like a human does. By combining Playwright's robust automation with advanced visual perception and semantic search, vizQA allows you to write tests in natural language without brittle CSS selectors or XPath—all running efficiently on **CPU** without the need for LLMs.
+
+> [!IMPORTANT]
+> **vizQA is currently in its early alpha stage.** We are actively developing and refining the framework. Feedback, bug reports, and contributions are highly encouraged and welcome! Please review our [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
+
+
+---
+
+## 👁️ Why Vision-Driven?
+
+Traditional UI testing relies on the underlying DOM structure. When a developer changes a class name or wraps an element in a new `div`, tests break—even if the UI looks identical to the user.
+
+**vizQA changes the paradigm by focusing on the visual reality:**
+- **Natural Language**: Write tests like "Click the login button" or "Verify the error message appears in red".
+- **Visual Intelligence**: Understands visual rules such as **contrast** against background, **salience** (how much an element stands out), and **spatial semantics** ("the button at the top right").
+- **Real-World Verification**: Verifies **reachability**, **visibility**, and detects **obstruction** (e.g., an element being covered by a modal or tooltip).
+- **Semantic Understanding**: Finds elements based on intent and visual appearance, not just hidden attributes.
+
+---
+
+## Key Features
+
+- **Natural Language Steps**: Define your test flow in simple YAML instructions.
+- **Advanced Interactions**: Supports `click`, `hover`, `type`, `scroll`, and even `drag and drop`.
+- **Visual Assertions**: Verify UI state, colors, positions, and visibility.
+- **Artifact Variables**: Load strings, file contents, or paths as variables (e.g., `{user_name}`) for dynamic test data.
+- **Lightweight & Fast**: CPU-only execution with a minimal **~250 MB** memory footprint and sub-second latency.
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- **Python 3.11+**
+- **Playwright**
+- **UI Perception Backend**: vizQA requires a perception backend. You can run the official lightweight UI-Atlas docker image for cully local operation:
+  ```bash
+  docker run -d -p 8228:8000 --name ui-atlas tinyreasonlabs/ui-atlas:latest
+  ```
+  Learn more about [UI-Atlas on Dockerhub](https://hub.docker.com/r/tinyreasonlabs/ui-atlas)
+
+  vizQA connects to the backend using the `PERCEPTION_BACKEND` environment variable:
+  - Default: `localhost:8228`
+  - Example:
+    ```bash
+    export PERCEPTION_BACKEND=localhost:8228
+    ```
+
+### Installation
+
+```bash
+pip install vizqa
+vizqa install
+```
+
+---
+
+## 📝 Usage
+
+### Define a Test (`login_test.yaml`)
+
+```yaml
+name: "User Login Flow"
+url: "https://example.com/login"
+description: "Verify that a user can log in with valid credentials."
+
+steps:
+  - action: "Type 'admin' into the username field"
+    expect: "The username field should contain 'admin'"
+  - action: "Type 'password123' into the password field"
+  - action: "Click the 'Login' button"
+    expect: "Should redirect to the dashboard and show 'Welcome back!'"
+```
+
+### Run the Test
+
+```bash
+# Run all tests in a directory
+vizqa tests/
+```
+
+### CLI Arguments
+
+| Argument | Description | Default |
+| --- | --- | --- |
+| `paths` | One or more paths to test files or directories. | (Required) |
+| `--headless / --no-headless` | Run browser in headless mode. | `True` |
+| `-v, --verbose` | Increase output verbosity (-v, -vv). | `0` |
+| `-x, --interactive` | Stop and enter interactive mode on first failure. | `False` |
+| `--report` | Generate a visual HTML report after execution. | `False` |
+
+---
+
+## Configuration
+
+vizQA supports global and per-test configuration, including custom HTTP headers for authentication or specialized testing.
+
+### Global Configuration
+You can define global headers in your `pyproject.toml` or any common `.ini` file (e.g., `pytest.ini`, `tox.ini`).
+
+**`pyproject.toml`**
+```toml
+[tool.vizqa.headers]
+Authorization = "Bearer global-api-token"
+X-Custom-Header = "GlobalValue"
+```
+
+**`pytest.ini` / `vizqa.ini`**
+```ini
+[vizqa.headers]
+Authorization = Bearer global-api-token
+X-Custom-Header = GlobalValue
+```
+
+### Per-Test Overrides
+You can specify or override headers directly in your test YAML file. These take precedence over global settings.
+
+**`my_test.yaml`**
+```yaml
+name: "Protected API Test"
+url: "https://example.com/api"
+headers:
+  Authorization: "Bearer test-specific-token"
+steps:
+  - VERIFY: "Welcome" should appear
+```
+
+---
+
+## Methodology
+
+vizQA follows a three-stage execution cycle for every step:
+
+1.  **Perception**: Takes a screenshot and sends it to the Perception API to identify all visual elements and their properties (bounds, text, color, state).
+2.  **Planning**: Uses semantic matching to understand intent and internally breaks down high-level instructions into atomic `find`, `do`, and `verify` commands to handle complex interactions.
+3.  **Execution**: Performs the interaction via Playwright using precise pixel coordinates, ensuring we interact exactly with what was "seen."
+
+---
+
+## Contributing
+
+We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for details on setting up the environment and submitting PRs.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

vizqa-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+
+[project]
+name = "vizQA"
+version = "0.1.0"
+description = "Vision-driven UI Testing Framework"
+authors = [
+    {name = "Spospider", email = "64846609+Spospider@users.noreply.github.com"}
+]
+readme = "README.md"
+requires-python = ">=3.11"
+
+dependencies = [
+    "playwright (>=1.58.0,<2.0.0)",
+    "click (>=8.1.7)",
+    "pyyaml (>=6.0.1)",
+    "rich (>=13.7.0)",
+    "httpx (>=0.27.0)",
+    "onnxruntime (>=1.24.3,<2.0.0)",
+    "tokenizers (>=0.22.2,<0.23.0)",
+    "pydantic (>=2.6.0)",
+    "tomli (>=2.0.0,<3.0.0) ; python_version < '3.11'"
+]
+
+[project.scripts]
+vizqa = "vizQA.cli:cli"
+
+[tool.pytest.ini_options]
+pythonpath = ["vizQA"]
+testpaths = ["vizQA/tests"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+packages = [
+    { include = "vizQA", from = "." }
+]
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.0.2,<10.0.0)",
+    "coverage (>=7.13.5,<8.0.0)",
+    "pytest-cov (>=7.1.0,<8.0.0)",
+    "pytest-json-report (>=1.5.0)",
+    "pylint (>=4.0.4)"
+]
+
+[tool.coverage.run]
+omit = [
+    "tests/*",
+    "*/test*/*"
+]

vizqa-0.1.0/vizQA/__init__.py

@@ -0,0 +1,2 @@
+# pylint: disable=invalid-name
+# Source package initialization