The Citrus community is thrilled to announce the general availability of Citrus 5.0.0! After two milestone releases and extensive testing by early adopters, the next major version of the Citrus integration testing framework has landed.

AI generated with Google Gemini

Why Citrus 5?

The Java ecosystem has taken significant leaps forward. Spring Framework 7, Spring Boot 4, Jackson 3, JUnit 6, Quarkus 3.38 and Apache Camel 4.21 all represent new major versions that come with breaking changes and modern API improvements. Citrus 5 aligns with these releases so you can use the latest enterprise Java libraries alongside your integration tests without dependency conflicts.

If you want to learn more about the motivation and background, check out our earlier post on getting ready for Citrus 5.0.0.

What’s new

Here is a summary of the most important changes in Citrus 5.0.0.

Updated technology stack

Citrus 5 brings a comprehensive update of the core dependency stack:

Citrus 5.0 still supports Java 17 as a minimum but aligns with Java 21 as the recommended LTS baseline and adds Java 25 support. ActiveMQ Classic has been replaced by Apache Artemis as the default JMS broker in tests and samples.

Java module system (JPMS) support

One of the largest efforts in Citrus 5 is the resolution of split packages across all modules (#1054). In previous versions several Citrus modules exported classes into the same Java package, which is incompatible with the Java Platform Module System. Citrus 5 reorganizes the entire package structure so that every module owns a clean, disjoint set of packages. This prepares Citrus for first-class use on the module path and improves compatibility with modern build tools and runtimes that enforce module boundaries.

Citrus MCP server

Citrus 5 introduces a Model Context Protocol (MCP) server that exposes the framework’s test vocabulary, endpoint configurations and action catalog to AI coding assistants (#1505). The MCP server is published as a Claude Code plugin via JBang (#1550) and also ships with a migration guide resource (#1634), a migration prompt (#1658) and a settings catalog (#1659) to help both humans and AI assistants navigate the framework.

Expanded Testcontainers support

The Testcontainers module gains several new container implementations:

• Native Apache Kafka container as a lightweight alternative to the Testcontainers Kafka module (#1559)
• Strimzi Kafka container for teams already using Strimzi in Kubernetes (#1555)
• Floci container support as an alternative AWS test service provider (#1553)
• Automatic Kafka topic creation on container start (#1558)
• Localstack auth token support for authenticated Localstack usage (#1551)
• Redpanda SASL/authorization support (#1520)

Message processors

Citrus 5 adds a comprehensive set of message processors for transforming message payloads inline during send and receive actions:

• JSON and XML marshalling/unmarshalling processors for data format conversion (#1645)
• Formatting processors for JSON, XML and SOAP that pretty-print payloads for better readability in test output (#1647)
• Camel data format support for unmarshal operations in YAML DSL message processing (#1643)
• Full YAML DSL support for message processors (#1533)

YAML and XML DSL improvements

The YAML and XML test DSLs receive several usability improvements:

• Beans configuration support in both YAML and XML DSL so you can define helper beans directly in your test definitions (#1580)
• Typed endpoints schema for XML DSL with autocompletion in IDEs (#1519)
• Improved JSON Schema quality for the Citrus Test DSL with corrected types, oneOf generation and default values (#1609)

Apache Camel CLI and infrastructure services

The former “JBang” integration has been rebranded to Camel CLI (#1601) and now also supports the Camel Launcher CLI jar as an alternative to JBang (#1602). Camel infrastructure services gain several quality-of-life improvements:

• Fixed port configuration support (#1588)
• Schema examples and autocompletion for service names (#1593)
• Automatic dependency resolution in JBang (#1594)
• Dynamic bean reference propagation from Citrus to Camel endpoints (#1667)

Logging redesigned

The logging output has been redesigned for clearer test workflow visibility (#1586). The new logging concept provides structured output that makes it easier to follow the test execution flow, especially in CI environments where you need to quickly identify what went wrong.

Java DSL improvements

• Simplified message payload builders — the Java DSL now provides more direct access to message payload construction (#1639)
• Test variables in annotation config — use Citrus test variables directly in annotation-based configuration (#1527)
• ServiceLoader SPI fallback for ResourcePathTypeResolver enables component discovery without Spring context scanning (#1652)

Code modernization

The codebase has undergone significant modernization: value classes have been converted to records where appropriate, code has been updated to use lambdas, try-with-resources, enhanced switch expressions, and compiler warnings have been resolved across all modules (#1592).

Migration from Citrus 4.x

The migration from Citrus 4.x to 5.0 primarily involves updating your dependency versions and adapting to the new package structure introduced by the JPMS work. A comprehensive migration guide is available on the Citrus wiki covering all required changes in detail.

The Citrus MCP server also ships with an enhanced migration prompt, making AI-assisted migration very straightforward. Simply install the Citrus MCP server plugin in your AI coding assistant and let it guide you through the package renames, dependency updates and API changes automatically.

Update the Citrus BOM in your pom.xml:

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

Key migration notes:

• Package renames — the split package resolution moved classes to new packages. The migration guide lists all renames; most can be resolved with IDE “Optimize Imports”. The most common moves include TestActionSupport → o.c.dsl, NamespaceContextBuilder → o.c.api.xml.namespace, and XsdSchemaRepository → o.c.xml.schema.
• Artifact rename — citrus-junit5 has been renamed to citrus-junit-jupiter. Update your pom.xml dependency accordingly.
• Spring Framework 7 — if you use the Spring Framework to run tests with Spring’s Inversion of Control bean definition container follow the excellent guides for upgrading to Spring 7 and Spring Boot 4. Non-Spring-Boot setups may need to add an explicit spring-expression dependency.
• Jackson 3 — Jackson 3 changed both Maven coordinates (group ID com.fasterxml.jackson.core → tools.jackson.core) and Java packages (com.fasterxml.jackson.databind → tools.jackson.databind). Update your imports and dependency declarations if you use Jackson APIs directly.
• JUnit 6 — if you use the Citrus JUnit runtime, update to the JUnit 6 extension API.
• ActiveMQ → Artemis — if your tests use the JMS module with ActiveMQ Classic, switch to the Apache Artemis dependency.
• Camel JBang → CLI — the jbang() DSL method, <jbang> XML element, and jbang: YAML key are deprecated in favor of cli(), <cli>, and cli: respectively. Configuration properties changed from citrus.camel.jbang.* to citrus.camel.cli.*.
• API changes — CitrusContext and TestContextFactory are now interfaces. Use CitrusContext.newInstance() or TestContextFactory.newInstance() for instantiation.

Provide feedback

We would love to hear from you! If you run into issues during migration or have ideas for improvements, please open an issue on GitHub or start a discussion.

Thank you!

The Citrus community has once again shown its strength in bringing this major update together. After 18+ years of development, Citrus continues to evolve with the Java ecosystem. We are proud to deliver a framework that stays current with the technologies you use every day. A special thank you to everyone who contributed code, reported issues, tested milestone releases and provided feedback!

Keep going and on to the next chapter!