Windows

This directory is a Testudos runtime SDK compressed package: the engine, agent injector, Python wheel, a pre-built example application (Qt runtime included), example source, and E2E tests.

The example AUT ships ready to run under example\test_app_runtime\. You do not need Qt installed to start the example app itself. You still need Qt 6 on the host for testudos_engine and the Python wheel (same CPU architecture as this package).

All commands assume your shell is in the package root (the folder that contains bin\, lib\, python\, example\, and this README.md). Use x64 / ARM64 Native Tools Command Prompt for VS unless noted otherwise.

What is included

Path	Contents
`bin\`	`testudos_engine.exe`
`lib\`	`testudos-agent-injector-windows.dll`
`python\`	`testudos-*.whl` Python SDK
`example\test_app_runtime\`	Pre-built Qt Quick example AUT (`testudos_test_app.exe` + included Qt)
`example\test_app\`	Example AUT source (optional rebuild / reference)
`example\tests\`	Python E2E test suite (profile name `ExampleTestApp`)
`example\helpers\`	Scripts for optional image baseline generation

What you need to provide

Requirement	Used for
Python 3 + `pip`	Install the wheel and run tests
Qt 6 (MSVC kit)	Run `testudos_engine` and load the Python SDK native module - configure in step 0

Verify the package

dir .\bin\testudos_engine.exe
dir .\lib\testudos-agent-injector-windows.dll
dir .\python\testudos-*.whl
dir .\example\test_app_runtime\bin\testudos_test_app.exe
dir .\example\tests\

If the wheel is missing, contact us.

0. Qt runtime (set up first)

testudos_engine, pytest, and the Python wheel load Qt DLLs from your host Qt 6 MSVC kit. Without QT_PATH and PATH, engine startup and tests fail with errors such as Missing Qt6Core.dll.

Point QT_PATH at your Qt 6 MSVC kit. Use the kit that matches this package (msvc2022_64 on x64, msvc2022_arm64 on ARM64). Example:

set QT_PATH=C:\Qt\6.8.3\msvc2022_arm64
set PATH=%QT_PATH%\bin;%PATH%

For the engine GUI (not required for headless tests), also set:

set QT_PLUGIN_PATH=%QT_PATH%\plugins
set QML2_IMPORT_PATH=%QT_PATH%\qml

Quick check (run from the package root after setting QT_PATH and PATH):

.\bin\testudos_engine.exe --help

Run these commands in each terminal where you start the engine or run tests (or add them to a local env.cmd you call once per session).

The machine also needs the Visual C++ Redistributable matching the MSVC version used to build this package.

1. Install the Python SDK

Use a local virtual environment in the package directory (recommended). This does not install Testudos into your system Python.

python -m venv .venv
.\.venv\Scripts\activate

python -m pip install -U pip pytest pillow
python -m pip install python\testudos-<version>.whl
python -c "import testudos; print(testudos.__file__)"
deactivate

2. Example application (pre-built)

The sample application binary is located at example\test_app_runtime\:

.\example\test_app_runtime\bin\testudos_test_app.exe

Optional: rebuild from source

Source is included at example\test_app\ if you want to modify or rebuild the example against your own Qt 6 MSVC kit:

cmake -S .\example\test_app -B .\example\test_app\build
cmake --build .\example\test_app\build --config Release

Binary (typical): .\example\test_app\build\Release\testudos_test_app.exe

If you use a rebuilt binary, point --aut-path / --aut-workdir at that build output instead of test_app_runtime in step 3.

If CMake cannot find Qt, set CMAKE_PREFIX_PATH or QT_PATH as in Qt runtime (set up first), to the full kit path (the folder that contains bin\, lib\, and plugins\), not the top-level Qt install directory.

3. Register the example with the engine

The included tests expect an AUT profile named ExampleTestApp. Register it once; settings are saved to %LOCALAPPDATA%\testudos\config.json.

Option A - command line (recommended)

From the package root (cmd.exe - x64 or ARM64 Native Tools Command Prompt):

set "AUT=%CD%\example\test_app_runtime\bin\testudos_test_app.exe"
set "WORKDIR=%CD%\example\test_app_runtime\bin"
set "LIBDIR=%CD%\lib"

.\bin\testudos_engine.exe ^
  --write-config ^
  --aut-name=ExampleTestApp ^
  --aut-path="%AUT%" ^
  --aut-workdir="%WORKDIR%" ^
  --set-testudos-dir="%LIBDIR%"

If you rebuilt from source, change AUT and WORKDIR to your build output paths instead.

--set-testudos-dir must point at this package’s lib\ directory so the engine can find the agent injector.

Option B - engine GUI

.\bin\testudos_engine.exe

Use the UI to set the AUT binary, working directory, and Testudos library directory, then save. Useful for exploring the object tree before writing tests.

4. Start the engine

For automated tests, run the engine in headless mode in one terminal and leave it running.

.\bin\testudos_engine.exe --headless --host=127.0.0.1 --port=4322

Use the same host and port in your test environment (step 5).

5. Run example tests

In a second terminal, activate the venv from step 1 and run pytest.

.\.venv\Scripts\activate.bat

set TESTUDOS_ENGINE_HOST=127.0.0.1
set TESTUDOS_ENGINE_PORT=4322

python -m pytest .\example\tests -v

The suite covers buttons, inputs, signals, object search, mouse/drag, C++ properties, AUT arguments, popup windows, and optional image comparison.

Image comparison tests (optional)

Screenshot baseline PNGs are not shipped in this package. Tests in test_tabs_images.py skip when baselines are missing under example\images\.

To generate baselines after the engine is running and ExampleTestApp is registered, run the included helper:

.\.venv\Scripts\activate.bat

python .\example\helpers\update_main_screen_baseline.py ^
  --host 127.0.0.1 ^
  --port 4322 ^
  --aut-name ExampleTestApp ^
  --images-dir .\example\images\local

Re-run pytest; image tests will run when the expected files exist.

Troubleshooting

Error	What to do
Missing `Qt6Core.dll` / similar when starting the engine or pytest	Set `QT_PATH` to your Qt 6 MSVC kit and run `set PATH=%QT_PATH%\bin;%PATH%` (see Qt runtime (set up first)). The included AUT under `example\test_app_runtime\` does not need this.
`ModuleNotFoundError: No module named 'testudos'`	Activate `.venv` and install the wheel (step 1).
`DLL load failed` when running pytest	Set `QT_PATH` and add `%QT_PATH%\bin` to `PATH` (see Qt runtime (set up first)).
`Engine unreachable` / `Connection refused`	Start the headless engine (step 4). Match `TESTUDOS_ENGINE_HOST` and `TESTUDOS_ENGINE_PORT`.
`Unknown AUT name: …`	Register `ExampleTestApp` (step 3), then restart the engine.
AUT crashes on start / exits immediately	For the pre-built runtime, confirm `.\example\test_app_runtime\bin\testudos_test_app.exe` runs standalone. For a rebuilt binary, set `QT_PATH` and `PATH` first.
`Could not find Qt6` during CMake configure	Set `CMAKE_PREFIX_PATH` to the full Qt kit path (optional rebuild, step 2).
Example binary not found	Check `.\example\test_app_runtime\bin\testudos_test_app.exe` exists, or rebuild from `example\test_app\` source.
Injector / start AUT errors	Ensure `--set-testudos-dir` points at this package’s `lib\` directory.
Missing MSVC runtime DLLs	Install the matching Visual C++ Redistributable.
Image tests skipped	Expected without baselines; see Image comparison tests.

Registering your own application

Replace ExampleTestApp with your profile name and point --aut-path / --aut-workdir at your AUT binary and its working directory. Keep --set-testudos-dir on this package’s lib\.

Ensure QT_PATH and PATH are set in any terminal where you run the engine (see Qt runtime (set up first)).

You can register multiple profiles with separate --write-config invocations (different --aut-name values).