Skip to content

Installation Guide

This guide covers installing the tractusx-testlab package and its testlab CLI.

Prerequisites

Requirement Minimum Version
Python 3.12+
pip latest
OS Linux, macOS, Windows

Quick Install (PyPI)

TestLab is published on PyPI as pre-releases, so pip needs --pre:

Bash
pip install --pre tractusx-testlab

This installs the library and the testlab CLI. The Tractus-X SDK comes with it as a dependency.

To install one specific release:

Bash
pip install tractusx-testlab==1.0.0a5

Development Install (from source)

The project is managed with Poetry (>= 2.0):

Bash
git clone https://github.com/eclipse-tractusx/tractusx-testlab.git
cd tractusx-testlab
poetry install
poetry run testlab --help

poetry install installs the dev, test and docs dependency groups as well. See Development Workflow for running the tests and the docs site.

Virtual Environment

It is recommended to use a virtual environment to avoid conflicts with other Python packages.

Create and Activate

Bash
python3 -m venv .venv
source .venv/bin/activate
PowerShell
python -m venv .venv
.venv\Scripts\activate

Deactivate

Bash
deactivate

Verify Installation

After installation, confirm everything is working:

Bash
# Check the installed version
python -c "import importlib.metadata as m; print(m.version('tractusx-testlab'))"

# Check the testlab CLI
testlab --help

testlab --help lists these commands:

Command Purpose
compile Compile a TCK manifest into a .tck package
config Show the settings this engine resolved, and which of them came from the environment
docs Generate the step reference from the steps' declared input/output models
inspect Report what a .tck package contains, without executing it
keygen Generate RSA (encryption) + Ed25519 (signing) key pairs for a player identity
run Load and execute a TCK, printing results to stdout
schema Generate the TCK JSON Schemas from the authoring models
serve Start the TestLab FastAPI server via uvicorn
validate Validate a TCK manifest and its tests without compiling

Configuration

Every setting has a default, so no configuration file is needed to validate or compile. To run a TCK against a dataspace, bind the connectors and registries it requires — see testlab.config.example.yaml in the repository and Executing Tests. testlab config prints what resolved and where each value came from.

Upgrade

Bash
pip install --upgrade --pre tractusx-testlab

Uninstall

Bash
pip uninstall tractusx-testlab

Troubleshooting

testlab command not found

If testlab is not found after installation, ensure:

  1. The virtual environment is activated (if using one)
  2. The install location is on your PATH
  3. From a source checkout, run it through Poetry: poetry run testlab --help

No matching distribution found for tractusx-testlab

Only pre-releases are published so far. Add --pre, or pin a version such as tractusx-testlab==1.0.0a5.

Python version too old

TestLab requires Python 3.12+. Check your version:

Bash
python3 --version

If you need to install a newer version, use pyenv or your system package manager.