Citrus

See the following sample showing how to write a Citrus test on top of TestNG:

If you are familiar with TestNG you will see that the Java class is a normal TestNG test class using the usual @Test annotation. For convenience reasons you can extend a basic Citrus TestNG base class TestNGCitrusSupport which enables the Citrus test execution as well as the Java DSL features for us.

In addition, the test methods use the @CitrusTest annotation which allows setting properties such as test names and packages.

The Citrus test logic goes directly as the method body with using the Citrus Java domain specific language features. As you can see the Java DSL is able to follow BDD (Behavior Drive Design) principles with Given-When-Then syntax. As an alternative to that you can just use run() for all test actions.

The great news is that you can still use the awesome TestNG features in with the Citrus test class (e.g. parallel test execution, test groups, setup and tear down operations and so on). Just to give an example we can simply add a test group to our test like this:

For more information on TestNG please visit the official TestNG website, where you find a complete reference documentation. The following sections deal with a subset of these TestNG features in particular.

TestNG as a framework comes with lots of great features such as data providers. Data providers execute a test case several times with different test data. Each test execution works with a specific parameter value. You can use data provider parameter values as test variables in Citrus. See the next listing on how to use TestNG data providers in Citrus:

Above test case method is annotated with TestNG data provider called messageDataProvider . In the same class you can write the data provider that returns a list of parameter values. TestNG will execute the test case several times according to the provided parameter list. Each execution is shipped with the respective parameter value.

According to the @CitrusParameter annotation the test will have test variables called message and delay.

Integration tests tend to be more time-consuming compared to pure unit tests when it comes to execute tests. This is because integration tests often need to initialize test infrastructure (e.g. test servers, database connections). Running tests in parallel can reduce the overall test suite time a lot.

When running tests in parallel you need to make sure each test operates on its own set of resources. Tests must not share components such as the Citrus Java DSL test action runner or the test context.

You should be using the resource injection to make sure each test operates on its own resources.

First of all the method parameters must be annotated with @Optional because the values are not injected by TestNG itself but by the Citrus base test class. Finally, the parameter requires the @CitrusResource annotation in order to mark the parameter for Citrus resource injection.

Now each method uses its own resource instances which makes sure that parallel test execution can take place without having the risk of side effects on other tests running at the same time. Of course, you also need to make sure that the message exchange in your tests is ready to be performed in parallel (e.g. use message selectors).

You can use the Citrus JUnit5 extension on your test as follows:

The class above is using the JUnit5 @Test annotation as a normal unit test would do. The @CitrusSupport annotation marks the test to use the Citrus JUnit5 extension. This enables us to use the @CitrusTest annotation on the test and adds support for the parameter injection for the TestActionRunner.

The Citrus Java DSL runner is the entrance to the Java fluent API provided by Citrus. The sample above uses the Gherkin test runner variation for leveraging the BDD (Behavior Driven Development) style Given-When-Then syntax.

You can also inject the current TestContext in order to get access to the current test variables used by Citrus.

In addition to injecting test resources you can also inject endpoints via @CitrusEndpoint annotated field injection in your test class. This enables you to inject endpoint components that are defined in the Citrus context configuration.

Spring is a famous dependency injection framework that also provides support for JUnit5. Citrus is able to load its components as Spring beans in an application context. The Citrus JUnit5 extension works great with the Spring extension.

The Spring extension loads the application context and Citrus adds all components to the Spring bean configuration.

The test now uses the @CitrusSpringSupport annotation which combines the @ExtendWith(CitrusSpringExtension.class) and @ExtendWith(SpringExtension.class) annotation. This way the test combines the Spring application context management with the Citrus Java DSL functionality.

You can load Spring beans with @Autowired into your test. Also, you can use the @CitrusResource annotations to inject the test action runner fluent Java API.

You can run your JUnit5 test cases in order in a distributed manner, facilitating test sharding. The following snipped showcases you how to get started within a Spring/XML test case environment. Note that sharding is available with all kind of Stream-sources.

All the available configuration options are documented withing the chapter Sharding Test Cases

See the following sample test class that uses JUnit4.

The simple test class above uses the normal @Test annotation and extends the base class JUnit4CitrusSupport. This is the most convenient way to access the Citrus Java DSL capabilities. As an alternative you may switch to using the CitrusJUnit4Runner in your test class.

The fine thing here is that we are still able to use all JUnit features such as before/after hooks or ignoring tests.

After the test run the result is reported exactly like a usual JUnit unit test would do. This also means that you can execute this Citrus JUnit class like every other JUnit test, especially out of any Java IDE, with Maven, with Gradle and so on.

Integration tests tend to be more time-consuming compared to pure unit tests when it comes to execute tests. This is because integration tests often need to initialize test infrastructure (e.g. test servers, database connections). Running tests in parallel can reduce the overall test suite time a lot.

When running tests in parallel you need to make sure each test operates on its own set of resources. Tests must not share components such as the Citrus Java DSL test action runner or the test context.

You should be using the resource injection to make sure each test operates on its own resources.

The method parameters require the @CitrusResource annotations in order to mark the parameter for Citrus resource injection.

Now each method uses its own resource instances which makes sure that parallel test execution can take place without having the risk of side effects on other tests running at the same time. Of course, you also need to make sure that the message exchange in your tests is ready to be performed in parallel (e.g. use message selectors).

The test is able to configure Message endpoints to connect to different messaging transports as part of the test.

Creating new message endpoints is very easy. Just use the proper endpoint builder and optionally bind the new endpoint to the Citrus bean registry via @BindToRegistry annotation. You may then use the message endpoint in all send and receive test actions in order to exchange messages.

You may move the endpoint configuration into a separate class and load the endpoints with the configuration class as follows:

The endpoint configuration class uses @BindToRegistry members or methods to add beans to the Citrus registry. The configuration class may be referenced by many tests then using the @CitrusConfiguration annotation.

Citrus loads the configuration class and injects the KafkaEndpoint instance to the test with @CitrusResource annotation.

Citrus supports many test languages besides writing tests in pure Java. Users can load tests written in XML, YAML, Groovy and many more via dynamic tests.

The example above loads YAML test case definitions and runs those as dynamic tests with JUnit Jupiter. The package scan loads all files in the given folder and runs the tests via Citrus. All YAML tests are able to reference the message endpoints configured in the configuration class EndpointConfig.class.

A sample YAML test may look like this:

The @QuarkusTest annotation will automatically start the application under test. Citrus provides the ability to programmatically set application properties before the Quarkus application is started. This is important when you need to overwrite configuration based on test message endpoints configured in the test.

The next example shows a Citrus enabled Quarkus test that supplies a set of application properties to configure the application under test.

The DemoAppConfiguration class implements the Supplier interface and set a config property. This property will be set on the application under test.

The application properties supplier is able to set Quarkus properties as well as application domain properties. The example above sets greeting.message property which can be referenced in the Quarkus application:

Citrus integrates with Testcontainers to easily start/stop Testcontainers instances as part of the test. You can leverage the Citrus Testcontainers features within a Quarkus test very easily. Citrus implements Quarkus test resources for each of the supported containers (AWS LocalStack, Kafka, Redpanda, …​).

The following example starts an AWS LocalStack Testcontainers instance and uses the S3 service on that container to upload a file to the S3 bucket. The Quarkus application under test should handle this S3 file then.

A few things happened in this example and let’s explain those features one after another. First thing to notice is the @LocalStackContainerSupport annotation that makes Citrus run the AWS LocalStack Testcontainers instance. Also, the annotation provides the enabled services on that container (services = LocalStackContainer.Service.S3). This starts the Testcontainers instance as part of the Quarkus test.

The test also implements the ContainerLifecycleListener interface. This enables the test to handle the container instance after it has been started. This is a good place to create an S3 client and the bucket for the test.

Also, the started listener may return some application properties that get set for the Quarkus application under test. This is the opportunity to set the Testcontainers connection settings for the Quarkus application.

Obviously the Quarkus application uses some property based configuration with the my.app.* properties. The test is able to reference the Testcontainers exposed settings as values for these properties (e.g. my.app.aws-s3-source.accessKey=container.getAccessKey()).

With this configuration in place the test is able to upload and S3 file to the test bucket on the Testcontainers instance with the uploadS3File() method. This should trigger the Quarkus application under test to handle the new file accordingly. We can add some verification and assertion steps to verify that the Quarkus application has handled the S3 file.

This is how Citrus is able to start Testcontainers instances as part of a Quarkus test. The application properties supplier as well as the container lifecycle listener interfaces allow us to connect the Quarkus application with the Testcontainers instance. The test is able to use the services on the Testcontainers instance to trigger some test data that is consumed by the application under test.

Please also have a look into the other provided Testcontainers annotations in Citrus:

All of these annotations allow you to start Testcontainers instances as part of your Quarkus test and provides the opportunity to participate in the container lifecycle to access managed ports and connectivity settings for instance.

Cucumber is able to run tests with JUnit. The basic test case is an empty test which uses the respective JUnit runner implementation from cucumber.

The test case above uses the Cucumber JUnit test runner. In addition to that we give some options to the Cucumber execution. In case you want to have the usual Citrus test results reported you can add the special Citrus reporter implementation org.citrusframework.cucumber.CitrusReporter. This class is responsible for printing the Citrus test summary. This reporter extends the default Cucumber reporter so the default Cucumber report summary is also printed to the console.

That completes the JUnit class configuration. Now we are able to add feature stories and step definitions to the package of our test MyFeatureIT . Cucumber and Citrus will automatically pick up step definitions and glue code in that test package. So let’s write a feature story echo.feature right next to the MyFeatureIT test class.

As you can see this story defines two scenarios with the Gherkin Given-When-Then syntax. Now we need to add step definitions that glue the story description to Citrus test actions. Let’s do this in a new class EchoSteps .

The step definition class is a normal POJO that uses some annotations such as @CitrusResource annotated TestCaseRunner. The Citrus backend injects the test runner instance at runtime.

The step definition contains normal @Given, @When or @Then annotated methods that match the scenario descriptions in our feature file. Cucumber will automatically find matching methods and execute them. The methods add test actions to the test runner as we used to do in normal Java DSL tests.

That is a first combination of Citrus and Cucumber BDD. The feature file gets translated into step implementations that use Citrus test action runner Java API to run integration tests with behavior driven development.

The previous section handled glue code in Java in form of step definitions accessing the Java test runner fluent API. This chapter deals with the same concept with just XML configuration.

Citrus provides a separate configuration namespace and schema definition for Cucumber related step definitions. Include this namespace into your Spring configuration in order to use the Citrus Cucumber configuration elements.

The JUnit Cucumber feature class itself does not change. We still use the Cucumber JUnit runner implementation with some options specific to Citrus:

The feature file with its Gherkin scenarios does also not change:

In the feature package my.company.features we add a new XML file EchoSteps.xml that holds the new XML step definitions:

The above step definition uses pure XML actions. Citrus will automatically read the step definition and add those to the Cucumber runtime. Following from that the step definitions are executed when matching a statement in the feature story.

The XML step files follow a naming convention. Citrus will look for all files located in the feature package with name pattern **/**.Steps.xml and load those definitions when Cucumber starts up.

The XML steps are able to receive parameters from the Gherkin regexp matcher. The parameters are passed to the step as test variable. The parameter names get declared in the optional attribute parameter-names. In the step definitions you can use the parameter names as test variables.

We have to do this because otherwise the quotation characters will interfere with the XML syntax in the attribute.

This completes the description of how to add XML step definitions to the cucumber BDD tests.

Cucumber provides support for Spring dependency injection in step definition classes. The Cucumber Spring capabilities are included in a separate module. So first of all we have to add this dependency to our project:

The Citrus Cucumber extension has to handle things different when Cucumber Spring support is enabled. Therefore we use another object factory implementation that also support Cucumber Spring features. Change the object factory property in cucumber.properties to the following:

Now we are ready to add @Autowired Spring bean dependency injection to step definition classes:

As you can see we used Spring autowiring mechanism for the echoEndpoint field in the step definition. Also be sure to define the @ContextConfiguration annotation on the step definition. The Cucumber Spring support loads the Spring application context and takes care of dependency injection. We use the Citrus CitrusSpringConfig Java configuration because this is the main entrance for Citrus test cases. You can add custom beans and further Spring related configuration to this Spring application context. If you want to add more beans for autowiring do so in the Citrus Spring configuration. Usually this is the default citrus-context.xml which is automatically loaded.

Of course, you can also use a custom Java Spring configuration class here. Please be sure to always import the Citrus Spring Java configuration classes, too.

As usual, we are able to use @CitrusResource annotated TestCaseRunner fields for building the Citrus integration test logic. With this extension you can use the full Spring testing power in your tests in particular dependency injection and also transaction management for data persistence tests.

YAKS is a side project of Citrus and provides some predefined steps for typical integration test scenarios that you can use out-of-the-box.

You can basically define send/receive operations and many other predefined steps to handle Citrus test actions. As these steps are predefined in YAKS you just need to use them in your feature stories. The step definitions with glue to test actions is handled automatically in YAKS.

If you want to enable predefined steps support in your test you need to include the YAKS module as a Maven dependency.

After that you need to include the glue code package in your test class like this:

Instead of writing the glue code on our own in step definition classes we include the glue package org.citrusframework.yaks.standard as extra glue. This automatically loads all YAKS step definitions in this module. Once you have done this you can use predefined steps without having to write any glue code in Java.

The YAKS framework provides the following modules with predefined steps:

Once again it should be said that the step definitions included in this modules can be used out-of-the-box. You can start to write feature stories in Gherkin syntax that trigger the predefined steps.

For a more convenient way to use the Citrus JBang scripts you can install Citrus as a JBang app.

Now you can just call:

You can directly run test sources with Citrus JBang. This includes test sources written in Java, XML, YAML, Cucumber.

Citrus JBang comes with a set of default dependencies that makes the scripts run as tests.

The default modules that you can use in Citrus JBang are:

This enables you to run Java, YAML, XML, Groovy tests out of the box. In case your tests uses an additional feature from the Citrus project you may need to add the module so JBang can load the dependency at startup.

The easiest way to do this is to create a jbang.properties file that defines the additional dependencies:

The file above adds the modules citrus-camel, citrus-testcontainers and citrus-kafka so you can use them in your JBang Citrus test source.

The jbang.properties file may be located right next to the test source file or in your user home directory for global settings.

You can run tests from your current clipboard. Just use the file name clipboard.xxx where the file extension defines the type of the test source (.java, .yaml, .xml, .groovy, .feature).

The ls command lists all running Citrus tests. These tests may be started

First of all, you need to wrap your test case loading with the org.citrusframework.sharding.Shard#createShard(Stream<T> items) method. Have a look at the previous runtime chapters to get to know how to do this with the test framework of your choice.

Once you’re done doing so, the sharding can be configured using environment variables or system properties. The following two key configuration parameters are required for sharded test loading:

The following table summarizes the full configuration options:

When writing test cases in Java, additional constructors exist, such that the total number of shards, as well as the current shard number can be programmatically configured.

The test action runner is the entry to the fluent Citrus Java API. You can configure test actions with a builder pattern style API and immediately runs the test actions.

See the following example to see the Java domain specific language in action.

The test action runner executes each test action immediately as you use the provided run() method. All actions provided in Citrus represent a certain functionality (e.g. send/receive messages, delay the test, access a database). Citrus ships with a wide range of test actions, but you are also able to write your own test actions and execute them during a test.

By default, all actions run sequentially in the same order as they are defined in the test case. In case one single action fails the whole test case is failing. Of course, you can leverage parallel action execution with the usage of test containers.

The test action runner is also available as Gherkin style runner with given(), when(), then() methods. The Gherkin test action runner follows the Behavior Driven Development concepts of structuring the test into the three parts: Given a certain context, when an event occurs, then an outcome should be verified.

The user is able to provide some additional information about the test case. The meta-info section at the very beginning of the test case holds information like author, status or creation date.

The status allows the following values:

This information gives the reader first impression about the test and is also used to generate test documentation. By default, Citrus is able to generate test reports in HTML and Excel in order to list all tests with their metadata information and description.

The test description should give a short introduction to the intended use case scenario that will be tested. The user should get a short summary of what the test case is trying to verify.

Java developers might be familiar with the concept of try-catch-finally blocks. The finally section contains a list of test actions that will be executed guaranteed at the very end of the test case even if errors did occur during the execution before.

This is the right place to tidy up things that were previously created by the test like cleaning up the database for instance.

As an example imagine that you have prepared some data inside the database at the beginning of the test and you need to make sure the data is cleaned up at the end of the test case.

In the example the first action creates an entry in the database using an INSERT statement. To be sure that the entry in the database is deleted after the test, the finally section contains the respective DELETE statement that is always executed regardless the test case state (successful or failed).

A finally block placed at the very end of the test will not take action unless put in a traditional Java try-finally-block:

Using the traditional Java try-finally feels more natural no doubt. Please notice that the Citrus report and logging will not account the traditional finally block actions then. Good news is whatever layout you choose the outcome is always the same.

The finally block is executed safely even in case some previous test action raises an error for some reason.

The concept of test behaviors is a good way to reuse test action blocks in the Java DSL. Test behaviors combine action sequences to a logical unit. The behavior defines a set of test actions that can be applied multiple times to different test cases.

The behavior is a separate Java DSL class with a single apply method that configures the test actions. Test behaviors follow this basic interface:

The behavior is provided with the test action runner and all actions in the behavior should run on that runner. Every time the behavior is applied to a test the actions get executed accordingly.

The listing above shows two test behaviors that add very specific test actions and test variables to the test case. As you can see the test behavior is able to use the same Java DSL action methods and defines test variables and actions as a normal test case would do. You can apply the behaviors multiple times in different tests:

The behavior is applied to the test case by calling the apply() method. As a result the behavior is executed adding its logic at this point of the test execution. The same behavior can now be called in multiple test cases so we have a reusable set of test actions.

A behavior may use different variable names than the test and vice versa. No doubt the behavior will fail as soon as special variables with respective values are not present. Unknown variables cause the behavior and the whole test to fail with errors.

So a good approach would be to harmonize variable usage across behaviors and test cases, so that templates and test cases do use the same variable naming. The behavior automatically knows all variables in the test case and all test variables created inside the behavior are visible to the test case after applying.

In general, you are able to mix Citrus Java DSL actions with custom Java code as you like.

The test above uses a mix of Citrus test actions and custom service calls. The test logic will execute as expected. It is recommended though to wrap custom code in a test action in order to have a consistent test reporting and failure management in Citrus.

The sample above wraps the call to the custom service myService in an abstract test action represented as Java lambda expression. This way the service call becomes part of the Citrus test execution and failures are reported properly. Also you have access to the current test context which holds the list of test variables as well as many other Citrus related test objects (e.g. message store).

This is why you should wrap custom code in a test action and run that code via the test action runner methods. You can also put your custom code in a test action implementation and reference the logic from multiple tests.

The Citrus context is a place where objects can register themselves in order to enable dependency injection and instance sharing in multiple tests. Once you register the object in the context others can resolve the reference with its given name.

In a simple example the context can register a new endpoint that is injected in several tests.

You can access the Citrus context within the provided before/after methods on the test.

With the CitrusContext you can bind objects to the registry. Each binding receives a name so others can resolve the instance reference for injection.

The @CitrusEndpoint annotation injects the endpoint resolving the instance with the given name foo. Test methods can use this endpoint in the following send and receive actions.

Resource injection is a convenient mechanism to access Citrus internal objects such as TestRunner or TestContext instances. The following sections deal with resource injection of different objects.

The XML test is able to create endpoints and other configuration entities as part of the test. The test leverages the Groovy programming language that provides a comfortable way to define beans in the Citrus registry. You can set any of the supported properties on the configuration components.

The test above creates a new direct endpoint called hello that uses an im-memory queue say-hello. The send action is able to reference the endpoint by its name to send a message body to the queue.

Templates group action sequences to a logical unit. You can think of templates as reusable components that are used in several tests. The maintenance is much more efficient because you need to apply changes only on the templates and all referenced use cases are updated automatically.

The template gets identified by a unique name. Inside a test case we apply the template referencing this unique name. Have a look at a first example:

The code example above describes a template called echo. Templates hold a sequence of test actions or calls other templates themselves. The template may define a set of parameters that represent customizable user input when applying the template.

The template is available for multiple tests that may apply the template as part of their test action sequence.

The example references the echo template and call it as part of the test with <apply-template/>. You can customize the template parameter to overwrite the default variable text with a custom value.

The example above assumes that you have added the template to the Citrus bean registry with the name echo. If this is not the case you may also reference the file resource path when applying the template:

The YAML test is able to create endpoints and other configuration entities as part of the test. The test leverages the Groovy programming language that provides a comfortable way to define beans in the Citrus registry. You can set any of the supported properties on the configuration components.

The test above creates a new direct endpoint called hello that uses an im-memory queue say-hello. The send action is able to reference the endpoint by its name to send a message body to the queue.

Templates group action sequences to a logical unit. You can think of templates as reusable components that are used in several tests. The maintenance is much more efficient because you need to apply changes only on the templates and all referenced use cases are updated automatically.

The template gets identified by a unique name. Inside a test case we apply the template referencing this unique name. Have a look at a first example:

The code example above describes a template called echo. Templates hold a sequence of test actions or calls other templates themselves. The template may define a set of parameters that represent customizable user input when applying the template.

The template is available for multiple tests that may apply the template as part of their test action sequence.

The example references the echo template and call it as part of the test with <apply-template/>. You can customize the template parameter to overwrite the default variable text with a custom value.

The example above assumes that you have added the template to the Citrus bean registry with the name echo. If this is not the case you may also reference the file resource path when applying the template:

A Groovy test is able to create endpoints and other configuration entities as part of the test. The Groovy language provides a comfortable way to define beans in the Citrus registry. You can set any of the supported properties on the configuration components.

The test above creates a new direct endpoint called hello that uses an im-memory queue say-hello. The send action is able to reference the endpoint by its name to send a message body to the queue.

The Gherkin Given-When-Then syntax helps you to categorize and structure the individual steps in your test. The Groovy test language in Citrus can use this concept, too.

The Groovy language is good choice when it comes to creating domain specific languages. You can provide syntactical sugar to make it as comfortable as possible to use your domain.

As an example you can use message builders to create message body payloads in XML or Json format.

The example above deals with Json message payloads and leverages the message builders to create a Json body like this:

The same approach works fine with XML payloads:

The test actions use the XML message builder and create XML body payloads such as:

Templates group action sequences to a logical unit. You can think of templates as reusable components that are used in several tests. The maintenance is much more efficient because you need to apply changes only on the templates and all referenced use cases are updated automatically.

The template gets identified by a unique name. Inside a test case we apply the template referencing this unique name. Have a look at a first example:

The code example above describes a template called echo. Templates hold a sequence of test actions or calls other templates themselves. The template may define a set of parameters that represent customizable user input when applying the template.

The template is available for multiple tests that may apply the template as part of their test action sequence.

The example references the echo template and call it as part of the test with applyTemplate(). You can customize the template parameter to overwrite the default variable text with a custom value.

The example above assumes that you have added the template to the Citrus bean registry with the name echo. If this is not the case you may also reference the file resource path when applying the template:

Despite the fact that the complete test logic is defined in XML we need a Java class to actually load the XML file and run the test as part of JUnit, Cucumber or TestNG depending on the test engine you choose. The Java class acts as a wrapper to load the XML file and execute the test.

The Spring XML test case definition in Citrus uses two files that are connected via naming conventions. In a Maven project these two files would be:

The files above represent a test called MyFirstCitrus_IT. The .java file defines the runtime that should be used to execute the test. This Java file does not have any test logic and is not likely to be changed. In fact, you can generate the Java file from Citrus (e.g. Maven plugin).

The command above creates the two test files (.java and .xml) using an interactive mode. The user provides the test case information such as test name, package, runtime and so on.

The purpose of the generated Java class is to load the XML file as a Spring bean test and execute the test case.

The default naming convention requires the XML file with the test name in the same package as the generated Java class. This makes sure that the Java class is able to find the XML file when loading and running the test.

The user is able to provide some additional information about the test case. The meta-info section at the very beginning of the test case holds information like author, status or creation date.

The status allows the following values:

This information gives the reader first impression about the test and is also used to generate test documentation. By default, Citrus is able to generate test reports in HTML and Excel in order to list all tests with their metadata information and description.

The test description should give a short introduction to the intended use case scenario that will be tested. The user should get a short summary of what the test case is trying to verify. You can use free text in your test description no limit to the number of characters. Please be aware of the XML validation rules of well-formed XML (e.g. special character escaping). The usage of CDATA sections for large descriptions may be a good idea, too.

Java developers might be familiar with the concept of try-catch-finally blocks. The finally section contains a list of test actions that will be executed guaranteed at the very end of the test case even if errors did occur during the execution before.

This is the right place to tidy up things that were previously created by the test like cleaning up the database for instance.

As an example imagine that you have prepared some data inside the database at the beginning of the test and you need to make sure the data is cleaned up at the end of the test case.

In the example the first action creates an entry in the database using an INSERT statement. To be sure that the entry in the database is deleted after the test, the finally section contains the respective DELETE statement that is always executed regardless the test case state (successful or failed).

When using the XML test definition you must obey the XML rules for variable values. First of all you need to escape XML reserved characters such as <, & or " with <, & or ". Other values such as XML snippets would also interfere with the XML well-formed paradigm. You can use CDATA sections within the variable value element as a solution.

That is how you can use structured variable values in the XML DSL.

You can also use a script to create variable values. This is extremely handy when you have very complex variable values. Just code a small Groovy script for instance in order to define the variable value. A small sample should give you the idea how that works:

Just use the script code right inside the variable value definition. The value of the variable is the result of the last operation performed within the script. For longer script code the use of <![CDATA[ ]]> sections is recommended.

Citrus uses the JavaScript engine mechanism to evaluate the script code. By default, Groovy is supported as a script engine implementation. You can add additional engine implementations to your project and support other script types, too.

Templates group action sequences to a logical unit. You can think of templates as reusable components that are used in several XML tests. The maintenance is much more efficient because you need to apply changes only on the templates and all referenced use cases are updated automatically.

The template always has a unique name. Inside a test case we call the template by this unique name. Have a look at a first example:

The code example above describes two template definitions. Templates hold a sequence of test actions or call other templates themselves as seen in the example above.

There is an open question when dealing with templates that are defined somewhere else outside the test case. How to handle variables? A templates may use different variable names then the test and vice versa. No doubt the template will fail as soon as special variables with respective values are not present. Unknown variables cause the template and the whole test to fail with errors.

So a first approach would be to harmonize variable usage across templates and test cases, so that templates and test cases do use the same variable naming. But this approach might lead to high calibration effort. Therefore, templates support parameters to solve this problem. When a template is called the calling actor is able to set some parameters. Let us discuss an example for this issue.

The template "doDateConversion" in the next sample uses the variable ${date}. The calling test case can set this variable as a parameter without actually declaring the variable in the test itself:

The variable sampleDate is already present in the test case and gets translated into the date parameter. Following from that the template works fine although test and template do work on different variable namings.

With template parameters you are able to solve the calibration effort when working with templates and variables. It is always a good idea to check the used variables/parameters inside a template when calling it. There might be a variable that is not declared yet inside your test. So you need to define this value as a parameter.

Template parameters may contain more complex values like XML fragments. The call-template action offers following CDATA variation for defining complex parameter values:

In the listing above a template print is called several times in a parallel container. The parameter values will be handled in a global context, so it is quite likely to happen that the template instances influence each other during execution. We might get such print messages:

Index parameters do not fit and the message 'Hello Asia' is completely gone. This is because templates overwrite parameters to each other as they are executed in parallel at the same time. To avoid this behavior we need to tell the template that it should handle parameters as well as variables in a local context. This will enforce that each template instance is working on a dedicated local context. See the global-context attribute that is set to false in this example:

After that template instances won’t influence each other anymore. But notice that variable changes inside the template then do not affect the test case neither.

When an incoming message is passing the message validation the user can extract some values of that received message to new test variables for later use in the test.

With this example we have extracted three new test variables via JSONPath expression evaluation. The three test variables will be available to all upcoming test actions. The variable values are:

As you can see we can also extract complex JSONObject items or JSONArray items. The test variable value is a String representation of the complex object.

Add this code to your message receiving action.

As you can see Citrus is able to extract both header and message body content into test variables. The extraction will automatically create a new variable in case it does not exist. The time the variable was created all following test actions can access the test variables as usual. So you can reference the variable values in response messages or other test steps ahead.

First thing we want to do with JsonPath is to manipulate a message content before it is actually processed. This is very useful when working with message file resources that are reused across multiple test cases. Each test case can manipulate the message content individually with JsonPath before processing the message content.

Let’s have a look at this simple sample Json message body: