KOB-Testsuite - VORAB VERSION!!

Inhaltsverzeichnis

• Einführung

• Setup

• Testvorbedingungen

• Konfiguration

• Routing

• Testausführung

• Port Tabelle

• Prüfnachweis für die KOB

Einführung

Vorab-Version der KOB-Testsuite. Dies ist die Testsuite, mit welcher die Konformitätsbestätigung der gematik für EPA 3.0 erreicht werden kann.

Es sind der verpflichtende KOB-Test sowie optionale Tests vorhanden. In näherer Zukunft werden diese Tests mittels Testtreiber-Schnittstelle auch in einen voll automatisierbaren Zustand gebracht, sodass automatisierbar Regressionstests durchgeführt werden können.

Important

Dies ist eine Vorab-Version der KOB-Testsuite. Die Veröffentlichung der endgültigen Version ist für den 1. Dezember 2024 geplant. Für die Ausführung der KOB-Testsuite ist es wichtig, dass nicht die PS-Testsuite und auch keine Mock Services aus dem epa-deployment parallel auf dem gleichen Rechner verwendet werden (u.a. wegen Port Konflikte).

Setup

Die grundsätzlichen technischen Voraussetzungen sehen wie folgt aus:

• Die Testsuite wird auf einem Tester-PC ausgeführt.

• Auf diesem läuft auch das Primärsystem.

• Der Konnektor ist korrekt konfiguriert und erreichbar.

• Auf diesem Testrechner kann nun die Tiger-Testsuite gestartet werden, ebenso wie der Tiger-Proxy.

• Die Kommunikation zwischen Primärsystem und der TI muss nun über den Tiger-Proxy geleitet werden.

• Dieser kann die Kommunikation aufzeichnen und analysieren.

• Die Testsuite kann Artefakte von Maven Central aus dem Internet beziehen.

Testvorbedingungen

Die grundsätzlichen fachlichen Voraussetzungen sehen wie folgt aus:

• Die Aktenkonten bei beiden Aktensystemen sind in der RU-DEV eingerichtet worden.

• E-Rezepte für die Aktenkonten wurden eingestellt. (z.B. können AVS Hersteller hierfür das Gematik Tool vom Medical Team ERPIONE nutzen)

• Die Aktenlokalisierung der Aktenkonten kann bei beiden Aktensystemen erfolgreich durchgeführt werden.

• Für die genutzte LEI (SMCB) kann eine Befugnis (Entitlement) für die Aktenkonten bei den beiden Aktensystemen eingestellt werden.

• In Nicht-PU-Umgebungen muss der Client (das Primärsystem) die verwendeten Schlüssel (K2_c2s_app_data und K2_s2c_app_data) Base64 kodiert im Header "VAU-nonPU-Tracing" übertragen. Dies ist nur für die Testumgebungen (z.B. KOB-Testfall) vorgesehen und MUSS für die produktive Umgebung (PU) zwingend wieder entfernt und dürfen dort NICHT übertragen werden. (siehe A_24477)

Konfiguration

Warning

Für eine ordnungsgemäße Ausführung der KOB-Testsuite dürfen nur bestimmte Dateien angepasst werden. Diese sind: * kob.yaml (Konfiguration der Testsuite) * dc-testsuite.yml (Konfiguration des Docker-Containers) * .env (Konfiguration des Docker-Containers) Alle übrigen Dateien dürfen nicht verändert werden!

Die folgenden, relevanten Konfigurationen der KOB-Testsuite müssen wie folgt in kob.yaml vorgenommen werden:

• kvnrIbm - die für die KOB gegen das IBM Aktensystem verwendete KVNR

• kvnrRise - die für die KOB gegen das RISE Aktensystem verwendete KVNR

• emltype - das für die KOB verwendete EML-Format

• useTestdriverApi - ob die Testtreiber-API bei der KOB verwendet werden soll

TLS Konfiguration

Der Tiger-Proxy unterstützt TLSv1.2 und gibt Server Zertifikate zurück, welche den Zertifikaten der Aktensysteme in der RU-DEV entsprechen. Siehe folgende Dateien:

• epa-as-1.dev.epa4all.de_NIST_X509.p12

