The community is proud to announce the availability of Citrus 4.0.0!

Objectives

Citrus 4.0 is a major release mainly driven by the industry migrating from javax.* to jakarta.* APIs. The new version uses Java 17 and aligns with popular Java enterprise libraries such as Spring Boot and Quarkus. Citrus 4 uses updated versions of many dependency libraries (e.g. Spring 6, Apache Camel 4, Cucumber 7, Selenium 4, Jakarta EE and many more). The proper alignment with those libraries and the evolving of Java’s ecosystem in general is a key driver for Citrus 4.

Of course the new major version also addresses many improvements and fixes. That being said we try to keep breaking changes on a low-level in order to provide a smooth migration from former versions. Due to the breaking changes in the many javax APIs this might not always be possible though. People coming from Citrus 3.x should have a look at the 3.x migration guide.

Here are the main objectives we have with Citrus 4.0

• Java 17
• Move to groupId org.citrusframework
• Update dependencies to latest major versions
• Move from javax.* to jakarta.*
• Polyglot test runner support (XML, Groovy and YAML)
• QuarkusTest runtime support
• Remove deprecated modules and code

Java 17

The Citrus 4.0 bits are compiled with Java 17 (was Java 11 for Citrus 3.x). This means you need to use Java 17 as a minimum to run Citrus.

We recommend to use the following setup:

• Java 17+
• Maven 3.9+
• As runtime one of
  • JUnit Jupiter 5.10+
  • TestNG 7.8+
  • Cucumber 7.14+
  • JUnit 4.13+
  • Quarkus Test 3.4+

Of course this also means that you are able to use the full greatness of evolving Java features such as records, multiline text blocks and so many more.

Maven groupId “org.citrusframework”

Citrus is an Open Source project and promotes the idea of open code and community contributions. For over a decade Citrus has been using the groupId com.consol.citrus because the company ConSol Software GmbH and its employees have been a driving force in creating and maintaining the project since the very beginning.

Still ConSol plays a significant role in the success of Citrus by adapting and promoting the project in so many ways. However, the list of new contributors emerges and Citrus benefits from many community contributions these days.

For the sake of strengthening the Open Source idea we decided to move the Citrus groupId from com.consol.citrus to a more generic org.citrusframework from Citrus 4.0 onwards.

With the move to org.citrusframework we decided to happily comply with the Open Source nature of the project because nowadays, the project receives valuable contributions from many companies.

Please update the groupId in your Maven pom.xml accordingly when updating to Citrus 4.0.

<dependency>
    <groupId>org.citrusframework</groupId>
    <artifactId>citrus-bom</artifactId>
    <version>4.3.3</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

Since the groupId also represents the basic Java package used in Citrus the packages of all Citrus Java classes have also changed from com.consol.citrus to org.citrusframework so please replace all occurrences and imports accordingly as you update.

Please do not worry as it should be nothing more than a search-and-replace operation in your project codebase in order to use the new base package wherever it may be referenced.

Dependency update

Citrus depends on many fantastic libraries and projects. With the move to the Jakarta API many of them hava had major version releases in 2023. Citrus now aligns with the latest and greatest versions of these libraries.

The new library versions used in Citrus 4.0 are:

Move to Jakarta API

Many libraries accomplish the switch from javax.* to jakarta.* APIs. The migration itself can be a tough task and the Citrus team is happy to have tackled this move with the new major version update.

For you as a user this move may not cause much trouble because the Citrus dependencies are all using the new Jakarta APIs already. In case you are using Citrus in combination with an older servlet container or with a library that still uses the javax APIs it may be time to also update these dependencies in your project.

Polyglot test runner support

Citrus provides many ways to write test cases. The most popular ones are using the Java DSL and the Spring bean XML syntax. In addition to that you can now choose to write Citrus tests in pure XML, YAML or Groovy. All of them share the same feature set, so you can adapt the test language to your individual requirements (not everybody is a Java expert and this is fine).

QuarkusTest runtime

Quarkus is an emerging enterprise Java stack that is keen to bring Java as a leading platform into the cloud-native application future. With Citrus 4 you can directly combine the test framework with the test capabilities of Quarkus. The Quarkus test framework provides awesome features such as dev services, auto configuration and first class integration with Testcontainers.

Citrus now provides a Quarkus extension that is able to hook into the QuarkusTest runtime so you can inject Citrus capabilities into your Quarkus test.

Read more about it in docs/reference/index.html#runtime-quarkus.

Removed modules

Sometimes it is the time to say goodbye and a new major version is always a good point to get rid of obsolete and outdated things. Some Citrus modules are declared “end of life” and are being discontinued, some modules will just be moved to a separate code repository.

These modules have been removed from the main Citrus project.

• citrus-java-dsl deprecated Java domain specific language that was based on the TestDesigner interface
• citrus-arquillian Arquillian integration to run Citrus as part of the Arquillian framework
• citrus-jdbc JDBC server implementation that is able to simulate any JDBC driver and database
• citrus-remote Run Citrus via remote Http tunnel on a foreign server

Removing the modules does not mean that these bits are completely gone forever though. Some modules have just been moved out of the Citrus project into new separate code repositories. This is mainly because these modules do have experimental status and updating to Jakarta EE and Java 17 has not been possible at the moment.

The experimental modules moved to separate repositories are:

• citrus-remote lives on in https://github.com/citrusframework/citrus-remote
• citrus-jdbc endpoint module has been moved to https://github.com/citrusframework/citrus-db

The code and functionality of those modules stays the same. Also, the code has already received updates on the major releases such as Spring 6.

It is up to the community though to decide about the future maintenance and release cadence as these modules will not be released automatically with Citrus main project anymore.

Provide feedback and help

Please adapt to using Citrus 4 as soon as possible and give us feedback what is working and what may need more attention. We would love to hear from you how you like Citrus 4! Also the documentation has not been fully updated yet. Any help is much appreciated! So in case you have something to improve of fix just open a PR we are more than happy to receive your contributions!

Thank you!

Let’s use this opportunity to thank everybody involved in making this Citrus 4 release happen. The Citrus community did a tremendous job to brings this all together! The Citrus team is very proud to have a new version of Citrus available that after 16+ years of development still is up-to-date with the latest and greatest software libraries out there! THANK YOU!