Changes in Citrus 2.6

Citrus 2.6 comes with a set of new modules that enable completely new aspects of integration testing. Namely these are the new modules for Cucumber behavior driven development and Zookeeper support. Just have a look at the following features that are shipped within the 2.6 box.

Gzip compression

Citrus now supports Gzip message compression. For Http client server endpoints we introduced special compression filters that automatically tak care on compression when the http header Accept-Encoding=gzip or Content-Encoding=gzip is set. For other endpoints we introduced the message type gzip and the message validator gzip-base64 which automatically compresses and decompresses message payloads and enables base64 String comparison for validation purpose. The new compression features are described in http and validation-gzip.

Custom servlet filters

The Citrus http server component now accepts custom servlet filter implementations. This is useful for implementing custom logic on request/response processing such as automatic message compression or caching. You can set one or many custom filter implementations and map those to request paths for the server. Read about this in chapter http.

Escape test variable syntax

Citrus uses test variables and looks for the expressions of type ${variable-name}. Now when this same syntax is part of a message content we run into errors as Citrus wants to find a test variable. At the end Citrus complains about the unknown variable. Therefore we introduced an escape syntax for variables so you can skip the Citrus variable expression evaluation. You can do this by using ${//escaped//} syntax. Read more about this in test-variables.

Configurable XML serializer

We often deal with XML message format and therefore need to parse and serialize XML data. The default XML serializer uses pretty print format and cdata section support. Now sometimes it is mandatory to customize these settings which is possible with the new version. You can add a custom XML serializer in the Spring application context and Citrus will automatically use this implementation and configuration. You can see how it works in chapter validation-xml.

Local message store

We introduced a local message store that automatically saves all exchanged messages (inbound and outbound). This message store can be used to get exchanged messages during and after the test. Test actions as well as test listeners can access the local message store. Read more about this in chapters endpoints, actions-send and actions-receive.

Wait message condition

The wait test action has a new condition. Besides waiting for files to exist and http requests to be responded you can now wait for messages in the local message store. This way you can wait for a certain message to arrive. This is described in chapter actions-wait.

Xpath and JsonPath Function

There are new functions available to evaluate some Xpath or JsonPath expression on a XML/Json source. The source can be a static structure coming from an external file or a message payload stored in the local storage. See how to use this functions in chapter functions.

Static response adapter variables support

Server components can use static response adapters that automatically send response messages to any calling client. The response adapter is now able to use test variables and functions. In addition to that you can map values from the actual request message that has triggered the response adapter by using the local message store in combination with Xpath or JsonPath. Read about this in endpoint-adapter.

Cucumber BDD support

Behavior driven development is more and more coming up also in the integration testing environment. Cucumber is a fantastic behavior driven development library that provides support for BDD concepts with Gherkin. The new Citrus integration with Cucumber enables the mix of Gherkin syntax feature scenarios with Citrus test case execution. You write feature stories as usual and create Citrus test cases with lots of actions for the integration test. See details for this feature in cucumber.

Zookeeper support

Zookeeper from Apache lets you manage configuration with distributed coordination. As a user you create and edit values on a Zookeeper server. Other clients then can retrieve this information. With Citrus you are able to access this information from within a test case. The Zookeeper Citrus client lets you manage information on the Zookeeper server. See details for this feature in zookeeper.

Spring Restdocs support

Restdocs is a fantastic way of generating documentation for RESTful APIs. While exchanging request/response data with the server Restdocs creates documentation information on the data. The documentation includes field descriptions, headers and snippets for body content. With new Citrus version Http clients in Citrus can add Restdoc interceptors that generate the documentation while executing the test cases. This way you are able to document what messages were exchanged in tests. The Restdocs support is also available for the SOAP Http client in Citrus. See details in restdocs.

Hamcrest matcher conditions

Iterating test action containers in Citrus evaluate boolean expressions for determination of how to execute the nested actions in a loop. Also the conditional container executes nested actions based on boolean expression evaluation. The Citrus boolean expression support is limited to very basic operations such as lower than or greater than. Furthermore the combination of boolean expressions with variables has not been supported. Following from that we have improved the boolean expression evaluation mechanism with extension to Hamcrest matchers. So now you can evaluate matchers in iterating conditions. This feature is described in containers-conditionaland containers-iterate.


Citrus provides a new Java fluent API for sending and receiving SOAP related message content. The Java DSL enhancements are based on those of Http. Now you can define SOAP messages with special SOAP action headers more easily. On top of that you can handle SOAP faults on client and server with the fluent API. Checkout soap-webservicesfor details.


Refactoring in terms of simplification and standardization is part of our daily life as a developer. We have been working on improving the Java DSL fluent API for SOAP. We also introduced a more common way of handling the test action containers like iterate, parallel and so on. This leads to some classes and methods that were marked as deprecated. So please have a look at your Java DSL code and if you see some usage of deprecated stuff please use the new approaches as soon as possible. The deprecated stuff will definitely disappear in upcoming releases.

Some of the changes that we have made might hit you right away. These changes are:

  • ws:assert element in SOAP testcase schema has been renamed to ws:assert-fault . This was done for better interoperability reasons with assert action in core schema and to be compliant to send-fault action.

  • Java DSL module has had Maven dependencies to several other modules in Citrus (e.g. citrus-jms, citrus-soap). These dependencies were declared as compile dependencies, which is not very nice as you might not need JMS or SOAP functionalities in your project. We have added optional and provided markers to that dependencies which means that you have to decide in your project which of the modules to include.

You may face some missing dependencies errors when running the Maven project. As a result you need to include the Citrus modules (e.g. citrus-http, citrus-docker, and so on) in your project Maven POM explicitly.