Fernsteuern von ecu.test¶

Derzeit gibt es nachfolgende Möglichkeiten, um ecu.test automatisiert über eine andere Software auszuführen:

per Kommandozeile
per COM API
per REST API
per ecu.test execution plugin

All diese Mechanismen greifen intern über eine lokale Netzwerkverbindung auf die laufende ecu.test-Instanz zu.

Dabei wird standardmäßig die Portnummer 8000 verwendet.

Falls diese Portnummer durch ein anderes Programm bereits belegt ist, kann durch manuelles Erstellen eines Registry-Werts eine andere Portnummer festgelegt werden:

Unter HKEY_LOCAL_MACHINE/Software/tracetronic/ecu.test 2025.3 muss zu diesem Zweck ein DWORD-Wert xmlrpcPort mit der gewünschten Portnummer erstellt werden. Um die Einstellung für einen einzelnen Benutzer abweichend von der systemweiten Einstellung festzulegen, muss HKEY_CURRENT_USER anstelle von HKEY_LOCAL_MACHINE verwendet werden.

Unter Windows stehen explizit zwei Varianten zur Verfügung:

Instanz mit grafischer Benutzeroberfläche: ecu.test.exe
Runner als Konsolenanwendung: ecu.test_runner.exe

Kommandozeile (Batch-Schnittstelle)¶

Über die Kommandozeile kann ecu.test automatisiert gestartet und gesteuert werden. Es kann beispielsweise eine Testkonfiguration und Testbenchkonfiguration angegeben und geladen werden. Außerdem können Packages oder Projekte geöffnet und ausgeführt werden.

ecu.test kann sowohl unter Windows, als auch unter Linux oder im Docker-Container über das Kommandozeileninterface gesteuert werden.

Ausführen eines Packages oder Projektes¶

Mit dem Unterbefehl execute kann mit einem einzelnen Aufruf ecu.test gestartet, ein Package oder Projekt ausgeführt und anschließend ecu.test wieder beendet werden.

Argumente¶

Argument	Beschreibung	Anmerkungen
`--help` oder `-h`	[optional] Hilfe zur Verwendung des Unterbefehls ausgeben	Listet alle Argumente dieses Befehls auf
`--workspace WORKSPACE`	Der Pfad zum ecu.test Workspace, der für die Ausführung verwendet werden soll	Absoluter Pfad oder relativ zum `cwd`
`--testconfiguration TCF`	[optional] Pfad zur Testkonfiguration, die für die Ausführung verwendet werden soll	Erlaubt sind absolute Pfade, Pfade relativ zum Konfigurationsverzeichnis (in den Einstellungen des verwendeten Workspace angegeben), sowie Library-Pfade im Format `<libraries.namespace.configurations>/Dateiname.tcf`.
`--testbenchconfiguration TBC`	[optional] Pfad zur Testbenchkonfiguration, die für die Ausführung verwendet werden soll	Erlaubt sind absolute Pfade, Pfade relativ zum Konfigurationsverzeichnis (in den Einstellungen des verwendeten Workspace angegeben), sowie Library-Pfade im Format `<libraries.namespace.configurations>/Dateiname.tbc`.
`--reportdirectory REPORTDIR`	[optional] Pfad zu einem leeren Verzeichnis, in dem die Report-Dateien gespeichert werden sollen	Absoluter Pfad oder relativ zum `cwd`
`TARGET`	Pfad zum Package oder Projekt, welches ausgeführt werden soll	Erlaubt sind absolute Pfade, Pfade relativ zum Packages-Verzeichnis (in den Einstellungen des verwendeten Workspace angegeben), sowie Library-Pfade im Format `<libraries.namespace.configurations>/PackageName`.

Rückgabewerte¶

Der Befehl kehrt bei Verwendung von ecu.test mit GUI sofort und immer mit dem Rückgabewert 0 zurück.

Bei Verwendung von ecu.test ohne GUI wird die Log-Ausgabe in der Konsole ausgegeben und der Befehl kehrt entweder nach einem Fehler (Rückgabewert 1) oder nach Abschluss des Tests mit einem Rückgabewert zurück, der im Zusammenhang mit dem Testergebnis steht.

Die möglichen Rückgabewerte für diesen Fall sind in folgender Tabelle aufgelistet.

Rückgabewert	Beschreibung	Anmerkungen
`0`	Der ausgeführte Test hat das Ergebnis SUCCESS oder NONE
`2`	Der ausgeführte Test hat das Ergebnis INCONCLUSIVE
`3`	Der ausgeführte Test hat das Ergebnis FAILED
`4`	Der ausgeführte Test hat das Ergebnis ERROR
`1`	Es ist ein Fehler bei der Ausführung aufgetreten. Das Kommando konnte nicht korrekt ausgeführt werden.	Informationen zur Fehlerursache können dem Log entnommen werden.

Info

In der Windows-Kommandozeile kann der Rückgabewert des zuletzt ausgeführten Befehls mittels echo %errorlevel% ermittelt werden.

Beispiele¶

Alle Pfade müssen stets plattformspezifisch angegeben werden.

Somit könnte ein Kommando unter Windows beispielsweise wiefolgt aussehen:

ecu.test execute --workspace C:/Data/ecu.test --testbenchconfiguration local.tbc --testconfiguration myTCF.tcf myPackage.pkg

Unter Linux sieht ein Beispielkommando demnach wiefolgt aus:

ecu.test execute --workspace /home/Data/ecu.test --testbenchconfiguration sub/local.tbc --testconfiguration myTCF.tcf subFolder/myPackage.pkg

Steuern einer ecu.test-Instanz¶

ecu.test kann automatisch per Kommandozeile mit einer Konfiguration und einem Package oder Projekt gestartet werden, das dann ausgeführt werden kann. Wenn ecu.test bereits läuft, wird diese Instanz verwendet.

Argumente¶

Alle Argumente können beliebig kombiniert werden. Im Falle der Testkonfiguration und Testbenchkonfiguration ist es ratsam, diese in einem Kommando gemeinsam zu definieren.

Argument	Beschreibung	Anmerkungen
`-h` oder `--help`	Hilfe für das Kommandozeileninterface ausgeben
`-s "C:/Data/ecu.test/settings"`	Verwendung eines anderen Einstellungsverzeichnisses statt `%AppData%/tracetronic/ecu.test x.y/`	z.B. für `localsettings.xml`, diverse Caches, etc.
`--toollibsini "C:/.../ToolLibs.ini"`	Angeben einer anderen ToolLibs.ini
`--workspaceDir "C:/.../workspace"`	Starten in einem bestimmten Workspace
`-w` oder `--wait`	Warten, bis eine gestartete Instanz von ecu.test bereit ist
`-c "C:/Data/ecu.test/Configurations/empty.tcf"`	Laden einer Testkonfiguration
`-b "C:/Data/ecu.test/Configurations/local.tbc"`	Laden einer Testbenchkonfiguration	Beim Laden von Konfigurationsdateien wird nach Start von ecu.test die Konfiguration geladen und weder der Test- noch der Testbench-Konfigurationseditor geöffnet.
`-o "C:/Data/ecu.test/Packages/loop.pkg"`	Öffnen eines Packages oder Projektes, Testreports oder einer Test(bench)konfiguration
`-u "tracetronic:///C:/Data/ecu.test/Packages/loop.pkg"`	Öffnen eines Packages oder Projektes, Testreports oder einer Test(bench)konfiguration in URL-Notation
`-u "tracetronic:///{ET_WORKSPACE_DIR}/Packages/loop.pkg"`	Öffnen eines Packages oder Projektes, Testreports oder einer Test(bench)konfiguration in URL-Notation mit einem zum Workspace relativen Pfad	Beim Öffnen von Konfigurationsdateien wird nur der Test- bzw. Testbench-Konfigurationseditor geöffnet.
`-u "tracetronic:///C:/Data/ecu.test/Testreports/report.trf#231"`	Öffnen eines Packages oder Projektes, Testreports oder einer Test(bench)konfiguration in URL-Notation mit einem zum Workspace relativen Pfad mit Sprungmarke	Beim Öffnen eines Testreports kann eine Sprungmarke hinter dem Dateinamen angegeben werden. Nach dem Laden des Testreports wird der eintsprechende Eintrag ausgewählt. Im Testreportbetrachter kann die URL über das Kontext-Menü mit dem Eintrag Link kopieren in die Zwischenablage kopiert werden.
`-r "C:/Data/ecu.test/Packages/loop.pkg" --waitRunFinished`	Ausführen eines geöffneten Packages oder Projektes und auf Abschluss der Ausführung warten
`--waitRunFinished`	Warten, bis die Ausführung eines Packages oder Projekts beendet ist	nur in Verbindung mit `-r`
`--start-web-api`	Starten der web API für ecu.test code	Kann sowohl beim ersten Starten von ecu.test angegeben werden als auch beim Fernsteuern einer schon laufenden ecu.test-Instanz.
`-q` oder `--quit`	Beenden einer laufenden ecu.test-Instanz
`-k` oder `--kill`	Beenden einer laufenden ecu.test-Instanz erzwingen

Rückgabewerte¶

Wenn der ecu.test-Prozess aufgrund eines Fehlers beendet wird, gibt dieser einen Code ungleich 0 zurück.

