VisionTrace

What it is

VisionTrace is an internal Python-based system-test framework. It records UI workflows against a Windows desktop app once, then replays them in CI by driving Windows UI Automation (UIA) directly. AI verification steps (via Anthropic Claude) compare the on-screen state against natural-language assertions, producing both a pass/fail and a written justification for the audit trail.

VisionTrace is what lets us write tests like “ST-001: Local clinic visible in Patients menu” once, in plain English plus a recorded click sequence, and have CI execute them deterministically against a freshly-installed BioFlow Pro on every PR.

Why we chose to build it

Off-the-shelf UI-automation tools (Selenium, Playwright, Squish, WinAppDriver) are either web-only or extremely heavyweight, and none combine natural-language verification steps with structured Allure output ready for audit. VisionTrace fills the gap with:

• Record-once / replay-many: one human records the test interactively; CI runs it on every PR
• AI verification for stateful UI assertions that would be brittle if expressed as XPath / element queries (e.g. “the clinics dropdown is open and the local clinic entry is visible”)
• Native Windows UIA for the click/type primitives — no DOM, no shim layer, drives the same UIA tree assistive-technology software uses
• First-class Allure integration so each test result lands in the dashboard with screenshots, recorded videos, the full LLM reasoning, and per-step breakdowns
• StrictDoc-aware via the @visiontrace_test_case("ST-NNN") marker, which carries the test’s StrictDoc UID into the Allure result so the post-processor can join it to the spec

Where it lives

• Source repo: Corona-Project-Life/VisionTrace (formerly UIATest)
• Distributed as: a Python package, installed via pip install from the private repo. CI installs it via uv pip install "visiontrace[dev] @ git+https://...@main". The token used for installation in CI is the VISIONTRACE_TOKEN repo secret.
• Recorded test artefacts in this repo: visiontrace_tests/ — every recorded ST workflow lives under visiontrace_tests/<product>/<test-id>/, carrying both the recorded .yaml workflow and the generated .py test file plus reference screenshots.
• BioFlow-side fixtures: visiontrace_tests/conftest.py — the autouse ensure_licensed fixture that activates the BioFlow license on first launch in CI

How to operate it

Local development

Install in editable mode from a local clone of the VisionTrace repo (only needed if you’re developing VisionTrace itself):

uv pip install -e "C:\Users\<you>\Documents\UIATest[dev]"

For consumers (just running tests), install from the published Git ref:

uv pip install "visiontrace[dev] @ git+https://github.com/Corona-Project-Life/VisionTrace.git@main"

Run a single recorded ST test:

uv run pytest visiontrace_tests/bioflow/st001/ \
  --alluredir test-results/allure-results --clean-alluredir

Always pass --clean-alluredir — without it, prior runs accumulate as duplicate entries in the Allure dashboard.

Recording a new test

Use VisionTrace’s own visiontrace-record CLI (documented in the VisionTrace repo). The recorder produces a .yaml workflow file and the matching .py test file under the chosen folder. After recording, set the StrictDoc UID via the @visiontrace_test_case("ST-NNN") decorator so Allure / the post-processor pick up the linkage.

Required environment variables

When running locally or in CI:

Variable	Purpose
ANTHROPIC_API_KEY	API key for the LLM-driven verification steps
APP_EXE_PATH	Absolute path to the executable to launch (e.g. C:\Program Files\BioFlow Pro\bioflow.exe). Defaults to notepad.exe if unset — explicitly setting it prevents tests from accidentally running against the wrong app.
BIOFLOW_CI_LICENSE_KEY	License key used by the ensure_licensed fixture to activate BioFlow on first launch. Only needed against fresh installs.

Versioning / update policy

• VisionTrace is pinned in CI by Git ref (@main or a specific tag). Pin to a tag in pr_branch_tests.yml’s Install VisionTrace step before regulated releases.
• Regulated SOUP — version pin and any bump go through the standard SOUP register procedure
• VisionTrace exposes its fixtures via a pytest plugin (pytest11 entry point) so consuming repos pick them up automatically — no conftest.py boilerplate needed beyond product-specific overrides

External documentation

VisionTrace’s source repository (Corona-Project-Life/VisionTrace) carries its own README and per-module docstrings — that’s the canonical reference for the recorder, the agent API, the verification mechanics, and the configuration surface. This page covers only how VisionTrace fits into TRACE ALM — how it’s installed, parameterised, and integrated with Allure and the post-processor.