testium/README.md

testium

testium is a YAML-driven test sequencer for hardware-in-the-loop and integration testing. A test campaign is described in a .tum file as a tree of items (checks, console interactions, Python/Lua functions, parallel blocks, dialogs, …); testium executes the tree, captures results, and produces reports in several formats.

Documentation

• Quick start — install and run your first test in five minutes.
• Tutorial — guided walk-through of the most common test items with a runnable example.
• User manual (PDF) — full reference.
• doc/examples/ — runnable .tum snippets.

Pre-built releases

Pre-built artifacts are published at https://git.beafrancois.fr/v-and-v/testium/releases:

• Python wheel (testium-<version>-py3-none-any.whl) — install with pip install testium-*.whl. Lighter than the binary; pulls Python dependencies from PyPI on install.

• Self-contained Linux binary (testium, built with PyInstaller) — runnable directly, no Python installation required on the host. Lua support still needs a system lua interpreter and the lua-socket / lua-cjson modules.

• Flatpak bundle (testium.flatpak) — install with:

  # Add Flathub (once, to fetch the KDE/PySide runtimes)
  flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
  
  # Install the bundle
  flatpak install --user testium.flatpak
  

  After installation testium appears in the desktop application menu and the testium command is available in the terminal (requires ~/.local/bin in PATH, which most modern distributions provide by default).

• AppImage (Testium-<version>-x86_64.AppImage) — a single self-contained executable bundling its own Python. Make it executable and run it:

  chmod +x Testium-*-x86_64.AppImage
  ./Testium-*-x86_64.AppImage -b mytest.tum
  

  As with the binary and Flatpak, py_func / lua_func items run under the host Python / Lua so your own modules stay visible.

Every channel ships the language server, so testium lsp (see Editor support) works out of the box from any of them.

Quick start

From a checkout of the repository:

OS	Command
Linux	./run.sh
Windows (cmd)	run.bat
Windows (PowerShell)	run.ps1

The wrapper creates a Python virtual environment on first run and starts testium in GUI mode. Add -b path/to/test.tum to run a test in batch mode.

Manual installation

If the wrapper script does not fit your environment, set up testium manually:

python3 -m venv .venv
source .venv/bin/activate
pip install -r src/requirements.txt

Required Python packages (see src/requirements.txt): pyside6, pyserial, pyyaml, pexpect, gitpython, jinja2, colorama, matplotlib, junit-xml, lxml.

For tests using lua_func items, install Lua (>= 5.1) plus the socket and cjson modules. On Debian/Ubuntu:

sudo apt install lua5.4 lua-socket lua-cjson

Run testium:

python3 src/testium               # GUI
python3 src/testium -b mytest.tum # batch

Editor support

testium ships a Language Server Protocol (LSP) server that gives .tum files completion of item types, hover documentation, and an outline view in any LSP-capable editor:

testium lsp        # speaks LSP over stdio; an editor's LSP client drives it
testium schema     # dumps the item/parameter schema as JSON (what the LSP serves)

The server is bundled in every pre-built release (wheel, binary, Flatpak, AppImage). For a source / wheel install, pull the language-server extra:

pip install 'testium[lsp]'                 # from PyPI / a wheel
pip install -e /path/to/testium/src[lsp]   # from a source checkout

A VSCode / VSCodium client extension (testium_assist) wraps testium lsp; the schema is built from testium itself, so new item types and parameters appear in the editor on the next testium upgrade with no client change.

Troubleshooting

wl_proxy_marshal_flags symbol error

testium: symbol lookup error: ... undefined symbol: wl_proxy_marshal_flags

Force the X11 Qt backend:

export QT_QPA_PLATFORM=xcb
testium

xcb plugin missing

qt.qpa.plugin: Could not load the Qt platform plugin "xcb"

Install the missing system libraries:

sudo apt install libxcb-cursor0 libicu-dev libxcb-cursor-dev

License

Copyright © 2025-2026 François Dausseur.

testium is distributed under the European Union Public Licence v. 1.2 (EUPL-1.2) — see LICENSE for the full text. SPDX: EUPL-1.2.

Contributions are accepted under the same licence (inbound = outbound). See CONTRIBUTING.md for development setup, debugging workflow, and the release procedure.