Release 2.7

Citrus 2.7 is using Java 8! The Citrus sources are compiled with Java 8 which means that from now on you need at least Java 8 runtime to work with Citrus. With this Java 8 base Citrus is proud to welcome two new crew members for supporting Selenium and Kubernetes in tests. Not enough we have the following features included in the box.

Java 8

Citrus is now using Java 8. This is mainly because we need to move on in using latest versions of Spring Framework, Apache Camel and so on. If you are still stuck on Java 7 you can not update to 2.7 as the Citrus sources are compiled with Java 8. Please contact us in case you really can not update to Java 8 in your project. We can think of a minor bugfix version with Citrus 2.6 base that still supports Java 7 runtime. On the bright side we can now use the full power of Lambda expressions and other Java 8 features in Citrus code base.

Kubernetes support

Citrus is now able to interact with Kubernetes remote API in order to manage pods, services and other resources on the Kubernetes platform. The Kubernetes client is based on the Fabric8 Java client that interacts with the Kubernetes API via REST services. So you can access Kubernetes resources within Citrus in order to change or validate the resource state for containerized testing. This is very useful when dealing with container application environments as part of the integration tests. Please stay tuned for blog posts and tutorial samples on how Citrus can help you test Microservices with Docker and Kubernetes. The basic usage is described in section Kubernetes.

Selenium support

User interface and browser testing has not been a focus within Citrus integration testing until now that we can integrate with the famous Selenium UI testing library. Thanks to the great contributions made by the community especially - especially by vdsrd@github - we can use Selenium based actions and features directly in a Citrus test case. The Citrus Java and XML DSL both provide comfortable access to the Selenium API in order to simulate user interaction within a browser. The mix of user based actions and Citrus messaging transport simulation gives complete new ways of handling complex integration scenarios. Read more about this in chapter Selenium.

Environment based before/after suite

You can enable/disable before and after suite actions based on optional environment or system properties. Users can give property names or property values that are checked before execution. Only in case the environment property checks do pass the actions are executed before/after the test suite run.

WsAddressing header customization

We have improved the header customization options when using SOAP WSAddressing feature. You can now overwrite the default WSAddressing headers per test action in addition to defining the headers on client endpoint component level.

JsonPath data dictionary

Json data dictionary was based on a simple dot notated syntax. Now you can also use more complex JsonPath expressions in order to overwrite elements in Json messages based on the data dictionary settings in Citrus. Read more about that in chapter Data Dictionary.

Java DSL test behavior

Test behaviors in Java DSL represent templates in XML DSL. The behavior encapsulates a set of test actions to a group that can be applied to multiple Java DSL tests. This enables you to combine common test actions in Java DSL with more comfortable reuse of test action definitions. See chapter Behaviors how to use that.

Refactoring

Deprecated APIs and classes that coexisted a long time are now removed. If your project is using on of these deprecated classes you may run into compile time errors. Please have a look at the Citrus API JavaDocs and documentation in order to find out how to use the new APIs and classes that replaced the old deprecated stuff.

Release 2.6.2

Citrus 2.6.2 comes with a set of improvements and features. A big THANK YOU to all people out there using Citrus framework every day making it better with feedback and new ideas. We have lots of improvements that are based on user input. Please keep that great contribution work and have a look at the following change set delivered with version 2.6.2.

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 chapters functions jsonpath and functions xpath.

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.

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

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 BDD support.

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

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 sections Conditional and Iterate.

SOAP Java DSL

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 for details.

Refactoring

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.

Release 2.5

We have added lots of new features and improvements with Citrus ## Namely these are the new modules for RMI and JMX support, a new x-www-form-urlencoded message validator and new functions anc test actions. Just have a look at the following features that made it to the box.

Hamcrest matcher support

Hamcrest is a very powerful matcher library that provides a fantastic set of matcher implementations for message validation purpose. Citrus now supports these matchers coming from Hamcrest library. On the one hand you can use Hamcrest matchers as a Citrus validation matcher as described in Section 3## “assertThat()”. On the other hand you can use Hamcrest matchers now directly using the Citrus Java DSL. See details for this feature in Section 1## “Validate with JSONPath”.

Binary base64 message validator

There is a new message validator implementation that automatically converts binary message content to a base64 encoded String representation for comparison. This is the easiest way to compare binary message content with an expected message payload. See Section ## “Binary message validation” how this is working for you.

RMI support

Remote method invocation is a standard Java technology and API for calling methods on remote objects across different JVM instances. Although RMI has lost its popularity it is still used in legacy components. Testing RMI bean invocation is a hard thing to do. Now Citrus provides client and server support for remote interface invocation. See Chapter 29, RMI support for details.

JMX support

Similar to RMI JMX can be used to connect to remote bean invocation. This time we expose some beans to a managed bean server in order to be managed by JMX operations for read and write. With Citrus 2.5 we have added a client and server support for calling and providing managed beans on a mbean server. See Chapter 30, JMX support for details.

Resource injection

With 2.5 we have added mechanisms for injecting Citrus components to your Java DSL test methods. This is very useful when needing access to the Citrus test context for instance. Also we are able to use new injection of test designer and runner instances in order to support parallel test execution with multiple threads. See the explanations in Section 4.## “Designer/Runner injection” and Section 4.## “Test context injection”.

Http x-www-form-urlencoded message validator

HTML form data can be transmitted with different methods and content types. One of the most common ways is to use x-www-form-urlencoded form data content. As validation can be tricky we have added a special message validator for that. See Section 1## “HTTP form urlencoded data” for details.

Date range validation matcher

Added a new validation matcher implementation that is able to check that a date value is between a certain date range (from and to) The date range is able to focus on days as well as additional time (hour, minute, second) specifications. See Section 3## “dateRange()” for details.

Read file resource function

A new function implementation offers you the possibilities to read file resource contents as inline data. The function is called and returns the file content as return value. The file content is then placed right where the function was called e.g. inside of a message paylaod element or as message header value. See Section 3## “citrus:readFile()” for details.

Timer container

The new timer test action container repeats its execution based on a time expression (e.g. every 5 seconds). With this timer we can repeat test actions with a fixed time delay or constantly execute test actions with time schedule. See Section 1## “Timer” and Section 1## “Stop Timer” for details.

Upgrade to Vert.x 3.2.0

The Vert.x module was upgraded to use Vert.x 3.2.0 version. The Citrus module implementation was updated to work with this new Vert.x version. Learn more about the Vert.x integration in Citrus with Chapter 24, Vert.x event bus support.

Release 2.4

Citrus 2.4 comes with a set of new features especially regarding Apache Camel and Docker integrations. Bugfixes of course are also part of the package. See the following overview on what has changed.

Docker support

Docker and Microservices are frequent topics in software development recently. We have added interaction with Docker in Citrus so the user can manage Docker containers within a test case. Citrus now provides special Docker test actions for building, starting, stopping and inspecting Docker images and containers in a test. See Chapter 27, Docker support for details.

Http REST actions

We have significantly improved the Http REST support in Citrus. The focus is on simplifying the Http REST usage in Citrus test cases. With new Http specific test actions on client and server we can send and receive Http REST messages very easy. See Chapter 17, HTTP REST support for details.

Wait test action

With the new wait test action we can explicitly wait for some remote condition to become true inside of a test case. The conditions supported at the moment are Http url requests and file based conditions. A user can invoke a Http server url and wait for it to return a success Http 200 OK response. This is an awesome feature when waiting for a server to start up before the test continues. We can also think of waiting for a Docker container to start up before continuing. Or you can wait until a file is present on the local file system. See Section 12.16, “Wait” for details.

Camel actions

Citrus has already had support for Apache Camel routes and Camel context loading. Now with 2.4 version we have added some special Apache Camel test actions for interacting with a Camel context and its routes. This enables the tester to create and use a new Camel route on the fly inside a test case. Also Citrus is now able to interact with the Camel control bus accessing route statistics and status information. Also possible are start, stop, suspend, resume operations on a Camel route. See Section 23.6, “Camel route actions” and Section 23.7, “Camel controlbus actions” for details.

Purge endpoints action

Purging JMS queues and in memory channels at test runtime has become a widely used feature especially when aiming to make tests more stable in terms of independent tests. We have added a purge endpoint test action that works on any consumer endpoint. So you do not need to separate between endpoint implementations anymore and more important you can purge server in memory channel components very easy. See Section 12.19, “Purging endpoints” for details.

Release to Maven Central

This is not a new feature but also worth to tell here as it is a significant improvement on the whole framework project. We can now release the Citrus artifacts to Maven central repository. So you do not need the additional labs.consol.de repository in your Maven POM anymore. The labs.consol.de repository will continue to exist though as we will release SNAPSHOT versions of Citrus here in future.

Release 2.3

We want to give you a short overview of what has changed in Citrus 2.3. The release adds some new features and improvements to the box. Bugfixes of course are also part of the package. See the following overview on what has changed.

Test runner and test designer

One of the biggest issues with the Citrus Java DSL is the fact that the Citrus Java DSL methods first build the whole test case together before the actual execution takes place. So calling a Java DSL method send for instance just prepares the sending test action. The actual sending of the message takes place to a later time when all test actions are setup and the test case is ready to run. This separation of design time and runtime of a test case leads to misunderstandings as a Java developer is used to work with statements and method calls that perform immediately. Based on that the mixture of Citrus Java DSL method calls and normal Java code logic in your test may have lead to unexpected behavior. Following from that we decided to refactor the Java DSL method execution. The result is a new TestRunner concept that executes all Java DSL method calls immediately. The old way of building the whole test case before execution is represented with TestDesigner concept. So both worlds are now available to you. See Chapter 4, Test cases for details.

WebSocket support

The WebSocket message protocol builds on top of Http standard and brings bidirectional communication to the Http client-server world. With this release Citrus users are able to send and receive messages with WebSocket connections. The Http server implementation is now able to define multiple WebSocket endpoints. The new Citrus WebSocket client is able to publish messages to the server via bidirectional WebSocket protocol. See Chapter 18, WebSocket support for details.

JSONPath support

Citrus is able to work with Xpath expressions in several fields within the testing domain (overwrite elements, ignore elements, extract values from payloads). Now this support of manipulating message payloads via expressions is extended with JSONPath. Similar to Xpath the JSONPath expression statements enable you to find elements and values within a message payload. Not very surprising the JSONPath expressions work with Json message payloads. With the new release you can overwrite, ignore and manipulate Json elements using JSONPath expressions. See Chapter 11, Using JSONPath for details.

Customize message validators

The framework offers several message validator implementations for different message formats like XML, JSON, plaintext and so on. In addition to that Citrus has a set of Groovy script message validators. All these validator implementations are active by default so you are able to validate incoming messages accordingly in Citrus. Now with this release we added a more comfortable way of changing the framework validation functionality, particular when adding new customized message validator implementations. See Chapter 9, Message validation for details.

Library upgrades

We have upgraded the versions of the major dependency libraries of Citrus. This includes TestNG, JUnit, Spring Framework, Spring WS, Spring Integration, Apache Camel, Arquillian, Jetty and more. So Citrus is now working with up-to-date versions of the whole messaging and middleware integration gang.

Upgrade from Citrus 2.2

Along with new features and improvements we refactored and changed some parts of Citrus so you might have to set things straight when upgrading to 2.3. See the following list of things that might be brought up to you:

  • @CitrusTest annotation: We have moved the @CitrusTest annotation to a more common package. The old package was com.consol.citrus.dsl.annotations.CitrusTest. The new package is com.consol.citrus.annotations.CitrusTest. So you have to change the Java import statements in your Test classes when upgrading.
  • TestResult: We changed the TestResult instantiation when generating the test reports. The TestResult class now works with static instantiation methods for success, skipped and failed tests. This only affects your code when you have created custom test reporters.
  • CitrusTestBuilder deprecation: A major refactoring was done in the TestBuilder Java DSL code. com.consol.citrus.dsl.TestBuilder and all its subclasses were marked as deprecated and will disappear in next versions. So instead we now support com.consol.citrus.dsl.design.TestDesigner which basically offers the same functionality as former TestBuilder. In addition that refactoring brought a new way of executing the Java DSL test cases. Instead of building the whole test case before execution is done as a whole you can now use the com.consol.citrus.dsl.runner.TestRunner implementation in order to execute each test action in the Java DSL immediately. This is a more Java like way of writing Citrus test cases as you can mix Citrus test action execution with normal Java statements as usual. Read more about the new approach in Chapter 4, Test cases

Bugfixes

Bugs are part of our software developers world and fixing them is part of your daily business, too. Finding and solving issues makes Citrus better every day. For a detailed listing of all bugfixes please refer to the complete changes log of each release in JIRA (http://www.citrusframework.org/changes-report.html).

Release 2.2

Citrus 2.2 is a release mostly adding new features as well as improvements to given Citrus features. Bugfixes of course are also part of the package. See the following overview on what has changed.

Arquillian support

Arquillian is a well known integration test framework that comes with a great feature set when it comes to Java EE testing inside of a full qualified application server. With Arquiliian you can deploy your Java EE services in a real application server of your choice and execute the tests inside the application server boundaries. This makes it very easy to test your Java EE services in scope with proper JNDI resource allocation and other resources provided by the application server. Citrus is able to connect with the Arquillian test case. Speaking in more detail your Arquillian test is able to use a Citrus extension in order to use the Citrus feature set inside the Arquillian boundaries. See Chapter 26, Arquillian support for details.

JUnit support

Citrus supports both major players in unit testing TestNG and JUnit. Unfortunately we did not offer the same feature support for JUnit as it was done for TestNG. Now with Citrus 2.2 we improved the JUnit support in Citrus so you are able to use all features with both frameworks. This is especially related to using the @CitrusTest and @CitrusXmlTest method annotations in test classes. See Section 6.2, “Run with JUnit” how it works.

Start/Stop server action

Citrus was missing a dedicated test action to start and stop Citrus server components at tet runtime. With the newly added test actions you are able to start and stop server components as you like within your test case. See Section 12.23, “Start/Stop server instances” with a detailed description.

Citrus Ant tasks

We discontinue to support the Citrus Ant tasks. The Ant tasks were not very stable an lacked full feature support when executing test cases with JUnit in Apache Ant. Instead we added a brief description on how to execute Citrus tests with the well documented and stable default JUnit and TestNG ant tasks. See Section 3.2, “Using Ant” how it works.

Bugfixes

Bugs are part of our software developers world and fixing them is part of your daily business, too. Finding and solving issues makes Citrus better every day. For a detailed listing of all bugfixes please refer to the complete changes log of each release in JIRA (http://www.citrusframework.org/changes-report.html).

Release 2.1

Citrus 2.1 adds some enhancements to the Citrus feature set as well as bugfixes and improvements. See the following overview on what has changed.

SOAP MTOM support

SOAP MTOM stands for Message Transmission Optimization Mechanism which allows you to send and receive large SOAP attachment contents streamed with optimized resource allocation on server and client. Many thanks to community contributions (github/stonator) that made this happen with Citrus SOAP client and server. As a user you can shoose to send and receive SOAP attachments with MTOM optimization. See Section 19.9.3, “SOAP MTOM support” for details.

SOAP envelope handling

In its default behavior Citrus will remove the SOAP envelope for incoming SOAP requests just providing the SOAP body as message payload. This is more straight forward in a test case to perform further validation steps. However it might be mandatory to see the whole SOAP envelope inside the test case for special validation. As a user you can now choose how to handle incoming SOAP envelope by definig the keep-soap-envelope setting on the Citrus SOAP server components. See Section 19.5, “SOAP Envelope handling” for details.

SOAP 1.2 message factory

The Citrus SOAP server component was missing a setting for the SOAP message factory to use. The SOAP message factory implementation decides which SOAP version to use 1.1 or 1.2. Now you can set the message factory on the server component and define the SOAP version to use. See Section 19.6, “SOAP 1.2” for details.

TestNG data provider handling

We improved the TestNG data provider handling in Citrus. Now you can use the usual TestNG data provider annotations in your test methods. TestNG will call the Citrus test case several times with respective parameters provided as test variables. This replaces the old citrusDataProvider mechanism that tried to make things working in a kind of workaround. The new provider handling also supports multiple data providers in a test class. Section 6.1.1, “Using TestNG DataProviders” describes how this is working for you.

Mail message namespace

The Citrus mail components enable message exchange as mail client and server. For validation purpose the components offer a XML mail message representation. We have added a target namespace xmlns=”http://www.citrusframework.org/schema/mail/message” and a XSD schema for this XML mail message representation. From now on you have to use the namespace accordingly in your mail message payloads when sending and receiving mail messages in Citrus. See Chapter 25, Mail support how to use the new XML mail message namespace.

Ssh message namespace

When sending and receiving messages via ssh Citrus provides a XML representation for request and response data. These ssh messages follow a new target namespace xmlns=”http://www.citrusframework.org/schema/ssh/message” and a XSD schema. This means you have to use the namespace accordingly in your ssh message payloads when sending and receiving ssh messages in Citrus. See Chapter 28, SSH support for further details.

Release 2.0

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.

Refactoring

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 com.consol.citrus.ws.WebServiceEndpoint was renamed to com.consol.citrus.ws.server.WebServiceEndpoint

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

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.

Release 1.4

Refactoring

It was time for us to do some code refactoring in Citrus. Many users struggled with the configuration of the Citrus components and project setup was too verbose in some areas. This is why we tried to improve things with working over the basic concepts and components in Citrus.

The outcome is a new Citrus 1.4 which has new configuration components for sending and receiving messages. Also the client and server components for HTTP and SOAP have changed in terms of simplification. Unfortunately refactoring comes along with code deprecation. This is why you have to also change your project code and configuration in the future. This is especially when you have made code adjustments and extensions to the Citrus API.

The good news now is that with Citrus 1.4 both old and new configuration works fine, so you do not have to change your existing project configuration when coming from Citrus 1.3.x and earlier versions. But there is a lot of code marked as deprecated in Citrus 1.4. Have a look at what has been marked as deprecated and update your code to use the new API.

We have set up a migration sheet for users coming from Citrus 1.3.x and earlier versions in order to find a quick overview of what has changed and how to use the new configuration components: Citrus 1.4 migration-sheet

Data dictionaries

Data dictionaries define dynamic placeholders for message payload element values in general manner. In terms of setting the same message element across all test cases and all test actions the dictionary provides an easy key-value approach.

When dealing with any kind of message payload Citrus will ask the data dictionary for possible translation of the message elements contained. The dictionary keys do match to a specific message element defined by XPath expression or document path expression for instance. The respective value is then set on all messages in Citrus (inbound and outbound).

Dictionaries do apply to XML or JSON message data and can be defined in global or specific scope. Find out more detailed information about this topic in Chapter 35, Data dictionaries

Mail adapter

With the new mail adapter you are able to both send and receive mail messages within a test case. The new Citrus mail client produces a mail mime part message with usual mail headers and a text body part. Optional attachment parts are supported, too.

On the server side Citrus provides a SMTP server to accept client mail messages. The incoming mail messages can have multiple text parts and attachment parts. As usual you can validate the incoming mail messages regarding headers and payload with the well known validation capabilities in Citrus.

Read more about the new mail module in Chapter 25, Mail support

Endpoint adapter

Endpoint adapters help to customize the behavior of a Citrus server such as HTTP or SOAP web servers. The endpoint adapter is responsible of creating an endpoint that responds to inbound requests. You can customize the behavior so the Citrus server handles incoming requests as you like.

By default the Citrus server uses a channel endpoint adapter so incoming messages get forwarded to an in memory message channel. There are several other implementations available as endpoint adapter. Read more about that in Chapter 32, Endpoint adapter

Global variables component

We added a global variables XML configuration component for more comfortable usage in basic Spring application context configuration. The component is able to create new global variables that are valid across all Citrus test cases. This can also be done by loading a property file from an external file resource. Find out how to us it in ???

Json text validator mode

The Json text validator is now able to operate in two different modes. The strict mode is the default mode and validation includes also a strict check on all sub-objects and JSON array elements. So if there is an object missing the validation will fail immediately. Sometimes it may be accurate to only validate a subset of all JSON objects in the data structure. Therefore the non-strict mode does not check on object attribute counts. See more description in Section 9.3, “JSON message validation”

HTTP REST specific Java DSL options

When sending and receiving HTTP messages on REST APIs you can now use interface specific options in the Java DSL. This refers to request uri, context path, query parameters and HTTP status codes for instance. With this enhancement you are now more comfortable in handling REST API calls in Citrus. Find out how to us it in Chapter 17, HTTP REST support

SOAP HTTP validation

While receiving SOAP messages over HTTP we are now able to also verify the used HTTP uri, context-path and query parameters. You can expect clients to use those values in your receive action as you would do in normal HTTP communication within Citrus. This completes the HTTP server validation when using SOAP over HTTP. Read more about it in Chapter 19, SOAP WebServices

Apache Camel integration

Apache Camel is a great enterprise integration platform that implements the enterprise integration patterns for building powerful mediation and routing rules for message based integration applications. With the new support for camel endpoints in Citrus you can interact with Apache Camel components for sending and receiving messages. Apache Camel offers a fine support for different message transports that now can be used in Citrus also. In addition to that you can put your Camel application to the test with loading of the Apache Camel context with all your route definitions. Citrus is able to interact with these routes in asynchronous and synchronous communication scenarios. Read about it in Chapter 23, Apache Camel support.

Vert.x integration

Vert.x is a very powerful application platform that provides scalable messaging for several message transports such as HTTP, WebSockets, TCP and more. Vert.x also has a distributed event bus that connects multiple Vert.x instances across the network. With Citrus 1.4 the Vert.x platform is integrated with Citrus event bus endpoints. So you can participate in communicating to the Vert.x event bus from Citrus test case. This enables you to add automated integration tests to the Vert.x platform. Read about that in Chapter 24, Vert.x event bus support.

Dynamic endpoint components

Endpoints represent the base component in Citrus for sending and receiving messages. The endpoint usually is defined inside the Citrus Spring application context as Spring bean component. Now it is also possible to create dynamic endpoint definitions at test runtime. This comes in very handy when you just want to send or receive a message with Citrus as is. You do not need to add the complete endpoint configuration but only use a special endpoint uri pattern. Citrus will create the endpoint at runtime automatically. Learn how to use the dynamic endpoint pattern in Chapter 31, Dynamic endpoint components.

Release 1.3

@CitrusTest and @CitrusXmlTest annotations

With the new Java DSL capabilities Citrus created new ways of executing test cases within a TestNG or JUnit test class. Now we even improved the usage here with two new annotations @CitrusTest and CitrusXmlTest. The integration into the unit test class has never been easier for you.

The new Citrus annotations go directly to your unit test methods. With this enhancement you can have multiple Citrus test cases in one single Java class and the Citrus tests now are able to coexist with other unit test methods. You can even mix Java DSL and XML Citrus test cases in a single Java class.

The XML Citrus tests can be grouped to a single Java class with multiple XML files loaded during execution. There is even a package scan for all Citrus XML files within a directory structure so you do not have to create a Java class for each test case anymore.

We have changed the documentation in this guide so you can see how to use the new annotations. For detailed overview see ???. Also see our Citrus blog where we continuously describe the many possibilities that you have with the new annotations.

@CitrusParameters annotation

Citrus is able to use the fabulous TestNG data provider capabilities in order to execute a test case several times with different data provided form external resources. The new @CitrusParameters annotation helps to set parameter names which are used as test variable names in the test case.

Schema repository configuration components

Defining schema repositories and schemas (xsd, wsdl) is common use in Citrus. We have added XML bean definition parsers so defining those components is less verbose. You can use the Citrus citrus:schema-repository and citrus:schema components in your Spring application context configuration. The components do receive several attributes for further configuration. XSD, WSDL and schema collections are supported here.

Checkout ??? for examples how to use the new configuration components.

Change date function

We have added a new Citrus function citrus:changeDate() that is available for you by default. The function changes a given date value adding or removing a datetime offset (e.g. year, month, day, hour, minute, second). So you can manipulate each date value also those of dynamic nature coming with some message.

See Section 33.29, “citrus:changeDate()” for examples and detailed syntax usage of this function.

Weekday validation matcher

The new weekday validation matcher also works on date values. The matcher checks that a given date value evaluates to a expected day of the week. So the user can check that a date field is always a saturday for instance. This is very helpful when checking that a given date value is not a working day for example.

See Section 34.11, “isWeekday()” for some more detailed description of the matcher’s capabilities.

Java DSL

Citrus users, in particular those with development experience, do often tell me about the nasty XML code they have to deal with for writing Citrus test definitions. Developers want to write Java code rather than XML. Although I personally do like the Citrus XML test syntax we have introduced a Java DSL language for writing Citrus tests with Java only.

We have introduced the Java DSL to all major test action features in Citrus so you can switch without having to worry about loosing functionality. Details can be seen in the test action section where we added Java DSL examples almost everywhere (Chapter 12, Test actions). The basic Java DSL setup is described in Chapter 4, Test cases.

XHTML message validation

Message validation for Html code was not really comfortable as Html does not confirm to be wellformed and valid XML syntax. XHTML tries to close this gap by automatically resolving all Html specific XML syntax rule violations. With Citrus 1.3 we introduced a XHTML message validator which does the magic for converting Html code to proper wellformed and valid XML. In a test case you can then use the full XML validation power in Citrus in order to validate incoming Html messages. Section Section 9.4, “XHTML message validation” deals with the new validation capabilities for Html.

Multiple SOAP fault detail support

SOAP fault messages can hold many SOAP fault detail elements. Citrus was able to handle a single SOAP fault detail on sending and receiving test actions from the very beginning but multiple SOAP fault detail elements were not supported. Fortunately things are getting better and you can send and receive as many fault detail elements as you like in Citrus 1.3. For each SOAP fault detail you can specify individual validation rules and expectations. See Section 19.7, “SOAP faults” for detailed description.

Jetty server security handler

With our Jetty server component you can set up Http mock servers very easy. The server is automatically configured to accept Http client connections and to load a Spring application context on startup. Now you can also set some more details on this automatic server configuration (e.g. server context path, servlet names or servlet mappings). In addition to that you can access the security context of the web container. This enables you to set up security constraints such as basic authentication on server resources. Clients are then forced to authenticate properly when accessing the server. Unauthorized users will get 401 access denied errors immediately. See Section 17.7, “HTTP server basic authentication” for details. Of course this also applies to our SOAP WebService Jetty server components (Section 19.11, “SOAP server basic authentication”).

Test actors

We introduced a new concept of test actors for sending and receiving test actions. This enables you to link a test actor (e.g. interface partner application, backend application) to a test action in your test. Following from that you can enable/disable test actors and all linked test actions very easy. This enables us to reuse Citrus test cases in end-to-end test scenarios where not all interface partners get simulated by Citrus. If you like to read more about this concept follow the detailed instruction in Chapter 36, Test actors.

Simulate Http error codes with SOAP

Citrus provides SOAP WebServices server simulation with clients connecting to the server sending SOAP requests. As a server Citrus is now able to simulate Http error codes like 404 Not found and 500 Internal server error. Before that the Citrus SOAP server had to always respond with a proper SOAP response or SOAP fault. See Section 19.8, “Send HTTP error codes with SOAP” for details.

SSH server and client

The Citrus family has raised a new member in adding SSH connectivity. With the new SSH module you are able to provide a full stack SSH server. The SSH server accepts client connections and you as a tester can simulate any SSH server functionality with proper validation as it is known to Citrus SOAP and HTTP modules. In addition to that you can also use the Citrus SSH client in order to connect to an external SSH server. You can execute SSH commands on the SSH server and validate the respective response data. The full description is provided in Chapter 28, SSH support.

ANT run test action

With this new test action you can call ANT builds from your test case. The action executes one or more ANT build targets on a build.xml file. You can specify build properties that get passed to the ANT build and you can add a custom build listener. In case the ANT build run fails the test fails accordingly with the build exception. See Section 12.22, “Running Apache Ant build targets” for details.

Polling interval for reply handlers

With synchronous communication in Citrus we always have a combination of a synchronous message sender and a reply handler component. These two perform a handshake when passing synchronous reply messages to the test for further processing such as message validation. While the sender is waiting for the synchronous response to arrive the reply handler polls for the reply message. This polling for reply messages was done in a static way which often led to time delays according to long polling intervals. Now with Citrus 1.3 you can set the polling-interval for the reply handler as you like. This setting is valid for all reply handler components in Citrus (citrus-jms, citrus-http, citrus-ws, citrus-channel, citrus-shh, and so on).

Upgrading from version 1.2

If you are coming from Citrus 1.2 you may have to look at the following points in order to have a smooth upgrade to the new release version.

  • Jetty version upgrade We are using Jetty a lot for starting Http server mocks within Citrus. In order to stay up to date we upgraded to Jetty 8.1.7 version with this Citrus release. This implies that package names did change for Jetty API. In general there is no conflict for you as a Citrus user, but you may want to adjust your logging configuration according to new Jetty packages. Jetty package names did change from ord.mortbay to org.eclipse.jetty.
  • Spring version upgrade Staying up to date with the versions of 3rd library dependencies is quite important for us. So we upgrade our dependencies to newer versions with each release. As we did only upgrade minor versions there is no significant change or problems to be expected. However you may take care on versions and release changes in the Spring world for details and migration.
  • TIBCO module We decided to put the TIBCO module separately as it is a very special connectivity adapter for TIBCO software only. So you will not find the TIBCO module within the Citrus distribution anymore. We will maintain a TIBCO connectivity adapter separately in the future.

Release 1.2

Spring version update

We have some major version upgrades in our Spring dependencies. We are now using Spring 3.1.1, Spring Integration 2.1.2 and SpringWS 2.1.0. This upgrade was overdue for some time and is definitely worth it. With these upgrades we had to apply some changes in our API, too. This is because we are using the Spring classes a lot in our code. See the upgrade guide in this chapter for all significant changes that might affect your project.

New groovy features

Citrus extended the possibilities to work with script languages like Groovy. You can use Groovy’s MarkupBuilder to create XML message payloads. Your Groovy code goes right into the test case or comes from external file. With MarkupBuilder you do not need to care about XML message syntax and overhead. Just focus on the pure message content. You can read the details in Section 12.2.4, “Groovy MarkupBuilder”.

Further Groovy feature goes to the validation capabilities. Instead of working with XML DOM tree comparison and XPath expression validation you can use Groovy XMLSlurper. This is very useful for those of you who need to do complex message validation and do not like the XML/XPath syntax at all. With XMLSlurper you can access the XML DOM tree via named closure operations which feels great. This especially comes in handy for complex generic XML structures as you can search for elements, sort element list and use the powerful contains operation. This is all described in Section 9.1.4, “Groovy XML validation”.

Some other Groovy support extension comes in SQL result set validation (Section 12.3.3, “Groovy SQL result set validation”). When reading data from the database someone is able to validation the resulting data row set with Groovy script. The script code easily accesses the rows and columns with Groovy’s out-of-the-box list and map handling. This adds very powerful validation to multi-row data sets from the database.

SQL multi-line result set validation

In this new Citrus version the tester can validate SQL Query results that have multiple rows. In the past Citrus could only handle a single row in the result set. Now this new release brings light into the dark. See also the new Groovy SQL result set validation which fits brilliant for complex multi-row SQL result set validation. The details can be found in Section 12.3.2, “SQL query”

Extended message format support

In previous versions Citrus was primary designed to handle XML message payloads. With this new release Citrus is also able to work with other message formats such as JSON, CSV, PLAINTEXT. This applies to sending messages as well as receiving and particularly validating message payloads. The tester can specify several message validators in Citrus for different message formats. According to the expected message format the proper validator is chosen to perform the message validation.

We have implemented a JSON message validator capable of ignoring specific JSON entries and handling JSONArrays. We also provide a plain text message validator which is very basic to be honest. The framework is ready to receive new validator implementations so you can add custom validators for your specific needs.

New XML features

XML namespace handling is tedious expecially if you have to deal with a lot of XPath expressions in your tests. Before you had need to specify a namespace context for the XPath expression every time you use them in your test - now you can have a central namespace context which declares namespaces you use in your project. These namespaces identified by some prefix are available throughout the test project which is much more maintainable and easy to use. See how it works in Section 10.4, “XML namespaces in XPath”.

SOAP support improvements

WsAddressing standard is now supported in Citrus (Section 19.12, “WS-Addressing support”). This means you can declare the specific WsAddressing message headers on message sender level in order to send messages with WsAddressing feature. The header is constructed automatically for all SOAP messages that are sent over the message sender.

Dynamic SOAP endpoint uri resolver enables you to dynamically address SOAP endpoints during a test. Sometimes a message sender may dynamically have to change the SOAP url for each call (e.g. address different request uri parts). With a endpoint uri resolver set on the message sender you can handle this requirement very easy. The tip for dynamic endpoint resolving was added to ???

We also simplified the synchronous SOAP HTTP communication within test cases. In previous versions you had to build complex parallel and sequential container constructs in order to continue with test execution while the SOAP message sender is waiting for the synchronous response to arrive. Now you can simply fork the message sending action and continue with further test actions while synchronous SOAP communication takes place. See the Section 19.13, “SOAP client fork mode” for details

Some really small change introduced with this release is the fact that Citrus now logs SOAP messages in their pure nature. This means that you can see the complete SOAP envelope of messages in the Citrus log files. This is more than helpful when searching for errors inside your test case.

Http and RESTful WebServices

We have changed Http communication components for full support of RESTful WebServices on client and server side. The Http client now uses Spring’s REST support for Http requests (GET, PUT, DELETE, POST, etc.). The server side has changed, too. The Http server now provides RESTful WebServices and is compliant to the existing SOAP Jetty server implementation in Citrus. If you want to upgrade existing projects to this version you may have to adjust the Spring application context configuration to some extent.

For details have a look at the upgrade guide (???) in this chapter or find detailed explanations to the new Http components in Chapter 17, HTTP REST support.

HTML reporting

Citrus provides HTML reports after each test run with detailed information on the failed tests. You can immediately see which tests failed in execution and where the test stopped. Section 40.3, “HTML reports” provides details on this new feature.

Validation matchers

The new validation matchers will put the message validation mechanisms to a new level. With validation matchers you are able to execute powerful assertions on each message content element. For instance you can use the isNumber validation matcher for checking that a message value is of numeric nature. We added several matcher implementations that are ready for usage in your test but you can also write your custom validation matchers. Have a look at Chapter 34, Validation matcher for details.

Conditional container

The new conditional test action container enables you to execute test actions only in case a boolean expression evaluates to true. So the nested test actions inside the container may be not executed at all in case a condition is not met. See Section 14.2, “Conditional” for details.

Support for message selectors on message channels

Spring Integration message channels do not support message selectors like JMS queues do for example. With Citrus 1.2 we implemented a solution for this issue with a special message channel implementation. So you can use the message selector feature also when using message channels. Go to Section 21.3, “Message selectors on channels” for details.

New test actions

We introduced some completely new test actions in this release for you. The new actions are listed below:

Purge message channel action (Section 12.18, “Purging message channels”) See Chapter 12, Test actions for detailed instructions how to use the new actions.

New functions

We introduced some new default Citrus functions that will ease the testers life. This includes commonly used functions like encoding/decoding base64 bindary data, escaping XML and generating random Java UUID values. These are the new functions in this release:

  • citrus:randomUUID()
  • citrus:cdataSection()
  • citrus:encodeBase64()
  • citrus:decodeBase64()
  • citrus:digestAuthHeader()
  • citrus:localHostAddress()

See Chapter 33, Functions for detail descriptions of each function.

Upgrading from version 1.1

If you are coming from Citrus 1.1 final you may have to look at the following points.

  • Spring version update We did some major version upgrades on our Spring dependencies. We are now using Spring 3.1.1, Spring Integration 2.1.2 and SpringWS 2.1.0. These new major releases bring some code changes in our Citrus API which might affect your code and configuration, too. So please update your configuration, it is definitely worth it!
  • Spring Integration headers: With 2.0.x version Spring Integration has removed the internal header prefix (“springintegration_”). So in some cases you might use those internal header names in your test cases in order to synchronize synchronous communication with internal message ids. Your test case will fail as long as you use the old Spring internal header prefix in the test. Simply remove the header prefix wherever used and your test is up and running again.
  • Message validator: You need to specify at least one message validator in the Spring application context. Before this was internally a static XML message validator, but now we offer different validators for several message formats like XML and JSON. Please see the Java API doc on MessageValidator interface for available implementations. If you just like to keep it as it was before add this bean to the Spring application context:
  
<bean id="xmlMessageValidator" class="com.consol.citrus.validation.xml.DomXmlMessageValidator"/>
  • Test suite: We have eliminated/changed the Citrus test suite logic because it duplicates those test suites defined in TestNG or JUnit. In older versions the tester had to define a Citrus test suite in Spring application context in order to execute test actions before/after the test run. Now these tasks before and after the test run are decoupled from a test suite. You define test suites exclusively in TestNG or JUnit. The test actions before/after the test run are separately defined in Spring application context so you have to change this configuration in your Citrus project. See Chapter 37, Test suite actions for details on this configuration changes.
  • JUnit vs. TestNG: We support both famous unit testing frameworks JUnit and TestNG. With this release you are free to choose your prefered one. In this manner you need to add either a JUnit dependency or a TestNG dependency to your project on your own. We do not have static dependencies in our Maven POM to neither of those two. On our side these dependencies are declared optional so you feel free to add the one you like best to your Maven POM. Just add a JUnit or TestNG dependency to your Maven project or add the respective jar file to your project if you use ANT instead.