Rückgabewert	Beschreibung	Anmerkungen
`0`	Kommando erfolgreich ausgeführt
`1`	Es ist ein Fehler bei der Ausführung aufgetreten, z.B. aufgrund eines Timeout beim Start der Instanz	Informationen zur Fehlerursache können dem Log entnommen werden
`8`	Es konnte keine neue Instanz gestartet werden	z.B. weil bereits eine Instanz auf diesem Port läuft
`99`	Fehlende Lizenz

Beispiele¶

Alle Pfade müssen stets plattformspezifisch angegeben werden.

Somit könnte ein Kommando unter Windows beispielsweise wiefolgt aussehen:

ecu.test.exe --workspaceDir C:/Data/ecu.test

Unter Linux sieht ein Beispielkommando demnach wiefolgt aus:

ecu.test --workspaceDir /home/Data/ecu.test

Bei dem folgenden Beispiel wird eine Instanz von ecu.test gestartet, wenn nicht bereits eine Instanz von ecu.test läuft. Wenn ecu.test bereits läuft, wird diese Instanz verwendet.

rem ecu.test mit angegebener Konfiguration starten
start ecu.test.exe
timeout /T 10
ecu.test.exe -w
timeout /T 5
ecu.test.exe -c "C:/Data/ecu.test/Configurations/empty.tcf" -b "C:/Data/ecu.test/Configurations/local.tbc"

rem warten bis gestartetes ecu.test bereit ist
ecu.test.exe -w

rem Package öffnen....
ecu.test.exe -o "C:/Data/ecu.test/Packages/DrivingCycle.pkg"

rem Package ausführen....
ecu.test.exe -r "C:/Data/ecu.test/Packages/DrivingCycle.pkg"

rem weitere Aktionen möglich

rem ecu.test wieder beenden
ecu.test.exe -q

Runner als Konsolenanwendung¶

Neben der GUI-Variante steht mit ecu.test_runner auch eine schnellere Konsolenanwendung zur Verfügung, die ohne grafische Benutzeroberfläche auskommt.

Diese bietet insbesondere bei der Automatisierung von Tests Vorteile hinsichtlich der Ausführungsgeschwindigkeit.

Eine Kommandozeile, welche den Runner nutzt, könnte wie folgt aussehen:

ecu.test_runner execute --workspace C:/Data/ecu.test myPackage.pkg

COM API¶

Neben der sehr einfachen Steuerung über Batchdateien verfügt ecu.test auch über einen COM-Server, der deutlich mehr Möglichkeiten zur Steuerung und Abfrage von Informationen bietet.

Die Befehle der ecu.test COM-Schnittstelle sind in der API-Dokumentation unter COM API detailliert beschrieben. Des Weiteren wird in COM API Beispiele die Verwendung der COM-Schnittstelle anhand der folgenden zwei Beispiele demonstriert.

Excel: Ein Package über die ecu.test COM-Schnittstelle ausführen und das Ergebnis in die Excel-Tabelle einfügen.
C#: Ein Package über die ecu.test COM-Schnittstelle ausführen.

Info

Die Registrierung von ecu.test als COM-Server muss hierfür bei der Installation aktiviert werden. Anderenfalls ist die COM API nicht verfügbar. Wurde eine andere Version von ecu.test deinstalliert, so funktioniert die COM API mit einer verbleibenden Version nur noch mit Angabe der Versionsnummer im Dispatch-Aufruf - z.B. win32com.client.Dispatch('ecu.test.Application.2025.3') bzw. win32com.client.Dispatch('ECU-TEST.Application.2023.3') für Versionen vor 2023.4

Die COM-Server Registrierung kann mit erneutem Aufruf des Installers und dort den Optionen „Ändern“ bzw. „Reparieren“ erneut vorgenommen werden. Führt diese Maßnahme nicht zum Ziel, ist die COM-Server Registrierung notfalls auch manuell über die Kommandozeile durchführbar:

~ecu.test Programmverzeichnis~/ecu.test_COM.exe /register

Für die systemweite Registrierung sind Admin-Rechte erforderlich. Alternativ kann mit der zusätzlichen Option /peruser die Registrierung nur für den aktuellen Nutzer vorgenommen werden. Der Aufruf sieht dann wie folgt aus:

~ecu.test Programmverzeichnis~/ecu.test_COM.exe /register /peruser

Info

Weitere Hinweise zur COM API finden sich im Kapitel API-Referenzen

REST API¶

Für die Ausführungssteuerung von ecu.test gibt es alternativ zur bisherigen COM API eine auf OpenAPI basierte REST API.

Weitere Hinweise zur REST API finden sich in der REST API Dokumentation.

ecu.test execution plugin¶

Das ecu.test execution plugin bietet eine einfache Integration und Ansteuerung von ecu.test sowie Tool Server in der Continuous Integration-Umgebung Jenkins.

Weitere Informationen zur Installation und Konfiguration des Plugins stehen im Github-Repository zur Verfügung.