• epa-as-2.dev.epa4all.de_NIST_X509.p12

Zusätzlich wurde die unterstützen CipherSuiten wie folgt eingeschränkt (GS-A_4384-*):

• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Routing

Es muss das Routing der Nachrichten über Tiger-Proxy der KOB-Testsuite erfolgen, um eine Auswertung dieser zu ermöglichen. Der Tiger-Proxy leitet die Anfragen an die korrekten Aktensysteme weiter. Wichtig ist hierbei auch, dass in dem äußeren HTTP-Request auch der HTTP-Header "Host" für die Anfrage an das entsprechende Aktensystem gesetzt ist, damit Tiger-Proxy die Anfrage entsprechend nach dem Mitschnitt weiterleiten kann.

Beispiel für den HTTP-Header, damit Tiger-Proxy korrekt routen kann.

Host: epa-as-1.dev.epa4all.de

Es gibt keine Vorgabe WIE diese Umleitung erfolgen muss, zwei Wege scheinen jedoch sinnvoll:

Forward Proxy (Variante 1)

Zunächst einmal kann der Tiger-Proxy schlicht als Forward-Proxy für das Primärsystem eingerichtet werden. Die Routen sind entsprechend konfiguriert, so dass der Verkehr hier an die korrekten Aktensysteme weitergeleitet wird.

DNS Manipulation (Variante 2)

Alternativ kann die DNS-Auflösung beeinflusst werden, z.B. über das Editieren der Host-Einträge im Testsystem selbst (e.g. /etc/hosts). Hier werden die Hostnamen der Aktensysteme auf die IP-Adresse des Testrechners, wo der Tiger-Proxy mit dem Port 443 läuft, umgeleitet.

Beispiel, wenn das Primärsystem auf dem gleichen Rechner läuft, wie die Testsuite mit dem Tiger-Proxy.

127.0.0.1    epa-as-1.dev.epa4all.de
127.0.0.1    epa-as-2.dev.epa4all.de

Important

Diese Einträge sollten nach der Durchführung der KOB-Testsuite wieder entfernt werden, da es ansonsten zu einem unbeabsichtigten Fehlverhalten führt, wenn die KOB-Testsuite nicht mehr aktiv läuft und somit die Nachrichten nicht mehr an die Aktensysteme weitergeleitet werden.

Proxy Konfiguration für Maven (Docker)

Da der KOB-Testsuite Container während der Ausführung Maven-Artefakte bezieht, muss das Internet für den Container erreichbar sein. Sollte das Internet nur über einen Proxy-Server erreichbar sein, müssen die Einstellungen in der [./settings.xml](./settings.xml) für die Ausführung des PS-Testsuite Containers angepasst werden. Bitte beachten Sie, dass der Parameter <active>true</active> gesetzt werden muss, um die Einstellungen zu aktivieren und das Docker-Volume kob-testsuite-maven gelöscht werden muss, um die Änderungen zu übernehmen.

Dazu müssen die folgenden Einträge angepasst werden:

  <proxy>
    <id>optional</id>
    <active>true</active>
    <protocol>https</protocol>
    <host>proxy.example.com</host>
    <port>8080</port>
    <username>user</username>
    <password>password</password>
    <nonProxyHosts>localhost|127.0.0.1</nonProxyHosts>
  </proxy>

Testausführung

Die KOB-Testsuite kann entweder lokal per Maven oder in einem Docker-Container ausgeführt werden.

Lokal (Maven)

Für die lokale Ausführung werden folgende Software-Versionen empfohlen:

• Maven Version >= 3.9

• JAVA Version >= 17

Ist dies gegeben, reicht ein einfaches Kommando mvn clean install im Root-Verzeichnis des Projekts. Um nur die Testfälle für die KOB EPA 3.0 auszuführen, können die folgenden Befehle verwendet werden:

• mvn clean verify -Dcucumber.filter.tags=@KOB für den Test gegen beide Aktensysteme

• mvn clean verify -Dcucumber.filter.tags=@IBM für den Test gegen das IBM Aktensystem

• mvn clean verify -Dcucumber.filter.tags=@RISE für den Test gegen das RISE Aktensystem

Um optionale Testfälle auszuführen, können die folgenden Befehle verwendet werden:

• mvn clean verify -Dcucumber.filter.tags=@login Aufbau einer User-Session bei einem der beiden Aktensysteme

• mvn clean verify -Dcucumber.filter.tags=@information-record-status Aktenkontolokalisierung bei einem der beiden Aktensysteme

• mvn clean verify -Dcucumber.filter.tags=@information-consent-decisions Abfrage der Zustimmung für ein Aktenkonto bei einem der beiden Aktensysteme

• mvn clean verify -Dcucumber.filter.tags=@entitlement Einstellen einer Befugnis für ein Aktenkonto bei einem der beiden Aktensysteme

Ohne diesen Filter werden alle Tests ausgeführt.

Lokal (Docker)

Die Testsuite kann mit einem Docker-Compose gestartet werden. Diese Variante startet per Default momentan nur die verpflichtenden KOB-Testfälle. Siehe .env Datei. Hier können dann auch die optionalen Testfälle, wenn gewünscht, konfiguriert werden.

docker compose -f dc-testsuite.yml up

WorkflowUI

Die Durchführung der Testsuite geschieht über die von der KOB-Testsuite bereitgestellte Webseite der WorkflowUI. Hierzu wird die folgende Adresse im Browser aufgerufen, wenn sich die Testsuite auf dem lokalen Rechner gestartet wurde: http://localhost:9010. Beim Starten über Maven versucht die Testsuite diese Seite automatisch im Default-Browser zu öffnen. Beim Starten als Docker Container wird der entsprechende Link im Log ausgegeben, sobald die Seite aufrufbar ist.

========================================================================================================================
  ____ _____  _    ____ _____ ___ _   _  ____  __        _____  ____  _  _______ _     _____        __  _   _ ___
 / ___|_   _|/ \  |  _ \_   _|_ _| \ | |/ ___| \ \      / / _ \|  _ \| |/ /  ___| |   / _ \ \      / / | | | |_ _|
 \___ \ | | / _ \ | |_) || |  | ||  \| | |  _   \ \ /\ / / | | | |_) | ' /| |_  | |  | | | \ \ /\ / /  | | | || |
  ___) || |/ ___ \|  _ < | |  | || |\  | |_| |   \ V  V /| |_| |  _ <| . \|  _| | |__| |_| |\ V  V /   | |_| || |   _ _ _
 |____/ |_/_/   \_\_| \_\|_| |___|_| \_|\____|    \_/\_/  \___/|_| \_\_|\_\_|   |_____\___/  \_/\_/     \___/|___| (_|_|_)

========================================================================================================================
09:21:12.065 [main ] INFO  d.g.t.t.l.TigerDirector - Waiting for workflow Ui to fetch status...
09:21:12.065 [main ] INFO  d.g.t.t.l.TigerDirector - Workflow UI http://localhost:9010

Nachdem der Testfall gestartet wurde, wartet die Testdurchführung auf eine Benutzerinteraktion, um mit der Prüfung der mitgeschnittenen Nachrichten vorzufahren. D.h. das in diesem Moment die eML vom Aktensystem abgerufen wurden muss, bevor man die Testdurchführung fortführt.

Port Tabelle

Service	Port	Protocol
Tiger Testsuite (WorkflowUI)	9010	http
Tiger-Proxy Admin Port	9011	http
Tiger-Proxy Proxy Port	443	http / https

Prüfnachweis für die KOB

Für die Beantragung des KOB Zertifikates bei der gematik benötigen Sie als Prüfnachweis den Testreport (zip file) und pro konfiguriertem Aktensystem je ein Screenshot (Bilddatei) von Ihrer GUI des PS auf der die angezeigte eML ersichtlich wird. Den Screenshot Datei(en) erstellen Sie bitte lokal bei Ihnen am System.

Testreport

Die Testergebnisse selbst sind unter target/site/serenity/index.html zu finden und können somit im Browser verifiziert werden. Der Testreport wird automatisch nach der Ausführung im target/kob-testsuite.*-test-report.zip abgelegt, wenn die Ausführung über den Quit Button in der WorkflowUI beendet wird. Um diese Datei aus dem Docker Container in das lokale System zu kopieren, muss der Platzhalter <KOB_RELEASE_VERSION> mit der entsprechenden Release-Versionsnummer ersetzt werden. Dann kann folgender Befehl genutzt werden:

