You have several options in customizing the Citrus project configuration. Citrus uses default settings that can be overwritten to some extend. As a framework Citrus internally works with the Spring IoC container. So Citrus will start a Spring application context and register several components as Spring beans. You can customize the behavior of these beans and you can add custom settings by setting system properties.

Citrus Spring XML application context

Citrus starts a Spring application context and adds some default Spring bean components. By default Citrus will load some internal Spring Java config classes defining those bean components. At some point you might add some custom beans to that basic application context. This is why Citrus will search for custom Spring application context files in your project. These are automatically loaded.

By default Citrus looks for custom XML Spring application context files in this location: classpath*:citrus-context.xml . So you can add a file named citrus-context.xml to your project classpath and Citrus will load all Spring beans automatically.

The location of this file can be customized by setting a System property citrus.spring.application.context . So you can customize the XML Spring application context file location. The System property is settable with Maven surefire and failsafe plugin for instance or via Java before the Citrus framework gets loaded.

See the following sample XML configuration which is a normal Spring bean XML configuration:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns=""

  <citrus:schema-repository id="schemaRepository" />


Now you can add some Spring beans and you can use the Citrus XML components such as schema-repository for adding custom beans and components to your Citrus project. Citrus provides several namespaces for custom Spring XML components. These are described in more detail in the respective chapters and sections in this reference guide.

Tip You can also use import statements in this Spring application context in order to load other configuration files. So you are free to modularize your configuration in several files that get loaded by Citrus.

Citrus Spring Java config

Using XML Spring application context configuration is the default behavior of Citrus. However some people might prefer pure Java code configuration. You can do that by adding a System property with a custom Spring Java config class as value.

System.setProperty("", MyCustomConfig.class.getName())

Citrus will load the Spring bean configurations in MyCustomConfig.class as Java config then. See the following example for custom Spring Java configuration:

import com.consol.citrus.TestCase;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

public class MyCustomConfig {

    @Bean(name = "customTestListener")
    public TestListener customTestListener() {
        return new PlusMinusTestReporter();

    private static class PlusMinusTestReporter extends AbstractTestListener implements TestReporter {

        /** Logger */
        private Logger log = LoggerFactory.getLogger(CustomBeanConfig.class);

        private StringBuilder testReport = new StringBuilder();

        public void onTestSuccess(TestCase test) {

        public void onTestFailure(TestCase test, Throwable cause) {

        public void generateTestResults() {

        public void clearTestResults() {
            testReport = new StringBuilder();

You can also mix XML and Java configuration so Citrus will load both configuration to the Spring bean application context on startup.

Citrus application properties

The Citrus framework references some basic System properties that can be overwritten. The properties are loaded from Java System and are also settable via property file. Just add a property file named to your project classpath. This property file contains customized settings such as:


Citrus loads these application properties at startup. All properties are also settable with Java System properties. The location of the is customizable with the System property citrus.application.config .

System.setProperty("citrus.application.config", "custom/path/to/")

At the moment you can use these properties for customization:

  • citrus.spring.application.context: File location for Spring XML configurations
  • Class name for Spring Java config
  • citrus.file.encoding: Default file encoding used in Citrus when reading and writing file content
  • citrus.default.message.type: Default message type for validating payloads
  • File name patterns used for XML test file package scan