Migration guide: Citrus 3.x to 4.x

Citrus 4.0 is the latest and greatest release version of the test automation framework and it provides some major changes that you may want to review when updating. This page is here to collect migration steps that users need to perform when upgrading from former Citrus versions.

If you still have issues while updating to Citrus 4 please do not hesitate to let us know so we can add potential migration steps here, too.

In general, the Citrus samples repository is also a good source to learn how things are working with Citrus 4. All samples have been updated to Citrus 4 on the main branch so feel free to have a look and see how it works.

Table of contents

• New groupId org.citrusframework
• Java 17 & Jakarta APIs
• String & resource utils

---

New groupId org.citrusframework

One of the major changes in Citrus 4.0 is the adjustment of the Maven artifact groupId. The groupId has changed from com.consol.citrus to org.citrusframework. This affects all Citrus Maven artifacts.

So this is what you may want to use in your Maven pom.xml to use Citrus 4.0

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

Since the groupId also represents the basic Java package in Citrus the packages of all Citrus Java classes have also changed. When a Java class has been using com.consol.citrus as a base package it now uses org.citrusframework. Please replace all occurrences and imports accordingly as you update your project.

Java 17 & Jakarta APIs

When updating to Citrus 4 you need to use Java 17 as a minimum to be able to run Citrus in your testing cycle. Also with the move to new major versions of dependency libraries such as Spring, Apache Camel, Selenium, Cucumber and so on you should be starting to use the jakarta.* APIs instead of javax.*

Basically all Citrus dependency libraries and Citrus itself now uses the Jakarta APIs. So please make sure to also use Jakarta APIs in your project when running Citrus (e.g. use a up-to-date Servlet container).

String & resource utils

Citrus 4 continues to reduce the amount of library dependencies in its core modules such as citrus-api and citrus-base to an absolute minimum. In this manner the Spring String utilities (such as StringUtils.hasText()) have been replaced with own implementations and Java 11+ capabilities (e.g. Strings.join()).

The same approach was used to replace the Spring resource utilities with an own implementation representing different types of resources such as "classpath" and "file system" resources.

As a result of this citrus-api and citrus-base does not depend on Spring Framework utils anymore. This does not mean that Spring is not used anymore in Citrus though. Other modules (e.g. many endpoint implementations in Citrus) do use Spring as a direct dependency also in Citrus 4.

The Citrus core APIs that have been using the Spring resource utilities do now use the Citrus internal resource utilities. When updating to Citrus 4 you may face some compilation errors in your code due to that adjustment.

It should be quite easy to resolve these errors as the Citrus resource utilities are available as a replacement.

Citrus 3.x

$(http()
    .client(todoClient)
    .send()
    .post("/api/todolist")
    .message()
    .body(new ClassPathResource("templates/todo.json")));

Citrus 4.x

$(http()
    .client(todoClient)
    .send()
    .post("/api/todolist")
    .message()
    .body(Resources.fromClasspath("templates/todo.json")));

The following resource implementations are available in Citrus.

Citrus 4.x

Resource cpr = Resources.fromClasspath("templates/todo.json");
Resource fsr = Resources.fromFileSystem("templates/todo.json");

Resource classpathRes = Resources.create("classpath:templates/todo.json");
Resource classpathContextualRes = Resources.create("classpath:todo.json", Todo.class);
Resource fileSystemRes = Resources.create("file:templates/todo.json");
Resource byteRes = Resources.create("Citrus rocks!".getBytes());
Resource urlResource = Resources.create("http://some/path");
Resource jarResource = Resources.create("jar:file-in-jar.txt");