Citrus 2.0 is a major version upgrade and therefore big things should be happening. In the following sections we shortly describe the Citrus evolution. We want you to get a quick overview of what has happened and all the new things in Citrus. So hopefully you can spot your favorite new feature.


In Citrus 1.4 we began to refactor the configuration components in Citrus. This refactoring was finalized in Citrus 2.0 which means that all deprecated classes and api are no longer supported. The classes were removed so you get compilation errors when using those old stuff. If you still use the old configuration see this migration-sheet in order to learn how to upgrade to the new configuration. It is worth to do so! In addition to that we did refactoring in following fields:

  • Reply message correlation In synchronous communication scenarios Citrus optionally correlated messages across send and receive test actions. In default setting the message correlation was disabled. With 2.0 release we changed this behavior to the opposite. Now message correlation is done by default with a default correlation algorithm. So in case you used the DefaultReplyMessageCorrelator in Citrus before you will not have to do so in future as this is done by default. The message correlation gives us more robust tests especially when executing tests in parallel. In the test case you do not have to do anything for proper message correlation.
  • Citrus message API We have refactored the Citrus message API to use custom message objects in endpoints, consumers and producers. This has no affect on your tests or configuration unless you have written endpoint extensions or custom endpoints on your own. You might have to refector your code accordingly. Have a look at the Citrus endpoint implementations in order to see how the new message API works for you.
  • Sleep time in milliseconds This is something that we definitely carry around since the beginning of Citrus. The time values in sleep test action were done in seconds, which is inconvenient when using time periods below one second or non natural numbers. Now you can choose to use milliseconds which is more likely how you should configure time periods anyway. See Section 12.4, “Sleep” for details
  • Auto sleep time in milliseconds We used seconds when using auto sleep in repeat on error container. This led to the fact that we were not able to sleep time periods below one second. Also it was not possible to specify non natural numbers such as 1.5 seconds auto sleep time. We changed to milliseconds which is more likely how you are used to configure time periods anyway. See Section 14.6, “Repeat on error until true” for details
  • Message handler vs. endpoint adapter In previous releases prior to 1.4 we had message handlers on server side that were able to forward in coming requests to message channels or jms destinations. The old message handler implementations were removed in 2.0. Instead you should use the endpoint-adapter implementations. See Chapter 32, Endpoint adapter how that works.
  • XML endpoint reference attribute In a XML test case you reference the message endpoint in the send and receive actions with a special attribute called with. This attribute is no longer supported and was removed. Instead you should use the endpoint attribute which was introduced in Citrus 1.4 and has the exact same functionality.
  • Removed citrus-adapter module The Maven module citrus-adapter was removed. Classes and API moved to citrus-core module. For endpoint adapters do use the new configuration components that were introduced in Citrus 1.4. See Chapter 32, Endpoint adapter for details.
  • WebServiceEndpoint class renamed In terms of package refactoring the was renamed to

Spring framework 4.x

In terms of upgrading the Citrus API dependencies we introduced Spring 4.x versions. This includes the core Spring framework libraries as well as the Spring Integration and Spring WebService project artifacts. So with the major version upgrade lots of API changes were also done in Citrus code in order to meet the new Spring 4.x API. So we recommend for you to also use Spring 4.x version in your Citrus projects.

FTP support

New member of the Citrus family deals with FTP connectivity. The new citrus-ftp module provides a neat ftp server and client implementation so you can send and receive messages vie FTP message transport. Chapter 20, FTP support describes the new functionality in detail.

Functions with test context access

Functions are now able to access the test context. This enables you to access all test variables and other central test related components in a function implementation. Therefore the function Java interface has now an additional test context parameter. Refactor your custom written functions accordingly to meet the new interface rules. See how to write custom functions for details.

Validation matcher with test context access

Just like functions now validation matchers are able to access the test context. This enables you to access all test variables and other central test related components in a validation matcher implementation. The validation matcher Java interface has changed accordingly with an additional test context parameter. Refactor your custom written matcher implementation accordingly to meet the new interface rules.

Message listener with test context access

Message listeners do now also have access to the test context. This is more powerful as you can access test variables and other central components within the test context.


SOAP over JMS was supported in Citrus from the very beginning. Unfortunately you had to always specify the whole SOAP envelope in your test case. SOAP envelope handling is now done automatically by Citrus when using the new SoapJmsMessageConverter. The converter takes care on constructing a proper SOAP envelope message. See Section 16.5, “SOAP over JMS” for details.

Multiple SOAP attachments

When sending and receiving SOAP messages with Citrus as client or server you can add one to many attachments to the message. Before it was only possible to have one single attachment in a message. Now you have no limits in defining SOAP attachments. See Chapter 19, SOAP WebServices for details.

Multiple SOAP XML header fragments

The SOAP header can hold multiple XML header fragments with different namespaces and content. With Citrus 2.0 you are able to construct such a SOAP message with multiple header contents. See Chapter 19, SOAP WebServices for details.

Create variable validation matcher

A new validation matcher implementation is able to create a new variable on the fly. The actual field name is used as variable name and the element value as variable value. The variable name can slo be customized with optional validation matcher parameter. This is a great alternative to the XPath expression evaluating variable extraction. Also very handsome to use this validation matcher in Json message payloads. See Section 34.12, “variable()” for details.

New configuration components

A major part of the Citrus configuration is done in a Spring bean application context. Central Citrus components and features are added as Spring beans to the application context. Now with Citrus 2.0 we have added special configuration components for almost all features. This means that you can easily add configuration using the new XML schema components. See which components are available:

  • Function library Custom function libraries with custom function implementations are now configured with the function-library XML schema components in the Spring application context configuration. See Chapter 33, Functions for details.
  • Validation matcher library Custom validation matcher implementations are now configured with the validation-matcher-library XML schema components in the Spring application context configuration. See Chapter 34, Validation matcher for details.
  • Data dictionary Data dictionaries apply to all messages send and received in test cases. You can define multiple dictionaries using the data-dictionary XML schema components in the Spring application context configuration. See Chapter 35, Data dictionaries for details.
  • Namespace context Configuration of a global namespace context is necessary for XML message payloads and XPath expressions used in the test cases. The namespace-context XML schema component is used in the Spring application context configuration and simplifies the configuration. See Chapter 10, Using XPath for details.

Before/after suite components

When executing test actions before the actual test run you can use the sequence before suite components. We have improved these components to use a special XML schema. This enables easy configuration of both before and after suite actions. In addition to that you can bind the suite actions to special packages, test names or suite names. So you can now have more than one sequence before suite at the same time. According to the environment settings the before suite actions are executed or left out. Last not least we have done the same improvement to the before test actions and we have introduced a after test sequence component for execution after each test. See how this is done in Chapter 37, Test suite actions.

Citrus JMS module

JMS support has been a major part of Citrus from the very beginning. Up to now the JMS features were located in citrus-core Maven module. With Citrus 2.0 we introduced a separate citrus-jms Maven module. This means that you might have to add proper Maven dependency of this new module in your existing project when using JMS. See how this is done in Chapter 16, JMS support.