docker cp kob-testsuite:/app/target/kob-testsuite-<KOB_RELEASE_VERSION>-test-report.zip .

Upload bei TITUS

Loggen Sie sich in Ihren Account auf dem Titus Bestätigungsportal (https://titus.gematik.solutions) ein und laden Sie die entsprechenden Prüfnachweise im Bestätigungsantrag hoch. Für das Hochladen nutzen sie den Dialog "Nachweise für das Bestätigungsverfahren", wo sowohl der Testreport als ZIP Datei als auch den/die Screenshot Datei(en), welche die eML in ihrem Primärsystem darstellen, ausgewählt werden können. Im Anschluss starten Sie den Bestätigungsnachweis über TITUS.

Fragen zum Titus-Bestätigungsportal und zur Durchführung des KOB Verfahrens können Sie über unseren Servicedesk einstellen: https://service.gematik.de/servicedesk/customer/portal/26/group/36

Troubleshooting / FAQs

Starten der Testsuite (Docker)

java.nio.file.AccessDeniedException: /.m2/repository/org

Der Zugriff auf das Docker Volume schlägt fehl.

Variante 1

Das Volume mit der gleichen Bezeichnung schon existiert und wurde von einer anderen, möglicherweise älteren, Version der KOB-Testsuite erstellt wurde. Man muss das Volume einmal löschen und bei Start der neuen Testsuite wird es wieder angelegt.

$> docker compose -f dc-testsuite.yml rm
$> docker volume rm -f kob-testsuite-maven
$> docker compose -f dc-testsuite.yml up

Variante 2 (Linux)

Bitte prüfen Sie vor dem Start der Testsuite, ob Sie das .docker Verzeichnis löschen können und starten sie die Testsuite im Anschluss noch einmal.

Variante 3 (ohne Docker Volume)

Eine weitere Möglichkeit ist auf die Nutzung des Docker Volume zu verzichten. Der Nachteil hierbei ist, dass die Maven Artefakte bei jedem Start der Testsuite erneut heruntergeladen werden müssen, was mehr Zeit in Anspruch nimmt. Hierzu wird die Zeile - kob-testsuite-maven:/.m2 wie folgt mit einem Hash (#) auskommentiert.

    volumes:
      - ./tiger.yaml:/app/tiger.yaml
      - ./kob.yaml:/app/kob.yaml
      #- kob-testsuite-maven:/.m2
      # has to be 'copied' AFTER the volume is mounted
      - ./settings.xml:/.m2/settings.xml

Ausführen der Tests / fehlschlagende Tests

Im Falle eines fehlgeschlagenen Testlaufs und dem Schreiben eines Support-Tickets im gematik Service Desk ist es sinnvoll, die *.tgr-Datei mit den aufgezeichneten Nachrichten anzuhängen. Damit ist es möglich, die Traces in eine lokale Tiger-Anwendung zu importieren, um die Kommunikation und deren Meldungsdetails anzuzeigen.

Dazu müssen Sie den folgenden Befehl ausführen, um die *.tgr aus dem ps-testsuite Container in das lokale Verzeichnis zu kopieren.

docker cp ps-testsuite:/app/tiger-proxy.tgr .

Geplante Änderungen

Hier eine Übersicht über die wichtigsten Änderungen, die wir planen. Wenn Sie hier Dinge vermissen oder Anregungen haben, melden Sie sich bitte bei uns!

• Automatisierung der optionalen Tests. Hierfür werden ggf. Anpassungen der Testtreiberschnittstelle notwendig sein. Diese Änderungen werden aber NICHT mit den verpflichtenden Tests kollidieren. Sprich: Die jetzt existierende Schnittstelle wird aller Voraussicht nach bis zur KOB 3.0 unverändert bleiben.

• Einbau einer Test-REST-API in die Tiger-Testsuite, um eine bessere Integration in CI/CD-Pipelines zu ermöglichen.