visual-regression-tracker 4.8.0__tar.gz → 5.0.0__tar.gz

visual_regression_tracker-5.0.0/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: visual_regression_tracker
+Version: 5.0.0
+Summary: Open source, self hosted solution for visual testing and managing results of visual testing.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Visual-Regression-Tracker/Visual-Regression-Tracker
+Project-URL: Source, https://github.com/Visual-Regression-Tracker/sdk-python
+Project-URL: Issues, https://github.com/Visual-Regression-Tracker/sdk-python/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.4
+Requires-Dist: dacite>=1.9
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.50; extra == "playwright"
+Dynamic: license-file
+
+# Python SDK for [Visual Regression Tracker](https://github.com/Visual-Regression-Tracker/Visual-Regression-Tracker)
+
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/0b98190cea064d6f9f1210da653ba37b)](https://www.codacy.com/gh/Visual-Regression-Tracker/sdk-python?utm_source=github.com&utm_medium=referral&utm_content=Visual-Regression-Tracker/sdk-python&utm_campaign=Badge_Grade)
+[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/0b98190cea064d6f9f1210da653ba37b)](https://www.codacy.com/gh/Visual-Regression-Tracker/sdk-python?utm_source=github.com&utm_medium=referral&utm_content=Visual-Regression-Tracker/sdk-python&utm_campaign=Badge_Coverage)
+
+Requires Python 3.10 or later. Image URLs in results need VRT server 5.0.10 or later; use 5.x of this SDK with VRT 6.0.
+
+## Install
+
+```sh
+pip install visual-regression-tracker
+
+# or, with playwright integration
+pip install "visual-regression-tracker[playwright]"
+python -m playwright install
+```
+
+## Usage
+
+### Import
+
+```python
+from visual_regression_tracker import VisualRegressionTracker, Config, TestRun, IgnoreArea
+```
+
+### Configure connection
+
+#### As python
+```python
+config = Config(
+    # apiUrl - URL where backend is running 
+    apiUrl='http://localhost:4200',
+
+    # project - Project name or ID
+    project='Default project',
+
+    # apiKey - User apiKey
+    apiKey='tXZVHX0EA4YQM1MGDD',
+
+    # ciBuildId - Current git commit SHA
+    ciBuildId='commit_sha',
+
+    # branch - Current git branch 
+    branchName='develop',
+
+    # enableSoftAssert - Log errors instead of exceptions
+    enableSoftAssert=False,
+
+    # httpTimeoutInSeconds - How long to wait for the server's answer, 0 for no limit.
+    # The server compares images while answering track(); with VLM checks or a busy
+    # comparison queue that can take minutes, so keep it above 300.
+    httpTimeoutInSeconds=360,
+)
+
+vrt = VisualRegressionTracker(config)
+```
+
+#### Or, as JSON config file `vrt.json`
+```json
+{
+    "apiUrl":"http://localhost:4200",
+    "project":"Default project",
+    "apiKey":"tXZVHX0EA4YQM1MGDD",
+    "ciBuildId":"commit_sha",
+    "branchName":"develop",
+    "enableSoftAssert":false,
+    "httpTimeoutInSeconds":360
+}
+```
+
+`vrt.json` is read from the current working directory.
+```python
+vrt = VisualRegressionTracker()
+```
+
+#### Or, as environment variables
+```sh
+VRT_APIURL="http://localhost:4200" \
+VRT_PROJECT="Default project" \
+VRT_APIKEY="tXZVHX0EA4YQM1MGDD" \
+VRT_CIBUILDID="commit_sha" \
+VRT_BRANCHNAME="develop" \
+VRT_ENABLESOFTASSERT=true \
+VRT_HTTPTIMEOUTINSECONDS=360 \
+    python
+```
+Empty variables are ignored.
+```python
+vrt = VisualRegressionTracker()
+```
+
+### Setup / Teardown
+
+As context manager:
+```python
+with vrt:
+    ...
+    # track test runs
+    ...
+```
+
+Without context manager:
+```python
+build = vrt.start()  # Build(id, projectId)
+...
+# track test runs
+...
+vrt.stop()
+```
+
+### Assert
+
+```python
+result = vrt.track(TestRun(
+    # Name to be displayed
+    # Required
+    name='Image name',
+
+    # Base64 encoded string
+    # Required
+    imageBase64=image,
+
+    # Allowed mismatch tollerance in %
+    # Optional
+    # Default: 0%
+    diffTollerancePercent=1,
+
+    # Optional
+    os='Mac',
+
+    # Optional
+    browser='Chrome',
+
+    # Optional
+    viewport='800x600',
+
+    # Optional
+    device='PC',
+
+    # Array of areas to be ignored
+    ignoreAreas=[
+        IgnoreArea(
+            # X-coordinate relative of left upper corner
+            # Required
+            x=10,
+            # Y-coordinate relative of left upper corner
+            # Required
+            y=20,
+            # Area width in px
+            # Required
+            width=300,
+            # Height width in px
+            # Required
+            height=400
+        )
+    ],
+))
+```
+
+`track` returns a `TestRunResult`: `testRunResponse` (with `status` and the `url` of the test run in the
+VRT app) and `imageUrl`, `diffUrl`, `baselineUrl`.
+
+`track` raises `TestRunError` when the status is `new` (no baseline yet) or `unresolved` (difference found);
+with `enableSoftAssert` it logs the error instead. `ok`, `approved` and `autoApproved` pass; `failed` passes
+too, as in the JavaScript SDK. A status this SDK does not know becomes `TestRunStatus.UNKNOWN`.
+
+An HTTP error from the server raises `ServerError` with `status_code` and the server's `message`.
+A request that gets no answer (connection refused, connect timeout after 10 s, read timeout after
+`httpTimeoutInSeconds`) raises `RequestError` with the `url`. A read timeout on `track` does not mean
+the server dropped the test run: it may still be stored.
+
+### Integration with Microsoft Playwright
+
+#### Imports
+```python
+from playwright.sync_api import sync_playwright
+from visual_regression_tracker import Config
+from visual_regression_tracker.playwright import PlaywrightVisualRegressionTracker
+```
+
+#### Start playwright and navigate to page
+```python
+playwright = sync_playwright().start()
+browserType = playwright.chromium
+browser = browserType.launch(headless=False)
+page = browser.new_page()
+page.goto('https://www.python.org/')
+```
+
+#### Configure connection to VRT server
+```python
+vrt = PlaywrightVisualRegressionTracker(browserType, config)
+```
+
+#### Setup / Tear down
+
+As context manager:
+```python
+with vrt:
+    ...
+    # track test runs
+    ...
+```
+
+Without context manager:
+```python
+vrt.start()
+...
+# track test runs
+...
+vrt.stop()
+```
+
+#### Track page
+```python
+result = vrt.trackPage(page, imageName[, options])
+```
+
+- `page: Page` [Playwright page](https://playwright.dev/python/docs/api/class-page)
+
+- `imageName: str` name for the taken screenshot image
+
+- `options: PageTrackOptions` optional configuration with:
+  - `diffTollerancePercent: float` specify acceptable difference from baseline, between `0-100`.
+
+  - `ignoreAreas: List[IgnoreArea]` 
+    - `x: int`  X-coordinate relative of left upper corner
+    - `y: int`  Y-coordinate relative of left upper corner
+    - `width: int`  area width in px
+    - `height: int` area height in px
+
+  - `screenshotOptions: PageScreenshotOptions` configuration for Playwrights `screenshot` method
+    - `full_page: bool`  When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to `false`.
+
+    - `omit_background: bool`  Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
+
+    - `clip: FloatRect` An object which specifies clipping of the resulting image. Should have the following fields:
+
+      - `x: float` x-coordinate of top-left corner of clip area
+      - `y: float` y-coordinate of top-left corner of clip area
+      - `width: float` width of clipping area
+      - `height: float` height of clipping area
+
+    - `timeout: float` Maximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout.
+
+  - `agent: Agent` Additional information to mark baseline across agents that have different:
+    - `os: str`  operating system name, like Windows, Mac, etc.
+    - `device: str`  device name, PC identifier, mobile identifier etc.
+    - `viewport: str` viewport size.
+
+#### Track element handle
+```python
+result = vrt.trackElementHandle(elementHandle, imageName[, options])
+```
+
+The async API has `trackPageAsync` and `trackElementHandleAsync`. All four return the same `TestRunResult` as `track`.
+
+- `elementHandle: ElementHandle` [Playwright ElementHandle](https://playwright.dev/python/docs/api/class-elementhandle)
+
+- `imageName: str` name for the taken screenshot image
+
+- `options: ElementHandleTrackOptions` optional configuration with:
+  - `diffTollerancePercent: float` specify acceptable difference from baseline, between `0-100`.
+
+  - `ignoreAreas: List[IgnoreArea]` 
+    - `x: int`  X-coordinate relative of left upper corner
+    - `y: int`  Y-coordinate relative of left upper corner
+    - `width: int`  area width in px
+    - `height: int` area height in px
+
+  - `screenshotOptions: ElementHandleScreenshotOptions` configuration for Playwrights `screenshot` method
+
+    - `omit_background: bool`  Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
+
+    - `timeout: float` Maximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout.
+
+  - `agent: Agent` Additional information to mark baseline across agents that have different:
+    - `os: str`  operating system name, like Windows, Mac, etc.
+    - `device: str`  device name, PC identifier, mobile identifier etc.
+    - `viewport: str` viewport size.
+
+## Development
+
+```sh
+pip install -e '.[playwright]' -r requirements.txt
+python -m playwright install chromium
+python -m pytest
+```

{visual_regression_tracker-4.8.0 → visual_regression_tracker-5.0.0}/README.md

@@ -3,13 +3,15 @@
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/0b98190cea064d6f9f1210da653ba37b)](https://www.codacy.com/gh/Visual-Regression-Tracker/sdk-python?utm_source=github.com&utm_medium=referral&utm_content=Visual-Regression-Tracker/sdk-python&utm_campaign=Badge_Grade)
 [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/0b98190cea064d6f9f1210da653ba37b)](https://www.codacy.com/gh/Visual-Regression-Tracker/sdk-python?utm_source=github.com&utm_medium=referral&utm_content=Visual-Regression-Tracker/sdk-python&utm_campaign=Badge_Coverage)
 
+Requires Python 3.10 or later. Image URLs in results need VRT server 5.0.10 or later; use 5.x of this SDK with VRT 6.0.
+
 ## Install
 
-```python
+```sh
 pip install visual-regression-tracker
 
 # or, with playwright integration
-pip install visual-regression-tracker[playwright]
+pip install "visual-regression-tracker[playwright]"
 python -m playwright install
 ```
 
@@ -18,7 +20,7 @@ python -m playwright install
 ### Import
 
 ```python
-from visual_regression_tracker import VisualRegressionTracker, Config, TestRun
+from visual_regression_tracker import VisualRegressionTracker, Config, TestRun, IgnoreArea
 ```
 
 ### Configure connection
@@ -43,6 +45,11 @@ config = Config(
 
     # enableSoftAssert - Log errors instead of exceptions
     enableSoftAssert=False,
+
+    # httpTimeoutInSeconds - How long to wait for the server's answer, 0 for no limit.
+    # The server compares images while answering track(); with VLM checks or a busy
+    # comparison queue that can take minutes, so keep it above 300.
+    httpTimeoutInSeconds=360,
 )
 
 vrt = VisualRegressionTracker(config)
@@ -56,9 +63,12 @@ vrt = VisualRegressionTracker(config)
     "apiKey":"tXZVHX0EA4YQM1MGDD",
     "ciBuildId":"commit_sha",
     "branchName":"develop",
-    "enableSoftAssert":false
+    "enableSoftAssert":false,
+    "httpTimeoutInSeconds":360
 }
 ```
+
+`vrt.json` is read from the current working directory.
 ```python
 vrt = VisualRegressionTracker()
 ```
@@ -71,8 +81,10 @@ VRT_APIKEY="tXZVHX0EA4YQM1MGDD" \
 VRT_CIBUILDID="commit_sha" \
 VRT_BRANCHNAME="develop" \
 VRT_ENABLESOFTASSERT=true \
+VRT_HTTPTIMEOUTINSECONDS=360 \
     python
 ```
+Empty variables are ignored.
 ```python
 vrt = VisualRegressionTracker()
 ```
@@ -89,7 +101,7 @@ with vrt:
 
 Without context manager:
 ```python
-vrt.start()
+build = vrt.start()  # Build(id, projectId)
 ...
 # track test runs
 ...
@@ -99,7 +111,7 @@ vrt.stop()
 ### Assert
 
 ```python
-vrt.track(TestRun(
+result = vrt.track(TestRun(
     # Name to be displayed
     # Required
     name='Image name',
@@ -145,13 +157,25 @@ vrt.track(TestRun(
 ))
 ```
 
+`track` returns a `TestRunResult`: `testRunResponse` (with `status` and the `url` of the test run in the
+VRT app) and `imageUrl`, `diffUrl`, `baselineUrl`.
+
+`track` raises `TestRunError` when the status is `new` (no baseline yet) or `unresolved` (difference found);
+with `enableSoftAssert` it logs the error instead. `ok`, `approved` and `autoApproved` pass; `failed` passes
+too, as in the JavaScript SDK. A status this SDK does not know becomes `TestRunStatus.UNKNOWN`.
+
+An HTTP error from the server raises `ServerError` with `status_code` and the server's `message`.
+A request that gets no answer (connection refused, connect timeout after 10 s, read timeout after
+`httpTimeoutInSeconds`) raises `RequestError` with the `url`. A read timeout on `track` does not mean
+the server dropped the test run: it may still be stored.
+
 ### Integration with Microsoft Playwright
 
 #### Imports
 ```python
-from playwright import sync_playwright
-from visual_regression_tracker import Config, TestRun
-from visual_regression_tracker.p import PlaywrightVisualRegressionTracker
+from playwright.sync_api import sync_playwright
+from visual_regression_tracker import Config
+from visual_regression_tracker.playwright import PlaywrightVisualRegressionTracker
 ```
 
 #### Start playwright and navigate to page
@@ -159,7 +183,7 @@ from visual_regression_tracker.p import PlaywrightVisualRegressionTracker
 playwright = sync_playwright().start()
 browserType = playwright.chromium
 browser = browserType.launch(headless=False)
-page = browser.newPage()
+page = browser.new_page()
 page.goto('https://www.python.org/')
 ```
 
@@ -189,10 +213,10 @@ vrt.stop()
 
 #### Track page
 ```python
-vrt.trackPage(page, imageName[, options])
+result = vrt.trackPage(page, imageName[, options])
 ```
 
-- `page: Page` [Playwright page](https://microsoft.github.io/playwright-python/sync_api.html#playwright.sync_api.Page)
+- `page: Page` [Playwright page](https://playwright.dev/python/docs/api/class-page)
 
 - `imageName: str` name for the taken screenshot image
 
@@ -206,7 +230,7 @@ vrt.trackPage(page, imageName[, options])
     - `height: int` area height in px
 
   - `screenshotOptions: PageScreenshotOptions` configuration for Playwrights `screenshot` method
-    - `full_page: bool`  When true, takes a screenshot of the full scrollable page, instead of the currently visibvle viewport. Defaults to `false`.
+    - `full_page: bool`  When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to `false`.
 
     - `omit_background: bool`  Hides default white background and allows capturing screenshots with transparency. Defaults to `false`.
 
@@ -226,10 +250,12 @@ vrt.trackPage(page, imageName[, options])
 
 #### Track element handle
 ```python
-vrt.trackElementHandle(elementHandle, imageName[, options])
+result = vrt.trackElementHandle(elementHandle, imageName[, options])
 ```
 
-- `elementHandle: ElementHandle` [Playwright ElementHandle](https://microsoft.github.io/playwright-python/sync_api.html#playwright.sync_api.ElementHandle)
+The async API has `trackPageAsync` and `trackElementHandleAsync`. All four return the same `TestRunResult` as `track`.
+
+- `elementHandle: ElementHandle` [Playwright ElementHandle](https://playwright.dev/python/docs/api/class-elementhandle)
 
 - `imageName: str` name for the taken screenshot image
 
@@ -252,3 +278,11 @@ vrt.trackElementHandle(elementHandle, imageName[, options])
     - `os: str`  operating system name, like Windows, Mac, etc.
     - `device: str`  device name, PC identifier, mobile identifier etc.
     - `viewport: str` viewport size.
+
+## Development
+
+```sh
+pip install -e '.[playwright]' -r requirements.txt
+python -m playwright install chromium
+python -m pytest
+```

visual_regression_tracker-5.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "visual_regression_tracker"
+version = "5.0.0"
+description = "Open source, self hosted solution for visual testing and managing results of visual testing."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.32.4",
+    "dacite>=1.9",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.optional-dependencies]
+playwright = ["playwright>=1.50"]
+
+[project.urls]
+Homepage = "https://github.com/Visual-Regression-Tracker/Visual-Regression-Tracker"
+Source = "https://github.com/Visual-Regression-Tracker/sdk-python"
+Issues = "https://github.com/Visual-Regression-Tracker/sdk-python/issues"
+
+[tool.setuptools]
+packages = ["visual_regression_tracker"]
+
+[tool.pytest.ini_options]
+python_classes = "NoThanks"
+junit_family = "xunit2"
+asyncio_default_fixture_loop_scope = "function"

visual_regression_tracker-5.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+