Obviously we need something to test in the samples section. The todo-list is a very simple sample application that represents the system under test for the Citrus samples. This todo application provides an API for adding, removing and changing todo entries.

Objectives

The todo-list sample application should be both simple but yet capable to act as service in a fully qualified integration test scenario. The application provides a REST API for accessing the todo entries via Http.

Code repository

The Citrus samples are available at GitHub in several repositories. You can navigate to these repositories and use git to clone the code to your local machine. After that you can build and execute the samples on your local machine.

Build

The sample application uses Maven as build tool. So you can compile, package and test the sample with Maven.

mvn clean install

This executes the complete Maven build lifecycle and creates the sample artifacts that are used throughout the other samples. The build application represents the system under test.

Run

The application is a Spring Boot web application that you can deploy on any web container. Of course Spring Boot provides many other fantastic ways of starting the application.

One of these possibilities is the Spring Boot Maven Plugin. You can start the sample todo list application with this command.

mvn spring-boot:run

This starts the application in a Tomcat web container and automatically deploys the todo list app. Point your browser to

http://localhost:8080/todolist/

You will see the web UI of the todo list. Now add some new todo entries manually and you are ready to go.

Sample applications

The samples in Citrus represent small applications that are started as a system under test. Usually the sample application is a web application implemented in one of the runtimes Quarkus, Spring Boot and Apache Camel. All runtimes act in the same way. You can start the applications on your local machine as part of the test run.

No matter what sample application is used Citrus interacts with the applications as part of the integration tests in order to trigger certain business logic and to verify its outcome.

Embedding the system under test into the Maven build lifecycle so the application is run and stopped automatically is a good approach when running automated tests in a continuous build.

In some other cases you may want to start the sample application manually before the tests so the application is still alive when the tests and the Maven build is finished. You can start the sample applications in Maven as a standalone process that keeps running on your local machine. Depending on the runtime Quarkus or Spring Boot the command look like this:

mvn quarkus:dev
mvn spring-boot:run

This starts the application under test locally so you can open the web interface and point your browser to:

http://localhost:8080/todolist/

For Quarkus use port 8081. You will see the web UI of the application, in this case the todo list application.

Running the Citrus tests

Once the sample application is deployed and running you can execute the Citrus test cases. Open a separate command line terminal and navigate to the sample folder.

Execute all Citrus tests by calling

mvn verify

You can also pick a single test by calling

mvn verify -Ptest=TodoListIT

You should see Citrus performing several tests with lots of debugging output in both terminals (sample application server and Citrus test client). And of course green tests at the very end of the build.

Of course, you can also start the Citrus tests from your favorite Java IDE. Just start the Citrus test using the integration for unit tests such as TestNG or JUnit Jupiter in IntelliJ, Eclipse or VSCode.

The Maven build automatically runs all Citrus test cases in the project. During the build execution you will see Citrus performing the integration tests and printing log messages. When the tests are done the embedded sample application under test is automatically stopped and the Maven test results with successful and failed tests are presented to you.

Sometimes you may need to explicitly add a property embedded in order to enable the automatic provisioning of the application under test.

mvn verify -Dembedded=true

The embedded option automatically starts the application under test before the integration test phase takes place.