Due to long file- and path names you have to take action before checking out the test suite repository. If you want to run and work with the test suite on a windows computer you have to enable GIT in Windows to deal with long file- and pathnames:
-
Run Git Bash as administrator (right-clicking the app shortcut will show the option to Run as Administrator ) Run the following command:
-
git config --system core.longpaths true
(!) Note: if step 2 does not work or gives any error, you can also try running this command:
-
git config --global core.longpaths true
The test driver interface is secured via mTLS. Since all communication runs through the Tiger Proxy, a client certificate must be provided to the Tiger Proxy. Additionally, the test driver must be equipped with the corresponding certificates. This chapter describes how to properly configure the proxy and provides supporting guidance on how to install the server certificate.
After applying for approval, you will be asked to provide the URLs of the interfaces you have supplied. For these URLs, gematik will create a server certificate, a client certificate, and all associated keys.
The certificates and keys can be extracted from the .p12-File as follows (required passwords are provided in the accompanying password file):
openssl pkcs12 -info --in gemTruststore.p12 -nokeys > trustedCert.pemopenssl pkcs12 -info --in <yourName>ServerKeystore.p12 -nokeys > serverCert.pemopenssl pkcs12 -info --in <yourName>ServerKeystore.p12 -nocerts > serverKey.pemopenssl pkcs12 -info --in <yourName>ClientKeystore.p12 -nokeys > clientCert.pemopenssl pkcs12 -info --in <yourName>ClientKeystore.p12 -nocerts > clientKey.pem|
Important
|
When a key is loaded from a .p12 file, a new password is set. This does not have to match the password in the provided `password`file. |
A precise guide is not possible here. The setup may vary depending on the technology used. The certificate and its verification can be handled directly in the application or through a proxy server placed in front.
|
Important
|
The interface must support TLSv1.2! |
An example configuration with a nginx proxy as it might appear under /etc/nginx/default.conf is provided here.
At the same time, the extracted
-
Server Key
-
Server Certificate
-
Trusted Certificate
must be placed under etc/nginx/conf.d/certs/* .
In addition, a .txt file must be created that contains only the server key password (either the user-defined password if the extracted certificate is taken from the keystore, or the password from the password.txt file if it has not been changed).
access_log /dev/stdout;
error_log /dev/stderr debug;
server {
listen 443 ssl default_server;
ssl_protocols TLSv1.2;
ssl_certificate conf.d/certs/serverCert.pem;
ssl_certificate_key conf.d/certs/serverKey.pem;
ssl_password_file conf.d/certs/pass-key.txt;
ssl_verify_client on;
ssl_verify_depth 1;
ssl_trusted_certificate conf.d/certs/trustedCert.pem;
charset utf-8;
location / {
...
}
}
The test driver interface uses mTLS. Therefore, a client certificate must be provided and passed to the Tiger Proxy. The test suite is set up to expect the path and password under the following environment variables:
-
TIM_KEYSTORE
-
TIM_KEYSTORE_PW
If a self-signed certificate is used for testing purposes, a truststore must also be configured. This is done by specifying the following two environment variables:
-
TIM_TRUSTSTORE
-
TIM_TRUSTSTORE_PW
The respective stores should be in .p12 format.
For local/internal development, the use of TLS can be bypassed. Instructions for this can be found here.
The test driver interfaces that need to be tested are managed in the file combine_items.json. To add a new test driver interface to the test suite, a corresponding entry must be added to this file.
The value in combine_items.json can either represent the complete URL or an alias for better reference.
The alias can be chosen freely.
If an alias is used, the corresponding URL must be entered under url.
[
{
"value": "API1",
"url": "https://<HOST_NAME>:<PORT>"
},
{
"value": "API2",
"url": "https://<HOST_NAME>:<PORT>/rest/"
},
{
"value": "API3",
"url": "https://<HOST_NAME>:<PORT>/ti-m-testtreiber"
}
]|
Important
|
For the use of an alias, it is also necessary to enter it in the tiger.yml according to the following schema!
|
# default local Tiger Proxy
tigerProxy:
tls:
forwardMutualTlsIdentity: "${TIM_KEYSTORE};${TIM_KEYSTORE_PW};pkcs12" (1)
proxyRoutes:
- from: http://API1 (2)
to: https://<HOST_NAME>:<PORT>
- from: http://API2
to: https://<HOST_NAME>:<PORT>/rest/ (3)
- from: http://API3
to: https://<HOST_NAME>:<PORT>/ti-m-testtreiber/-
The default local Tiger Proxy must remain.
-
Under
proxyRoutes, the individual routes can be specified for the proxy. From must start with http:// and match the value in combine_items.json. Make sure that the specified URL ends with a trailing '/', otherwise the connection will fail. -
Additional resources in the path must be specified.
|
Important
|
Please ensure that the interface metadata is populated with all required parameters accurately. |
One of these parameters is the information interface, which requires the
OS information. This parameter must be filled with the corresponding
operating system. This applies equally to both the TI-M client interface
(clientInfo) and the organization admin interface (fachdienstInfo).
For the TI-M client interface, the operating system must be differentiated between:
-
Mobile clients (e.g., Android, iOS)
-
Native clients (e.g., Windows, macOS)
-
Web clients (e.g., Linux Server, Windows Server)
The same applies to the organization admin interface. If it is integrated into a TI-M client (e.g., within a native app), the operating system should be specified similarly to TI-M clients (e.g., Windows, macOS).
Client interface example:
"clientInfo": {
"osInfo": {
"operatingSystem": "Android",
"version": "10"
}
}
Organisation admin interface example:
"fachdienstInfo": {
"osInfo": {
"operatingSystem": "LinuxServer",
"version": "5.15"
}
}
Please ensure that all required parameters are filled in, not just the osInfo field!
Additionally, this parameter must also be populated when using the same codebase for multiple products requiring approval. It must align with the information provided in the submitted application for approval documents.
Example: In the application for approval: TI-M Client Android → "operatingSystem": "Android".
The test suite executes the tests as Maven integration tests. The test suite is started with this command:
mvn verify
To be prepared for certain circumstances, the test suite can slightly adjust its behavior. Below are parameters that can all be specified using -D<parameterName>(=<parameterValue>) during invocation.
| Parameter name | Effect | defaultValue |
|---|---|---|
maxRetryClaimRequest |
Specifies how many times claiming a device can fail before it is terminated |
3 |
timeout |
Specifies how long to wait after a request is sent until the expected response appears |
10 sec |
pollInterval |
Specifies the intervals at which a request is sent again until the expected response appears |
1 sec |
httpTimeout |
Specifies how long the test suite waits for a response from the test driver interface |
180 sec |
claimDuration |
The value sent with a claim request testdriver.yaml |
180 |
runWithoutRetry |
Sends a request only once and assumes that there are no synchronization issues |
false |
clearRooms |
Each user queries their rooms at the beginning and leaves all of them. This results in a performance loss and is intended only for cleaning up the setup. |
false |
skipRoomStateCheck |
The test suite does not fail when the check that tests whether each room member has the correct membership state fails. Instead, an individual log entry is made if the value is set to |
false |
After the test execution, the current report is located in the build directory under target/site/serenity/index.html. Repeated executions are summarized in a common report.
Additionally, each run is saved in the root directory in the reports folder along with its report and the feature files used.