Tiger User Manual

The Tiger Proxy at its core is an extended Mock server, that has the following additional core feature set:

The Tiger test environment manager provides methods to configure and instantiate multiple server nodes in your test environment and offers the following core feature set:

The Tiger test library provides the following core features:

The Testenvironment Manager instantiates all test nodes configured in the tiger.yaml config file.
It also instantiates one local Tiger Proxy for the current test suite.
This Tiger Proxy instance (and others created in the test environment if using a mesh setup) traces all requests and responses
forwarded via this proxy and provides them to the test suite for further validation.

For each server node instantiated, the local Tiger Proxy adds a route so that the instantiated server node
can be reached by the test suite via HTTP and the configured server hostname.

Each Tiger Proxy can be configured in a multitude of ways: as reverse or forward proxy with special routing features and
modifications of content easily configurable, or in a mesh setup as proxy forwarding traffic to other Tiger Proxies…​

The BDD or JUnit test suite can integrate the Tiger test library to validate messages (requests and responses) sent/received
over Tiger Proxies using features such as RBelPath, VAU decryption, JSON checker and XML checker.

As Tiger evolves we have implemented quite a nice set of extensions that eases your job as tester in areas not directly fitting the core of Tiger. The currently or soon available extensions are:

This plugin allows to dynamically generate the JUnit driver classes that are then used in the Surefire plugin to start the test runs.
And replaces the serenity maven plugin to generate Serenity BDD test reports.

The failsafe plugin will trigger the test run.
It is important to activate the testFailureIgnore property, to ensure that even if the test fails, the serenity report is created.

To filter the scenarios/features to be run you may pass in the Java system property cucumber.filter.tags.
You can do so either within the <systemPropertyVariables> tag or via the command line using -Dcucumber.filter.tags

The "not @Ignore" is the default setting for maven verify as well as for IntelliJ, therefore scenarios that should be ignored are to be tagged with @Ignore.
If the user uses the cucumber option "-Dcucumber.options" to set own tags then the default setting of "not @Ignore" is overridden.
The same counts for own tag settings in the IntelliJ run configuration.

For more details about how to use filter tags see https://cucumber.io/docs/cucumber/api/#tags

Reason is that when using Tiger Proxies with the Tiger test library validation feature parallel execution may lead to messages from different threads / forked processes ending up in the wrong listening queue making it very complicated to make sure your validations are working as expected in different timing situations.

To be able to successfully start scenarios/features you first need to configure the Run/Debug settings of your project:

Best is to add these settings to the Configuration Templates for Cucumber Java.
Depending on the version of IntelliJ these settings are located either on the top icon bar or at the bottom left as link.

Else you would have to apply these settings to any new Debug/Run Configuration, like when you start a new scenario, which was never executed before.

If you are located behind a proxy please make sure to set the environment variables HTTPS_PROXY and HTTP_PROXY as well as the Java system properties http.proxyHost, http.proxyPort, https.proxyHost and https.proxyPort appropriately so that the internet connections are routed properly through your company proxy.

Please also make sure IntelliJ has its proxy settings configured appropriately for HTTP and HTTPS so that it can download the dependencies for the IntelliJ build environment too.

Before you start writing your own tiger.yaml configuration files, make sure you have worked with yaml files before and know its syntax and structure.
If unsure take a 20 minutes primer, although not everything in the video is relevant, it gives a good introduction to indenting properties and structures and specifying values in a yaml file.

The general properties apply to each node type.

Here is a little example how the server names are set and used and how there server is reachable via the Tiger Proxy.

The general properties are followed by the type specific substructures, which configure specific aspects of each node type.
Their meaning and format are explained in the related section.

The configuration of the Tiger Proxy is explained in detail in the section Configuring the local test suite Tiger Proxy

PKI identities can be supplied in a number of ways (JKS, BKS, PKCS1, PKCS8).
In every place a string can be given.
It could be one of

Not supported pathname strings:

Supported pathname string on all platforms:

Please notice, that double backslashes ("\\") are not supported as file separators, since they are not accepted on all platforms.
Invalid pathname strings will also produce an exception.

Each part can be one of:

If you want, you can also describe the components in a map:

In this case both the storeType and the password are not mandatory and would be guessed (the store-type via the file extension and the password via a default-list).

The docker container node allows to instantiate a local docker container from the configured image.
The exposed port of the docker container is available as a special token in the substitution process of the exports entries (${PORT:xxxx} where xxxx is the port being exposed inside the container).

To customize the docker container you may alter the entry point command line.
Additionally, Tiger will automatically add the Tiger Proxy certificate to the container’s operating system list of trusted certificates.
This modification can be disabled by setting the property dockerOptions.proxied to false.
E.g.:

For containers that should exit after a single command you may enable the oneShot property.

You can also copy files to the container by configuring the source and destinations paths of files or folder to be copied.

If there is no health check configured inside the docker image, Tiger will try to guess a healthcheck url by assuming the first exposed port as a get request to localhost to check for a successful startup of the docker container (e.g. http://127.0.0.1:xxxx).

If no port is exposed at all, the startupTimeoutSec property will determine the wait period, after which Tiger assumes the container is up and running.

If you have your local docker environment set up hosting the docker containers on a remote docker hub server, you may set the environment variable TIGER_DOCKER_HOST to allow the health check url determined on runtime to point to the remote host instead of localhost.

The docker compose node is a very tricky type of node because we use testcontainer library, which is not exactly up to date in terms of docker compose support.
So many of the yaml compose files will need to be modified to work with the testcontainer library.

For now, we support the ePA2 FD module and the DEMIS Meldeportal.

If you want to use your own compose files, please note that Tiger copies and processes your yml files to the target/tiger-testenv-mgr/${serverId} folder, replacing all variable/property expressions (for details check this chapter).

The processing/copying flattens the file hierarchy, thus you must not depend on any additional file resources in your docker compose files.
Each copied compose file will have a random UUID appended to its filename.

The External Jar node is along with the Docker container node the most important/used node for test environments.
Any Jar archive executable which can be started with the java -jar command can be configured as an external Jar node.

The options list are arguments added immediately after the java executable, while the arguments list is appended after the -jar argument.

The working directory is the place where the jar file is downloaded to and executed from.
So if your jar archive expects some configuration files make sure to choose the folder appropriately.

If using the local: prefix you can also use wildcards to find any matching jar-files.
Tiger will use the following order to try to find a matching file:

By default, the JVM used to start the JAR-File is the taken from the java.home system property, thus using the same JVM with which Tiger was started.
To change the JVM used you can set the property tiger.lib.javaHome (e.g. by setting -Dtiger.lib.javaHome, by setting TIGER_LIB_JAVAHOME in the environment or by setting lib.javaHome in the tiger.yaml).

The symbolic node type that will not start a server instance, but simply allows external services to be used via the configured hostname.
This is achieved by the test environment manager instructing the local Tiger Proxy to provide a route for the symbolic hostname to the external URL of the service.

So, in the following example, the test suite can send HTTP(S) requests to the server "http://myExternalServer" via the local Tiger Proxy, which will be rerouted to the external URL "https://www.medizin.de".
If it is ever necessary to change the external URL, the test suite does not have to be modified, only the routing configuration for the node has to be changed.

Given the nature of this type, the environment section has no effect and is not to be used.

The helm chart node allows to start a helm chart from the configured source (local helm chart file / folder or remote helm chart).
The helm chart is started and the server is ready when all pods are up and running, if port-forward is used (if exposedPorts are set), then port-forwarding is also done and the startup is finished and the service can be used for testing.

The most complex and versatile node type.
The Tiger Proxy will be started as an embedded spring boot application.
This way the start-up time can be minimized, and it is always guaranteed to start the current version.

The configuration of the Tiger Proxy is explained in detail in the section Configuring the local test suite Tiger Proxy

The httpbin simply starts a httpbin server.
This provides several endpoints against which you can perform all kinds of http requests.
The server port on which the server starts can be configured.

This template provides the reference implementation of the IDP server as a local docker container.
The docker image is loaded from a gematik internal docker registry server.

The system property IDP_SERVER is set to the URL of the Discovery Document end point and is available for all subsequently initiated test environment nodes.

The idp-rise-ru template provides the RU instance of RISE’s IDP server as an "external URL".
The system properties IDP_SERVER and GEMATIK_TESTCONFIG are set to the URL of the Discovery Document end point and a config-file for the IDP test suite respectively.
They are available for all subsequently initiated test environment nodes.

The idp-rise-tu template provides the TU instance accordingly.

This template provides the reference implementation of the eRezept server as a local docker container.
The docker image is loaded from a gematik internal docker registry server.
Make sure that an IDP server node is instantiated before the ERp FD is started and that it is available under http://idp or adapt the environment variable configuration.

A large list of environment variables is set.
But don’t worry, it is just the server that uses them.

This template provides the gematik reference Aktensystem simulation as docker compose.

This template provides a Primärsystem simulation (as a jar), usable for ePA.
See https://wiki.gematik.de/display/PTP/epa-ps for more information.

This template provides a Konnektor simulation (as external jar).
See https://wiki.gematik.de/display/PTP/KonSim for more information.

This template provides FdV simulation, usable for ePA.

This template provides the DEMIS Meldeportal as local docker compose.

Entries in the exports list of a node will be parsed and specific tokens will be substituted:

All exports entries of a node will be present when subsequent nodesare instantiated and can be used in the following properties:

Docker node:

Tiger Proxy node:

External URL node:

External Jar node:

Forward proxies work like a switch-station: You send a packet to your destination, via proxy.
The proxy receives the packet, sees the address and can send that packet to wherever he sees fit.
To use a forward proxy, the sender has to be aware of it and send the packet accordingly.

This allows the creation of virtual domains, something we use extensively in tiger.

A forward proxy can always read the entire content of your communication, something we also use heavily.

Lastly a forward proxy acts as a man-in-the-middle, enabling the penetration of TLS-traffic.
We also use this, but we will explain it in more depth later.

Reverse proxies also receive traffic and may reroute them at their own discretion.
But unlike a forward proxy a reverse proxy is invisible to the sender.
Reverse proxies act like normal servers and are addressed as such.
They then send the received packet to its actual destination and return the answer to the original caller.

The reverse proxy can also read the complete traffic.

The eventual destination is opaque to the original caller.
This also enables path-rewriting (for example the GET http://reverse.proxy.de/my/deep/url might be mapped to http://gematik.de/deep/url, eliminating the /my)

A reverse proxy also terminates https, always.
This is less of a problem with a reverse proxy since it is technically not a man-in-the-middle attack, due to the traffic being addressed to the reverse proxy.

From where should the traffic be collected?
This can either be an absolute URL (e.g. http://foobar), which defines a forward-proxy route, or relative (e.g. /blub), defining a reverse-proxy-route.
Please note: You can freely add parts (e.g. http://foobar/extra/part) to further specify the mapping.

You can add multiple routes that match the same URL.
If multiple matches are found the most specific route is select.
For example if you have two routes / and /foo then for a request to /foo/bar the route /foo will be selected.

A route will only match when the proxy-mode is met.
A reverse-proxy-route will thus not match when a forward-proxy request is received.
To disable this proxy-mode matching you can set the flag matchForProxyType to false (default is true).

The target of the mapping.
This has to be an absolute URL.
The Tiger Proxy will, upon receiving a request to this mapping, execute a matching request to the defined host.

An example.
Consider the following route:

The "http://" in the from property indicates that we have a forward-proxy route defined.
So when we execute: (assuming the Tiger Proxy is started locally under the port 1234)

The result will match the following curl

Additional headers are kept and just patched through.
The same goes for the body and the HTTP-Method.

Added parts of the from-URL are stripped when forwarding.
Meaning: If you have a mapping

and you execute GET http://my.domain/deep/deeper, you will get the result of GET http://orf.at/blub/deeper (the /deep in between has been eliminated along with my.domain).

Trailing slashes in routes may be significant for the server.
Thus, the handling in the tiger-proxy is important.
To achieve a consistent behavior while maintaining ease of use, the following rules apply:

This leads to the following examples:

In some instances you might be pressed to "hosts" multiple servers on one tiger-proxy.
This can happen when you can influence DNS-Resolvement, but neither the path nor the port used.
In this case you can use the hosts-property to define which hosts should be routed to which target.

The entries are matched first as a total match, failing that as regular expressions.
If you want to add ports you are free to do so: "myHost:80".
This however will necessitate that the ports on all entries in this specific list are given (this does not apply to other routes).

Sometimes you can only at runtime know which target to use.
This can be achieved by using the to-property as a list of targets:

When booting the tiger-proxy the proxy tries to reach the target host by sending a HEAD-request to the host (dropping the path).
If the server sends a valid HTTP (or HTTPS) response, the target is considered reachable and the route is used.
If no target can be reached an exception is thrown.
The return code is ignored.

As an additional measure for a more fine-grained matching you can use criterions.
These are JEXL-expressions which have to be fulfilled for the route to be used.
This can be leveraged to make the routing decision dependent on the content of the message.

This will only forward messages where the header contains a key "foo" with the value "bar".

You can deactivate the rbel-Logging on a per-Route basis.
Rbel is a versatile and powerful tool, but the analysis of individual messages consumes a lot of both CPU and memory.
Deactivating it for routes in which it is not needed is therefore a good idea.

You can add optional authentication configuration which will be added to the forwarded message.
Here either Basic access authentication or Bearer Token can be used:

Please note that the phrase "Bearer " will be added automatically.
Please do not add it yourself!

By default, a proxy route will only match when the proxy-mode defined by the from attribute is met.
For example, a route with from: /foo will not match with a forward-proxy request like so:

curl -x localhost:59163 http://backend.domain/

To enable matching for both proxy-modes you can use the matchForProxyType-flag:

This will match with both of the following requests:

TLS can be done via a http- or a https-proxy.
The proxy-protocol does NOT equate to the client-server-protocol.
To minimize the headache in configuration it is therefore strongly recommended to simply always use the http-proxy (sidenote: using a http-proxy does NOT reduce the security of the overall protocol.
The security still relies on server-certificate-verification.)

If, however, you can not avoid using the https-proxy you have to make sure that you add the given certificate to your truststore.
In class TigerProxy.java in Tiger there are methods such as SSLContext getConfiguredTigerProxySslContext(), X509TrustManager buildTrustManagerForTigerProxy() and KeyStore buildTruststore() which can help you configure the SSLContext in your case, if you use HTTP 3rd party libraries (Unirest, okHttp, RestAssured, etc.) as well as vanilla Java.
If you encounter any problems, please contact us.

For successfully breaking into TLS traffic the Tiger Proxy needs to present a certificate which features the domain-name of the server.
Since the domain-names are known only at runtime, we generate the needed certificate on-the-fly during the first connection.

For a forward-proxy this is easy: The client sends not only the path, but the complete URL to the proxy, letting him handle DNS-resolution.
So when the Tiger Proxy receives a new request the necessary domain-name is given by the client.
A new, matching, certificate is generated (these are cached) and presented.
To complete the setup the client-truststore needs to be patched.
The CA used by the Tiger Proxy is dynamically generated on each startup.

For a reverse-proxy the domain name, which should be used, is unknown to the Tiger Proxy (DNS-resolution is done on the client-side).
Thus, a domain-name needs to be provided, which should be used for certificate-generation:

When using a non-default certificate (which will almost always be the case for the Tiger Proxy) the modification of the client-truststore is necessary.
For cases where the client is running in the same JVM as the target Tiger Proxy (which is the typical case for a tiger-based testsuite) there exists helper method to make this task easier.

Depending on your HTTP- or REST- or SOAP-API you will need to choose the exact way yourself.
The following two examples might give you some idea of what to do.

If you can not or don’t want to alter the client-truststore you have two choices: You can either provide a custom CA to be used (and trusted by the client) or you can give the certificate to be used by the Tiger Proxy.
To set a custom CA to be used for certificate generation simply specify it:

The final, easiest and most unflexible way to solve TLS-issues is to simply give a fixed server-identity.
This identity will be used for all routes, but only if it matches the domain-name given by the client during the handshake.
As a fallback (if the domain-name does not match) the dynamic server-identity will be used.

If you want to use the fixed-server identity only for requests to matching hosts and you have NOT supplied a serverRootCa, you can use the allowGenericFallbackIdentity-property:

If certificateForFoobar.p12 contains a certificate for the FQDN foobar.com, then a request to foobar.com will use this certificate.
If the request is to barfoo.com the generic server-identity will be used.
If you have supplied a serverRootCa this CA will always be used for any request for which an exact match is not found.

Sometimes you might want to use different server-identities for different hosts that are proxied.
This can be achieved by using the serverIdentities-property.
Simply list the properties, the proxy will automatically try to choose the correct one.

If you want the Tiger Proxy to use OCSP stapling you can directly specify the OCSP-Signer to use in the configuration.

The server will then use this OCSP-Signer to create a fake OCSP-Response during the TLS-handshake.

Sometimes you might want to look at decrypted TLS-traffic in wireshark.
To achieve this we need to extract the masterSecrets of every connection from the Tiger Proxy and provide them to wireshark.
This is actually pretty straight forward, with one big caveat: It is very insecure to access the masterSecrets of a TLS-connection, so we need to attach a Java-Agent to the VM.

When you are using the Tiger Proxy in a normal tiger-testsuite you can simply add the <goal>attach-tiger-agent</goal> goal to the tiger-maven-plugin:

This will modify the argLine property used by failsafe to start the testsuite and attach the TigerAgent to the VM.
Next we need to set the filename where to write the masterSecrets to:

The Tiger Proxy will write the secrets to the given file.

The final step is to import the masterSecrets into wireshark:

Go to Edit → Preferences.
Open the Protocols tree and select TLS.
Alternatively, select a TLS packet in the packet list, right-click on the TLS layer in the packet details view and open the Protocol preferences menu.
Set the (Pre)-Master-Secret log filename to the file containing the master secrets.
Now wireshark should decrypt TLS traffic routed through the Tiger Proxy on-the-fly.

The Tiger Proxies use STOMP a simple/streaming text oriented messaging protocol via web socket to forward received traffic.
For an external client to receive these traffic data, it must subscribe to the traces topic reachable at the subscription path /topic/traces.
To do so the client must connect to the traffic endpoint URL of the Tiger Proxy.
This is answered with HTTP status 100 and then redirected to web socket protocol via the same port.
For each received traffic data pair (request/response) the Tiger Proxy will push a web socket message to all subscribed clients.

This JSON encoded message consists of:
* UUID string * http request as base64 encoded data * http response as base64 encoded data * hostname and port of sender (if retrievable, worst case only IP address or empty) * hostname and port of receiver (if retrievable, worst case only IP address or empty)

To make things easy and consistent, the entries of an array are simply stored as a map with the index as key.
So the following expression will return the first element of the array:

$.body.array.0

When a key is present multiple times, all elements are returned.
To differentiate between them, you can use the index:

$.body.entry[0]

would give the first element in the following XML:

To find alternating values, concatenate them using the pipe symbols, like so:
$.body.['foo'|'bar'].key

This expression will explore both subtrees to try to find the following nodes
$.body.foo.key and $.body.bar.key.
Please note that only elements that are present are returned.
So if only always one of the two elements is present, only a single element will be returned.

Sometimes it can be helpful to match keys in a case-insensitive manner.
To achieve this you can use the ~-operator:
$.body.[~'fOO'].key

This will match $.body.foo.key and $.body.FOO.key (and any other case-insensitive match).

To find multiple case-insensitive matches, concatenate them using the pipe symbols, like so:
$.body.['fOO'|'bAR'].key.
With this expression, the following nodes will be found: $.body.foo.key, $.body.FOO.key, $.body.bar.key and $.body.BAR.key (and any other potential matches).

RBeL-Path can be integrated with JEXL-expression, giving a much more powerful and flexible tool to extract certain element.
This can be done using the syntax from the following example:

The expression in the round-brackets is interpreted as JEXL.
The available syntax is described in more detail here or https://commons.apache.org/proper/commons-jexl/reference/syntax.html

Please note that these Jexl-Expression can not be nested inside each other deeper then one level (You can write a RbelPath that contains a Jexl-Expression.
And this Jexl-Expression can even contain a RbelPath.
But the inner RbelPath can not contain another Jexl-Expression).

The variables that can be used are listed below:

Additionally you can always reference the current element (via @.) or the root element (via $.) in any JEXL-expression.
Lets explain this using an example.

For more detailed information on JEXL expressions please refer to Detailed JEXL-expressions.

Consider the following rbel tree:

At $.body.body.idp_entity we have an array with potentially multiple entries (here there is only one, entry 0).
We want to select an entry where the iss-claim matches our expectation.
We can achieve this with using a nested Rbel-Path inside the JEXL-Expression:

$.body.body.idp_entity.[?(@.iss.content=='https://idpsek.dev.gematik.solutions')]

Here the @. references the current element: For each array entry the expression is tested, with @. always referring to the current entry.
To access elements starting from the root you can use $. like so:

$.body.body.idp_entity.[?(@.iss.content==$.body.body.idp_entity.0.iss.content)]

You can use recursive descent here as well:
$.body.[?(@..content == 'ES256')] would yield $.body.header.
Let’s unpack this expression:

Please note that since the RbelPath-expressions are executed prior to the JEXL-expression the negation might yield unexpected results.
Currently it is not recommended to use these. (e.g. $.body.[?(not (@.. == 'ES256'))])

To help users create RbelPath-Expressions there is a Debug-Functionality which produces log message designed to help.
These can be activated by RbelOptions.activateRbelPathDebugging();.
Please note that this is strictly intended for development purposes and will flood the log with quite a lot of messages.
Act accordingly!

When you want to debug RbelPath in BDD test suites, you can add a tiger.yaml file to your project root and add the following property (for more details see this chapter):

To get a better feel for a RbelElement (whether it being a complete message or just a part) you can print the tree with the RbelElementTreePrinter.
It brings various options:

Below some properties along with their respective default values:

This flag controls whether the Tiger Proxy will log all traffic.
If activated every request and response is noted in the log.
This can lead to a verbose and bloated log.
If you are not interested in the traffic log, but only in the Rbel-Analysis, you can deactivate this flag.
Default is true.

This flag activates the rewriting of the host-header.
If activated the host-header will be rewritten to the target host (only applicable for reverse proxy routes).
Default is false.

This flag activates the rewriting of the location-header for 3xx responses.
If activated the location-header will be modified so the client will still use the proxy to reach the new location.
Default is true.

By default, the Tiger Proxy will keep count of the number of requests it executes on itself (e.g. when a request is forwarded to the Tiger Proxy itself).
If this counter exceeds the value of maxLoopCounter the request will be aborted.
The default value is 10 (Meaning after 10 loops the request will end in an error).
Note: This behavior can only be customized for all Tiger Proxies.

At the core of the Tiger Proxy sits a RbelLogger instance.
Here the messages are parsed and stored.
Three sources feed into the RbelLogger:

Messages that are intercepted are automatically stored (the exception being the tigerProxy.activateForwardAllLogging-property, which can deactivate the logging of traffic not specifically forwarded via a route).
For messages in a mesh setup and from a source file filter expressions can be defined to limit the messages that are actually stored.
These can be defined using the tigerProxy.trafficEndpointFilterString (for mesh setups) and tigerProxy.fileSaveInfo.readFilter (for tgr-files) respectively.

When messages pass the filter, partner messages (request/response pairs) are kept intact.
So when you filter for messages that have a return code of 200 the corresponding requests do not match the filter expression.
They are however kept in memory since the partner, the response in that case, do match.

Filter expressions are JEXL-expressions.

When you display the messages on the Tiger Proxy Log you have the ability to filter out certain messages to be displayed exclusively.
The messages, which are filtered out, do still remain stored in the Tiger Proxy.
Consequently, this has no effect if you store a TGR file (be it via the Tiger Proxy Log or the YAML).

The menu on the right side will only show the messages being filtered out to avoid confusion.
However, the messages numbers do reference the order in the main Tiger Proxy store.
This way they are consistent across different Tiger Proxy Log filters (message #10 will always refer to the same message, regardless of the Tiger Proxy Log filter being applied).

Filter expressions are JEXL-expressions.

Finally, pagination is applied in the Tiger Proxy Log.
This comes after the Tiger Proxy Log-Filter has been applied.
So when would filter out every second message via a Tiger Proxy Log-Filter every page would still contain 20 (or whatever page size you have set) messages.

With the TGR find next request …​ steps you can validate a complete workflow of requests to exist in a specific order and validate each of their responses (see next chapter).

When comparing values (e.g. in the TGR current response body matches:) generally the algorithms check for equality and only check for regex matches if they were not equal.

Unresolved directive in tigerTestLibrary.adoc - include::./RBelValidatorGlueCommentsOnly.adoc[]

Tiger supports modifying JSON, XML and several token formats.
After loading in an object from a string or a file the RbelObject can be modified in multiple ways:

After the adjustments the values of the modified RbelElements can be asserted.
The object can be serialised back to a string.
Jexl Expressions are implemented, as for reading a file or for serializing:
'!{rbelObject:serialize("myRbelObject")}'

Unresolved directive in tigerTestLibrary.adoc - include::./RbelBuilderGlueCodeCommentsOnly.adoc[]

Unresolved directive in tigerTestLibrary.adoc - include::./HttpGlueCodeCommentsOnly.adoc[]

Using the validation steps TGR current response at {string} matches as XML: or
TGR current response at {string} matches as XML and diff options {string}: you are able to compare the content of any RbelPath node in the response.
The latter method even allows passing in the following options to the XMLUnit’s DiffBuilder:

Per default the comparison algorithm will ignore mismatches in namespace prefixes and URIs.
Comparison is also performed on similarity and not equal content.

For more detailed explanation about the XMLUnit difference evaluator we refer to the online documentation of the XMLUnit project.

Using the validation step TGR current response at {string} matches as JSON: you are able to compare the content of any RbelPath node in the response to the doc string beneath the step, with the help of the JSONChecker comparison algorithm.

The purpose of JSONChecker class is to compare JSON structures, including checking for the integrity of the whole RbelPath node, as well as matching values for particular keys.

To make sure all the attributes in your JSON RbelPath structure are present, such features as ${json-unit.ignore}, $NULL, optional attributes, regular expressions and lenient mode can come in handy.

${json-unit.ignore} is a parameter which allows ignoring certain values in your RbelPath node while comparing, and the result of such comparison always returns true.
It also works when ${json-unit.ignore} is used in a JSON array or nested JSON object.
This parameter should be placed as a value of a key.
To ignore some attributes in the JSON structure, you can set a boolean value checkExtraAttributes as false.
In this case if you miss one attribute in your doc string, the comparison will still be equal to true.

To check whether the value for a particular key is null, you can either use null or parameter $NULL at the place of the value.
Checking whether a nested key is null also works with JSONChecker.

Four underscores "__" before the JSON keys indicate that these keys are optional and will be checked for the value ONLY if the value exists in the test JSON RBelPath node.
Please note that checking whether a nested key is optional, is not yet possible with JsonChecker.

JSON Arrays are compared in lenient mode, meaning that the order of elements in JSON array doesn’t matter.

Identifying missing keys is made easy in JSONChecker with the help of parameter $REMOVE.

If you specify the name of the key and then $REMOVE parameter as its value, the comparison will result in true, if the key is indeed missing and false, if the key is present.
It is worth noting that even if the value of the key is null, the key doesn’t count as missing.

Last but not least, regular expressions, which can be used for matching the whole JSON element, as well as particular values.
It will be first checked, whether the expected value is equal to the actual one, and only afterwards, if the actual value matches a regular expression.

It should also be noted, that although JSONChecker can match multilevel JSON objects at a high level, it is not yet possible to access nested attributes out of the box.
We are working on it :)

The example above shows three main features of the JSONChecker.

Unresolved directive in tigerTestLibrary.adoc - include::./TigerGlueCommentsOnly.adoc[]

If you want to use large ASCII art style log banners you may find this class very helpful.
Supports ANSI coloring and a set of different fonts.
Furthermore, all banner messages are displayed and highlighted in the Workflow UI For more details please check the code and its usages in the Tiger test framework.

This class supports you in converting String representation of YAML and JSON data to an Java JSONObject or extract that or other loaded data to Java Maps.
If you are planning to implement test data management or configuration sets, we propose to use the TigerGlobalConfiguration class described in detail here.

The loader class allows to easily instantiate PKI identities from given files.
For more details on the format and the supported file types please check this section in the test environment chapter.

Tiger is closely integrated with SerenityBDD, which in turn has integrated the RestAssured library, so if you use the SerenityRest helper class, you will get detailed information about each call inside the test report.
The Tiger test library configuration also provides a flag to add curl command details to each of these calls, so that you can easily reproduce the REST call manually in case of test failure analysis.

For more information about REST testing in Tiger/SerenityBDD please check these two documents:

Say you have an environment configured in your testenv.yaml.
You want the Tiger Proxy to forward traffic on one route to your backend-server.
This will normally be a local server, but on the build-server you want to address another host.
You can simply set an environment variable to do the job for you.
Below are the relevant snippets:

In the buildserver you can now simply overwrite the "to"-part of this route like so:

In the above example let’s say you only want to customize the port.
This can be done by using placeholders:

This time we don’t overwrite the complete to-url but only the port like so:

Now we want to assert that the reply coming from the server has the correct backend-url in the XML that is returned to the sender.
To do this we have to reference the configured URL from above, since the value could be different on every execution.
We can solve this using placeholders:

The glue-code in Tiger automatically resolves the placeholders.

The default-namespace of the inline JEXL-expression carries the following functions:

An example of a function-invocation in the default namespace:

This will load the given file and replace any placeholders found in it.

To give you direct access to the messages sent please use the rbel-namespace:

This can be done like so

This will immediately return the href-attribute of the link in question as a string.

You can easily register additional namespaces by calling TigerJexlExecutor.registerAdditionalNamespace(<namespace-prefix>, <namespace class or object).

The section on the left is called status bar as shown in the picture below.

When the user clicks on the tigers head on the top left the status bar slides open as shown below.

The first button stops the test execution and terminates the servers.
As seen in the following screenshot the background color of the status bar changed to red and at a banner is shown that tells the user that the test execution has been aborted.
Once the Workflow UI has quit, searches and filtering on the Rbel log details as well as on the Web UI are no longer possible.

By clicking on the second button the test execution pauses.
The background color of the status bar and the pause button change to indicate the pause as shown in the following picture.

The test execution will be resumed once the user clicks on the green play button.
The third button opens the Configuration Editor which is explained in detail in this section.

Below the buttons the status box shows how many feature files and how many scenarios were executed and also the amount of failed tests are shown.

In the feature box below each scenario name is displayed.
The names are linked to the test and when the user clicks on the scenario the test is shown in the test execution on the main section.
The green icon in front of the name indicates a passed scenario, the red exclamation mark indicates a failed scenario.
The numbers in square brackets indicate that this is part of an outline scenario, meaning a test scenario that is run multiple times with different test data.

The server box above displays the configured servers, its status (e.g. STARTING, RUNNING, STOPPED) and some outputs of its logs.
When the icon color before the server name is green then the server is up and running correctly.

Below the server box the version number and the build date of the currently used tiger release is displayed.

The status bar can be minimized by clicking on the double arrow or by clicking on any of the icons in the status bar (e.g. status box icon, feature box icon, server box icon, tiger head icon).

The main window of the Workflow UI has two sections: the test execution and the server logs which can be selected by the two buttons on top of the Workflow UI as seen in the picture below.

An additional feature of the Workflow UI is the traffic visualization.
This feature allows to visualize the traffic between the servers under test in a sequence diagram.
The feature needs to be explicitly enabled in the tiger.yaml configuration file.

This will enable a third section in the main window of the Workflow UI where a sequence diagram is displayed.

The sequence diagram shows the messages that were exchanged between the servers under test.
By clicking on a message in the sequence diagram, the corresponding Rbel Log Details will be displayed in the Rbel Log Details section.

The traffic visualization currently supports the following server types: externalJar, externalUrl, zion, docker and compose.

For messages to show up in the sequence diagram they need to be routed through the Tiger Proxy.
This is the case for all the messages originating in the local tiger client and their responses.
If there are additional messages originating on one the servers under test, they need to be routed through the Tiger Proxy as well.
In Zion servers this is automatically configured.
For external jars this can be achieved by configuring the servers with the following VM options:

For the server types docker and compose, we do not yet support the visualization of messages originating on a client port of these servers.

The following screenshot shows the WebUI.
On the left side the request/response pairs are displayed.
The user can see the request type and the error code of the response as well as the timestamp of the request.

On the top right the tiger version and the build date are displayed.
In the middle the full request and response messages are shown with detailed header and body.

To access maps in JEXL/RbelPath the point notations is used. In case of lists use the number of the list entry you want to access, starting with 0, 1, 2 and so on.

There are predefined JEXL contexts which can be used for the query, for example isRequest, isResponse, charset, content or also more
complex contexts like response.statuscode, request.url, message.method etc.
For more details check the InlineJexlToolbox

message.headers.'content-length'.0 == "0" → Use single quotes when using JEXL contexts with a hyphen.

@.body.0.name.content =^ "Jasmin" → check whether the content starts with "Jasmin"

$.body.recordId == "X12349035" → checks for the recordId of a decrypted EPA-VAU-message

$.header.Content-Type == "application/json" → check if the message is a JSON-message

request.method == "GET" → check if request is da GET request

charset =~ "UTF-.*" → check the charset with a regex

empty(response.url)==true oder auch empty(response.url) → url is not set

$.body.recordId == "Y243631459" && charset == "UTF-8" → combines the two criterions

When accessing parameters POST and GET are handled differently.
POST form data requests contain the data as Url encoded query string in the body of the request.
There is no easy way to decode this data generically within Rbel/JEXL.
To help you ease the situation for POST we do have a helper JEXL inline method: !{urlEncoded('value')}
To access POST form data you may use $.body.paramname which will return the URL encoded value.

For GET requests you have two options:

For further help on JEXL please check out the official website (https://commons.apache.org/proper/commons-jexl).

The three parts denote the different part of a JWT: The header claims (header), body claims (body) and signature properties (signature).
RbelWriter will automatically try to sign the given JWT.
For this the key at $.signature.verifiedUsing is consulted and a matching key is searched in the tiger key-database.
This will be filled at start-time by digging through the root-directory of the application recursively and trying to open all found key-files with various default passwords.

Please note that the header-claims have to match the given key, otherwise the signing operation can’t be completed successfully.

As with the JWT, for the JWE all relevant claims are to be found in the appropriate sections.
The signature has been replaced by the encryptionInfo-section.
Here you need to specify the key to be used for the encryption.
Here in this example we are using a public/private key-pair (with the same name as before).
Again the header claims have to match the key used.

Apart from a public/private key-pair you can also use direct keys to encrypt your JWE.
Here is an example:

As we are using a AES 256 bit key the supplied key has to exactly carry 256 bits, Base64 encoded.

To generate a URL you can also use the RbelWriter.
Consult the following structure:

The parameters will be added as query-parameters.
This can be rather useful to construct more complex parameters, for example a dynamically generated JWT.

A Bearer token can also be serialized directly via RbelWriter.
This is very relevant if you want to, for example, generate a JWT on the fly and use it as the Bearer token.
The straight-forward way would be to directly write the Bearer token like so:

Here the whole arrangement will be parsed as a Bearer token (Which is essentially the Word Bearer, followed by a space and any string).
The value of the Bearer token will be parsed as a JSON.
When the result is then serialized, the tgrEncodeAs is interpreted and the JSON will be written as a Base64-encoded JWT.

The following example will produce the same result.
However the overall structure is a JSON, which will be written as a Bearer token ("tgrEncodeAs": "BEARER_TOKEN").
The content of the token is taken from the child-node with the name BearerToken.

Default error object with information about the occurred error

the result of an executed test

The description of a test case

information of which tests were started and where to find the results of the test run

Request the execution of a subset of tests. Multiple specifications will be combined with AND. If one of the tags, sourceFiles, or testUniqueIds is an empty list, it will not be considered in the selection of tests. If all are empty, all tests are selected.

the result of the executed tests

You can find the Serenity compatible with each Tiger version in the [ReleaseNotes](ReleaseNotes.md)

Please first make sure that either the surefire or failsafe plugin is enabled and shown as running in the console.
If you use Junit4 test annotations, you have to make sure that the junit vintage engine from the Junit5 library is included in the dependencies.

More specifically, the error is as follows:

This is due to a dependency conflict which may be solved by an exclusion in the tiger-test-lib:

Apparently you included SLF4J V2 dependencies.
We currently use the logback classic 1.2.x branch, which is delivered in the most recent SpringBoot version.
This is not compatible to SLF4J 2.x.x.

SpringBoot deploys an outdated selenium version.
To solve the conflicts, please use the versions stated in the release notes via dependency managent in the maven pom.xml.

Please make sure that you added the tiger-cloud-extension dependency in the most recent version.

Tiger expects that Docker Daemon starts the container locally.
However, if this is not the case, you may use the environment variable TIGER_DOCKER_HOST to share on which server instance the container is started and the HealthcheckURL is adjusted accordingly.
For purposes of the Gematik SW-factory, the following code snippet is recommended for the pipeline script:

Usually, this only happens when the test suite is started in intellij and TigerCucumberListener is delivered as a plugin in TigerCucumberListener.
This is no longer necessary since v1.3 because the listener is added automatically.
Due to this manual adjustment, two listeners are running that communicate the scenarios twice to the workflow UI.
If this happens in a mvn call, please check the tiger-maven-plugin configuration or the generated driver classes in terms of additional plugins in CucumberOptions.

By stopping the test runs, the workflow UI backend is terminated as well.
You may recognize this by the light-red color of the side bar.
However, navigating in the RbelLog Details Pane requires a running backend.
In addition, RbelPath- and JEXL inspect dialogues are not working.

Inside the tiger.yaml file, you can add a section logging.level: and add a list of packages / classes and the desired logging level.

Use the command below to remove all unused containers.
Or look for containers starting with "tiger", stop and remove them.

Last resort:

and restart docker

When using directly the method de.gematik.test.tiger.proxy.TigerProxy.addAlternativeName() to add multiple alternative names to the TLS certificate of the tiger proxy the following exception may come up:

The tiger proxy uses a mockserver internally which creates a SSLContext when handling the first request.
Adding additional names after the first request will not update the created SSLContext and the exception will be thrown.

A workaround for this behaviour is to explicitly restart the internal mockserver after adding an alternative name.
E.g.:

Das zu jeder Tiger Version kompatible Serenity findet ihr in den [ReleaseNotes](ReleaseNotes.md)

Bitte stell zuerst sicher, dass entweder das surefire oder das failsafe plugin aktiviert ist und auch in der Konsole als ausgeführt angezeigt wird.
Solltest Du Junit4 Test Annotationen verwenden so musst Du noch sicherstellen, dass die junit vintage engine aus der Junit5 Library in den dependencies mit angeführt ist.

Genauer geht es um folgenden Fehler:

Der Grund hierfür ist ein Dependency Konflikt und kann durch eine Exklusion in der tiger-test-lib dependency aufgelöst werden:

Du hast anscheinend Dependencies zu SLF4J V2 eingebunden.
Wir verwenden derzeit den logback classic 1.2.x branch, da dieser in der von uns verwendeten Spring Boot Version mitgeliefert wird.
Dieses ist NICHT kompatibel zu SLF4J 2.x.x!

Spring Boot liefert eine veraltete Version von Selenium aus.
Um die Konflikte zu lösen, bitte die in den ReleaseNotes angeführten Versionen über DependencyManagement im maven pom.xml lösen.

Vermutlich ist die System Property cucumber.junit-platform.naming-strategy.short.example-name (meist im File junit-platform.properties) auf etwas anderes als "pickle" gesetzt.
Wenn diese Property nicht explizit gesetzt wurde, wird sie von Tiger automatisch auf "pickle" gesetzt.

Stelle sicher, dass du die tiger-cloud-extension in der aktuellsten Version als dependency hinzugefügt hast.

Normalerweise geht Tiger davon aus, dass der Docker Daemon die Container am lokalen Rechner startet.
Sollte dies nicht so sein, so kann man Tiger mit der Umgebungsvariable TIGER_DOCKER_HOST mitteilen, auf welchem Rechner die Container gestartet werden und die HealthcheckURL wird dementsprechend angepasst.
Für die Gematik SW-Factory empfiehlt sich folgendes Code Snippet für das Pipeline-Skript:

Passiert eigentlich nur, wenn die Testsuite aus Intellij gestartet wurde und in der RuntimeConfiguration der TigerCucumberListener als plugin mitgegeben wird.
Dies ist seit v1.3 nicht mehr notwendig, weil der Listener automatisch hinzugefügt wird.
Durch den manuellen Eintrag laufen also dann zwei Listener, welche die Szenarien dann auch doppelt an die Workflow UI kommunizieren …​
Sollte dieser Effekt auch bei einem mvn call auftreten, dann bitte die Konfiguration des tiger-maven-plugins überprüfen, bzw. die generierten Treiberklassen bezüglich zusätzlicher Plugins in den CucumberOptions checken.

Durch das Beenden des Testlaufs ist das Backend der Workflow UI auch beendet worden.
Dies kannst Du auch daran erkennen, dass die linke Seitenleiste nun blass rot eingefärbt ist.
Das Navigieren in der RbelLog Details Pane benötigt aber das Backend und klappt daher zum jetzigen Zeitpunkt nicht mehr.
Auch die RbelPath- und JEXL Inspect Dialoge sind nicht mehr funktional.

Inside the tiger.yaml file you can add a section logging.level: and add a list of packages / classes and the desired logging level.

Use the command below to remove all unused containers.
Or look for containers starting with "tiger", stop and remove them.

Last resort:

and restart docker

When using directly the method de.gematik.test.tiger.proxy.TigerProxy.addAlternativeName() to add multiple alternative names to the TLS certificate of the tiger proxy the following exception may come up:

The tiger proxy uses a mockserver internally which creates a SSLContext when handling the first request.
Adding additional names after the first request will not update the created SSLContext and the exception will be thrown.

A workaround for this behaviour is to explicitly restart the internal mockserver after adding an alternative name.
E.g.: