Tiger User Manual

See chapter Tiger Test Environment Manager for a detailed description and configuration options.

See chapter Tiger Proxy for a detailed description and configuration options.

The Tiger test library provides the following core features:

See chapter Tiger Test Library for a detailed description and usage examples.

The test environment manager instantiates all test nodes configured in the tiger.yaml config file.
It also instantiates one local tiger proxy for the current test suite.
The local 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 test suite can reach the instantiated server node via HTTP and the configured server hostname.

Each tiger proxy can be configured in a multitude of ways: as a reverse or forward proxy with special routing features and content modifications, or in a mesh setup 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 and received over Tiger Proxies using features such as RBelPath, VAU decryption, JSON checker and XML checker.

As Tiger evolves, we have implemented a set of extensions that make your job as a tester easier in areas not directly covered by the Tiger core.
The following extensions are currently available:

See Tiger Extensions for a detailed description of each extension.

We provide a start pom which makes it faster to bootstrap a new test suite project.
You need to extend the tiger-starter-parent pom in your project, and you get a project with all the tiger dependencies and plugins configured to run tests with maven.

You can execute the tests in this project by running:

This will run your cucumber feature files using the Tiger Framework and generate serenity html reports.
For quick configuration we have set the following maven properties, which you can override in your project pom:

More detailed configuration can still be performed directly on the tiger-maven-plugin and maven-failsafe-plugin.
See the following section for details.

We also provide a maven profile which allows you to execute a test suite without the maven failsafe plugin.

With

you can start tiger as a java application without the full maven lifecycle.
This profile is pre-configured to start the Workflow UI with the interactive test selector dialog.
This means the tests will not be run automatically on start up and you can select exactly what you want to execute via the tiger ui.

To use Tiger with your BDD/Cucumber/Serenity based test suite you need to add a few dependencies to integrate with Tiger

And to trigger the test suite’s execution, you will need to add these plugins

For a successful startup you also need a minimum Tiger test environment configuration YAML file in your project root:

and finally a minimal feature file under src/test/resources/features:

With these three files in place you can run the simple dummy test scenario defined in the feature file by issuing

If you are interested in the plugins Tiger uses, please refer to the section ( Maven Plugin Deep Dive).

All exports entries of a node are available for subsequent nodes and can be used in their configuration (e.g. in Docker environment, tiger proxy proxyRoutes, etc.).

Starts any executable JAR archive using java -jar.
The options list is passed directly to the JVM (before -jar), while arguments are passed to the application (after -jar).

The working directory is the place where the jar is executed from.
If workingDir is not set or is empty, the jar’s parent directory is used as working directory for local: sources, or the OS temp folder for downloaded JARs.
A non-existent workingDir is created automatically.
Relative paths for both source and workingDir are resolved relative to the project root (the directory from which Maven is executed).

Tiger will use the following order to try to find a matching file:

By default, Tiger uses the same JVM with which Tiger itself was started.
To use a different JVM set lib.javaHome in tiger.yaml or the environment variable TIGER_LIB_JAVAHOME.

A symbolic node type that does not start any server.
Instead, it instructs the local tiger proxy to route requests for the configured hostname to the given source URL.

This allows the test suite to always address a server by the same fixed hostname (e.g. http://idpServer), while the actual target URL can be changed in the YAML without touching any test code.

Starts a Docker container from a configured image.
Tiger automatically adds the tiger proxy certificate to the container’s OS trust store.
This can be disabled by setting dockerOptions.proxied: false.

To customize the docker container you may alter the entry point command line.
For containers that should exit after a single command you may enable the oneShot property.

The exposed container port is available as ${PORT:xxxx} (where xxxx is the internal container port) in the exports entries.

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.

Starts multiple services defined in one or more Docker Compose YAML files.
Files can be referenced by path or loaded from the classpath (e.g. from inside a JAR).

Tiger copies and processes all compose files into target/tiger-testenv-mgr/<serverId>/ before starting them, replacing all Tiger placeholder expressions.
Because of this flattening, compose files must not reference additional external files.

Starts an additional standalone tiger proxy as an embedded Spring Boot application.
This is useful to intercept and log traffic between two components that do not communicate through the local test suite proxy.

The full tiger proxy configuration (routes, modifications, TLS, etc.) can be used inside tigerProxyConfiguration.
See Tiger Proxy basics for the complete reference.

Installs or upgrades a Helm chart in a local or remote Kubernetes cluster.
Tiger waits until all configured healthcheckPods are running before declaring the node ready.
Port forwarding is set up via exposedPorts so that the test suite can access the services locally.

Starts a httpbin server.
It provides a wide range of ready-to-use HTTP mock endpoints such as /get, /post, /status/{code}, /headers, /delay/{n} and many more.
No external dependency or Docker is required.
This type is ideal for quickly testing HTTP glue code steps without a real backend.

Forward proxies work like a relay station: you send a packet to your destination via the proxy.
The proxy receives the packet, reads the address, and can forward it to wherever it sees fit.
To use a forward proxy, the sender must be aware of it and send the packet accordingly.

This allows the creation of virtual domains, which is used extensively in Tiger.

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 it at their own discretion.
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 forward 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, a GET to http://reverse.proxy.de/my/deep/url might be mapped to http://gematik.de/deep/url, eliminating the /my prefix).

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, as the traffic is addressed directly 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. /foo), 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 selected.
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 of 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:

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.

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 unnecessary is therefore a good idea.

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 require that the ports on all entries in this specific list are given (this does not apply to other routes).

As an additional measure for a more fine-grained matching, you can use criteria.
These are JEXL expressions that 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 unnecessary 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:

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

This will match with both of the following requests:

This option will disable the rewrite of the Host-header in the forwarded request.
This will lead to inconsistent Host-headers in the proxied requests, which might lead to unexpected behavior on the target server. (e.g. when forwarding from http://my.domain/ to http://orf.at/ the Host-header will still contain "my.domain" instead of "orf.at").
Default is false.

The Tiger Proxy automatically probes each HTTPS backend at route-add time to discover its ALPN (Application-Layer Protocol Negotiation) capabilities.
Based on the result, the proxy restricts the protocols it advertises to clients during the TLS handshake — ensuring transparent behavior (the client sees the same protocol it would with a direct connection).

In most cases this works automatically and requires no configuration.
However, for ambiguous setups — such as two routes on the same hostname pointing to different backends with different protocol support — you can explicitly declare the ALPN protocols per route using the alpnProtocols property:

When alpnProtocols is set, the declaration overrides the automatic probe for that route — no probe is performed.
If multiple routes with explicit alpnProtocols declarations match the same client connection (same SNI hostname), the proxy computes the intersection of the declared lists (conservative approach).

Valid protocol identifiers are h2 (HTTP/2) and http/1.1.

TLS can be done via an 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 an http-proxy does NOT reduce the security of the overall protocol.
The security still relies on server-certificate-verification.)

If, however, you cannot 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() that can help you configure the SSLContext in your case, if you use HTTP third party libraries (Unirest, okHttp, RestAssured, etc.) as well as vanilla Java.
If you encounter any problems, please contact us.

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.

The following attributes serverRootCa, forwardMutualTlsIdentity, serverIdentity, and ocspSignerIdentity can be configured via a one-line string or via sub properties.

Example for a one-line string:

Example for sub properties:

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, see next section).

To successfully break 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 necessary certificate on-the-fly during the first connection.

For a forward-proxy this is straightforward: 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 a 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 cannot 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, 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.

The forwardMutualTlsIdentity property specifies the client certificate (identity) that the tiger proxy should use when establishing a mutual TLS (mTLS) connection to an upstream server. This is required if the target server expects the proxy to authenticate itself using a client certificate. You can provide the identity as a string (e.g., myIdentity.p12;changeit;JKS) or as a map with filename, password, and storeType. This ensures secure, authenticated communication between the proxy and the upstream server.

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 issue: 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 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.

In a mesh setup the participating Tiger Proxies may run on different machines whose system clocks are not perfectly synchronised.
Because Tiger uses timestamps to order messages, even small clock differences can cause messages from different sources to appear in the wrong order.

To compensate for this, the receiving Tiger Proxy automatically determines the clock offset to each remote proxy at connection time in an NTP-style fashion.
The resulting offset is applied to all timestamps of messages received from that remote proxy.

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 trace 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:

If the target server is behind another proxy, you can configure a forward proxy to be used:

To enable the use of the tiger proxy for non-HTTP scenarios, you can use the option directReverseProxy:

This will directly forward any request to the given host.
This is a form of reverseProxy, only also applicable for non-http-traffic.
HTTP traffic will still be forwarded through the use of a global reverse proxy.
Other traffic will be directly forwarded, rerouted directly on the TCP layer.
Messages transmitted can still be parsed via RBel.
If the optional flag ignoreConnectionErrors is true, no connection errors will be logged; the default is false.

The directReverseProxy configuration supports an optional list of modifier plugins that can be used to modify traffic at the TCP layer before it is forwarded:

Deactivating this flag turns off all Rbel-Analysis of the incoming traffic.
This is a huge deal in terms of memory- and CPU-consumption, but you will lose all benefits of performing Rbel-Analysis.

Tiger RBel parses and decodes a wide range of formats and protocols out of the box.
The following formats are supported by default (always active):

The following formats are optional and must be explicitly activated:

If blocking is enabled, the tiger proxy will only return the response when message parsing is completed.
This is inadvisable in high-speed scenarios.
It, however, greatly simplifies the test suite (after the communication is concluded the parsed message appears in the log).
Therefore, the blocking is deactivated by default.
The only exception is the local tiger proxy, which WILL block communication until parsing is completed.
For all Tiger Proxies this default behavior can be changed.

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.

Defines the timeout in seconds (supports decimal values) to wait for a previous message before parsing the current message when messages reference each other in mesh setups.
If the referenced previous message doesn’t arrive within this timeframe, the current message will be parsed anyway.
Default is 5.0 seconds.

Grace period in seconds (supports decimal values) for clock skew between mesh nodes when detecting messages that will never arrive.
This compensates for small time differences between different proxy instances.
Default is 10.0 seconds.

Minimum age in seconds (supports decimal values) for previous messages to trigger timeout detection.
If a referenced previous message has a timestamp older than this threshold, it may be considered as "will never arrive" and the current message will be processed immediately.
Default is 30.0 seconds.

Time threshold in minutes (supports decimal values) for considering a mesh connection as "recent".
Timeout detection only applies to connections that are newer than this threshold to avoid false positives in long-running connections.
Default is 5.0 minutes.

This flag activates the rewriting of the host-header.
If activated, the host-header will be rewritten to the target host (only applicably 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.

When enabled, reverse proxy requests that do not match any configured route will be forwarded to the host specified in the incoming Host header.
This is useful when the TigerProxy acts as a transparent reverse proxy in front of a dynamic set of backends, or when clients already set the Host header correctly to the actual backend.

The fallback has the lowest priority: if a configured route matches the request, that route is always used.
Only when no route matches does the Host header fallback kick in.

If the Host header points back to the TigerProxy itself (e.g. localhost on the proxy port), the connection will be closed to prevent infinite loops.

Default is false.

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.

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 a 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 expressions cannot be nested inside each other deeper than 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 cannot 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.
Let’s 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 by 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 that produces log messages 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:

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).

By default the validator iterates messages in registration order (sequence number).
In proxy-mesh setups where upstream traffic can arrive out of chronological order, switch to transmission-timestamp order via tiger.lib.validation.messageSortOrder:

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.

When defining a glue code method, you can use the variables with the names {tigerResolvedString} and {tigerResolvedUrl}.
These will be automatically resolved by the TigerGlobalConfiguration resolver, and the result is injected directly in the java method.

Here an example:

When using this step in a feature file, the passed string and url are resolved before being passed to the java code.
Inside the java code you don’t need to call the resolver again.
The resolved values are also displayed in the Workflow UI and serenity reports.

Depending on the concrete useage, a DataTable may be interpreted by the glue code as a row wise argument or as a column wise argument.
To make it clearer to the user, it may be helpful to highlight the first row or the first column of the table when displaying it in the Workflow Ui.
For that you can use the annotations @FirstColumnKeyTable and @FirstRowKeyTable on your own glue code.

When applying the annotations to a glue code method with a DataTable argument, the datatable will apply a bold formatting to the first column or the first row accordingly.
You can apply both annotations to the same method.

For example, this method is annotated with @FirstColumnKeyTable

and its argument will be displayed like this in the Workflow Ui:

With @FirstRowKeyTable the table will look like this:

RBelObjects are internal data structures used by the Tiger test framework to represent and manipulate parsed message content, such as JSON, XML, or token formats. They allow you to access, modify, and assert values at specific paths within a message using RBelPath expressions (see Understanding RBelPath). RBelObjects enable flexible validation, transformation, and serialization of message data during automated tests.

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 serialized back to a string.
Jexl Expressions are implemented, as for reading a file or for serializing:
'!{rbelObject:serialize("myRbelObject")}'

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.

If you want to use large ASCII art style log banners you may find this class very helpful, for example take a look at the following figure.

Supports ANSI coloring and a set of different fonts.
Furthermore, all banner messages are displayed and highlighted in the Workflow UI, as seen in this figure.

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.

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.

It is possible to configure the Workflow UI to not start all tests automatically at startup.
When setting the following configuration option in the tiger.yaml:

the tests will only be discovered and displayed in the Workflow UI.
That includes all the tests in the feature files, even if they don’t match the "cucumber.filter.tags" configuration.
This allows you to run manually any selection of tests.
The user can then choose which test scenario he/she wants to execute.
This can be done by clicking the play buttons in either the Test Execution pane or in the Status Bar.

Tests can be selected in the sidebar, or an advanced selection modal can be opened by clicking the "Advanced selection…​" button in the Status Bar.

The Test Selector modal window presents the tests in a tree table, where tests are organized by the folder structure of the feature files, and by scenarios within the feature files.
The folder structure is omitted if the feature files are located all in the same folder.

Additionally, the Test Selector modal window allows selecting tests by tags.
The tags are displayed on the right side of the modal window.

By clicking on a tag, all tests with that tag will be selected.
Additionally, one can remove a given tag from the selection or replace the full selection with just the selected tag.

A global search field as well as individual search fields for each column allow filtering the tests by name, tags or description.

It is possible to save the current selection of tests in a file, which can be loaded later on.

This may be useful for collaboration with other team members or for reusing the same selection in future test runs.

After selecting the tests, the user can click the "Run selected tests" button to start their execution.

The topology visualizer displays the test environment configuration in a graphical way. It reads the tiger configuration and displays the configured servers and how they are connected to each other.

You can access the topology visualizer directly from the Workflow UI.

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).

Tiger Zion Extension is a highly configurable mock server designed to simulate a real backend.
It supports the communication protocol HTTP and allows you to define, manipulate, and replay requests and responses.
With Tiger Zion, you can create complex test scenarios, simulate error cases, and validate the integration of your application with Zion systems.
It is ideal for automated, reproducible integration and interface testing, enabling dynamic scenario definition and message manipulation for robust test automation.

More information and source code can be found on GitHub: https://github.com/gematik/tiger-zion

The Tiger-Mail-Extension enables automated testing of email flows within test scenarios.
It provides steps and utilities to send, receive, and validate emails as part of your test cases.
More information and source code can be found on GitLab: https://gitlab.prod.ccs.gematik.solutions/tiger/tiger-mail-extension

The Tiger-Cloud-Extension allows to embed docker-image-based containers, docker compose scripts and even helm charts to local or remote kubernetes clusters.
The GitHub repo is https://github.com/gematik/tiger-cloud-extension.

The Tiger-On-Fhir-extension provides a set of simple BDD steps which can be used to check for valid FHIR content therein.
FHIR stands for Fast Healthcare Interoperability Resources.
The tiger-on-fhir can be found on GitHub https://github.com/gematik/tiger-on-fhir and it uses the Gematik Referenzvalidator located on GitHub https://github.com/gematik/app-referencevalidator.

The Tiger-Konnektor-Management-Extension provides an interface to the KMS system of different connector providers.
It also provides cucumber feature steps to access the different connectors.
This internal gematik extension can be found on GitLab https://gitlab.prod.ccs.gematik.solutions/konnektor/tiger-konnektor-management-extensions.

CATS stands for Card Terminal Simulator.
Tiger-Cats-Extensions offers the option to use the REST interface of CATS as Java functionality or as BDD steps.
This internal gematik extension can be found on GitLab https://gitlab.prod.ccs.gematik.solutions/cats/tiger-cats-extensions.

The Tiger-PSSIM-Extension is an extension for simulating a Primärsystem (PS) in your tests.
It provides a wide range of BDD Steps and covers the majority of PS functionalities.
This internal gematik extension can be found on GitLab https://gitlab.prod.ccs.gematik.solutions/konnektor/tiger-pssim-extension.

The Tiger-Robot-Extension is an extension designed to control the Cardterminal Robot created by the gematik.
This internal gematik extension can be found on GitLab https://gitlab.prod.ccs.gematik.solutions/roboter/tiger-robot-extension.

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

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.

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.

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.: