Linux

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).

What is included

Path	Contents
`bin/`	`testudos_engine`
`lib/`	`libtestudos-agent-injector-linux.so*` and native libraries
`python/`	`testudos-*.whl` Python SDK
`example/test_app_runtime/`	Pre-built Qt Quick example AUT (`testudos_test_app` + 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 (full kit)	Run `testudos_engine` and load the Python SDK native module - configure in step 0

Verify the package

ls ./bin/testudos_engine
ls ./lib/libtestudos-agent-injector-linux.so*
ls ./python/testudos-*.whl
ls ./example/test_app_runtime/bin/testudos_test_app
ls ./example/tests/

If the wheel is missing, contact us.

0. Qt runtime (set up first)

testudos_engine, pytest, and the Python wheel load Qt shared libraries from your host Qt 6 kit. Without QT_PATH and LD_LIBRARY_PATH, engine startup and tests fail with errors such as libQt6*.so.6: cannot open shared object file.

Point QT_PATH at your Qt 6 kit prefix (the directory that contains lib/, bin/, and plugins/). Example:

export QT_PATH="~/Qt/6.8.0/gcc_64"
export LD_LIBRARY_PATH="$QT_PATH/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"

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

export QT_PLUGIN_PATH="$QT_PATH/plugins"
export QML2_IMPORT_PATH="$QT_PATH/qml"

Quick check (run from the package root after exporting):

ldd ./bin/testudos_engine | grep -E 'Qt6|not found'
./bin/testudos_engine --help

Make Qt settings permanent (one-time)

Append the exports to your shell profile so every new terminal has them. Edit QT_PATH in the block below, then run:

cat >> ~/.bashrc <<'EOF'

# Testudos host Qt 6 kit
export QT_PATH="/your/path/to/Qt"
export LD_LIBRARY_PATH="$QT_PATH/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
export QT_PLUGIN_PATH="$QT_PATH/plugins"
export QML2_IMPORT_PATH="$QT_PATH/qml"
EOF

source ~/.bashrc

Use ~/.profile instead of ~/.bashrc if your login shell does not read .bashrc.

1. Install the Python SDK

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

python3 -m venv .venv
source .venv/bin/activate

python -m pip install -U pip pytest pillow
python -m pip install ./python/testudos-*.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

It should start without setting QT_PATH or LD_LIBRARY_PATH.

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 kit:

cmake -S ./example/test_app -B ./example/test_app/build
cmake --build ./example/test_app/build

Binary: ./example/test_app/build/testudos_test_app

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

3. Register the example with the engine

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

Option A - command line (recommended)

AUT="$(realpath ./example/test_app_runtime/bin/testudos_test_app)"
WORKDIR="$(realpath ./example/test_app_runtime/bin)"
LIB="$(realpath ./lib)"

./bin/testudos_engine --write-config --set-testudos-dir "$LIB"

./bin/testudos_engine --write-config \
  --aut-name ExampleTestApp --aut-path "$AUT" --aut-workdir "$WORKDIR"

./bin/testudos_engine --write-config \
  --aut-name ProfileA --aut-path "$AUT" --aut-workdir "$WORKDIR" \
  --aut-args 'arg1 "arg two"'

./bin/testudos_engine --write-config \
  --aut-name ProfileB --aut-path "$AUT" --aut-workdir "$WORKDIR" \
  --aut-args '--x 123'

--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

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 --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 (Qt variables from step 0 must be set in this shell).

export TESTUDOS_ENGINE_HOST=127.0.0.1
export TESTUDOS_ENGINE_PORT=4322

source .venv/bin/activate
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:

source .venv/bin/activate

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
`error while loading shared libraries: libQt6*.so.6` (engine or pytest)	Complete step 0: set `QT_PATH` and `LD_LIBRARY_PATH`, or append them to `~/.bashrc` and run `source ~/.bashrc`. 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).
`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.
Example binary not found	Check `./example/test_app_runtime/bin/testudos_test_app` exists, or rebuild from `example/test_app/` source.
Injector / start AUT errors	Ensure `--set-testudos-dir` points at this package’s `lib/` directory.
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/.

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