Skip to content

Developer Handover — TestLab Engine

This documentation is a technical handover guide for the TestLab engine: the Python library, the testlab CLI, and the FastAPI server that compile and execute certification tests for Eclipse Tractus-X dataspaces. It covers architecture, data flow, and the patterns used throughout the codebase so that a new developer can orient quickly and contribute confidently.

There is no user interface in this repository. The YAML test files are the interface — any text editor produces them — and the server's HTTP API lets other programs compile, store, and run packages and follow executions over SSE.

Repository layout

Text Only
tractusx-testlab/
├── src/tractusx_testlab/         ← The engine: CLI, compiler, player, server, steps, …
├── tests/                        ← Pytest suite (incl. e2e/ smoke tests)
├── stubs/                        ← Disposable SUT stubs for local runs (e.g. ccm-sut)
├── docs/                         ← This documentation (MkDocs)
│   └── developer/                ← You are here
├── mkdocs.yml
└── pyproject.toml                ← Poetry project definition

See Architecture for the layer-by-layer breakdown of src/tractusx_testlab/.

Quick start

Bash
poetry install
poetry run testlab --help        # the CLI entry point
poetry run pytest                # run the test suite
poetry run mkdocs serve          # preview this documentation

Documentation structure

Page What it covers
Product Scope Mission, MVP scope boundaries, lifecycle, execution ordering, versioning, and validation model
Architecture Engine roles, package layout and imports, compile and run flow, server API
Step Contracts The single-source-of-truth contract architecture: one id, one shape per step, enforcement and anti-drift tooling
Data Models The engine's Pydantic models and the YAML document structure
Block Lifecycle How a step maps from YAML → registry → Python executor → SDK call
Creating a Step Reference for writing a new step executor and its contract
Tutorials How-to guides: step executors, service types, assertions, debugging

Tech stack

Technology Purpose
Python 3 + Poetry Language and dependency management
Pydantic v2 Data models, step contracts, validation
Typer CLI command groups
FastAPI Server API, mock endpoints, callbacks, SSE streaming
tractusx-sdk Dataspace protocol communication (connector, DTR, discovery)
pytest Test suite
MkDocs (Material) This documentation

Key design principles

  1. One canonical contract per step. One id, one set of parameter names, one output shape — declared in Pydantic next to the executor, with no aliases and no backward-compat shims. See Step Contracts.
  2. The YAML is the interface. Tests use uses: / with: / returns:; the engine validates, compiles, and runs that document, however it was written.
  3. Steps are functions. Every step has typed inputs and typed outputs, and publishes all of its return outputs — each top-level output field becomes a context variable of the same name.
  4. Delegate the protocol. Steps call tractusx-sdk services rather than re-implementing dataspace protocols.
  5. Hide plumbing. Connector services are seeded into the run context at runtime — no step names its service.
  6. Generated reference, enforced parity. The step reference page is generated from the registry, and CI fails when it drifts (testlab docs --check).