Citrus Administration UI

The Citrus administration UI is there to help you manage configuration, modules and tests in your project. The user interface is able to give you a hand when it comes to managing Citrus messaging components and other configuration items such as (endpoints, validation Matcher, functions, schema repositories and so on).

The UI is browser based and is able to open and read your Citrus project. The administration pages provide access to the test cases so you can view and execute them. Of course you will also be able to review the test results. The administration web UI is not there to eliminate your favorite IDE (IntelliJ, Eclipse or whatever)! The UI is a helping instrument for getting in touch with Citrus and its concepts and works side by side with your local Java IDE as well as other text editors of your choice.

Also the UI is helpful when executing the Citrus integration tests in different stages (test, acceptance, explorative) of your release process. There is not always a full capable development environment available for executing integration tests. You can run the Citrus administrative UI as Docker container or Kubernetes pod in order to make the tests portable to your containerized test environment.

Now lets have a quick look at the feature set.

NOTE: This project is considered stable but still under construction!

The administration UI is stable not yet finished. Some features are still under construction. Some aspects are simply not covered yet.

Following from that we have to deal with some limitations and trade offs until the project emerges (hopefully with the help of the community, keeping our fingers crossed!). However the administration UI is usable and most features are considered to be stable.

Please consider following limitations that we have right now:

The admin UI is able to create completely new projects. The project sources are saved to your local file system in the admin UI working directory. The working directory is settable via system property or environment variable (see system configuration). By default this is the user home directory on your local system.

Of course you can open existing Citrus projects that are located on your local file system. When the administration UI is started without any further options you need to open a Citrus project first.

The project home selection form is displayed automatically when no project has been selected yet. You can preselect a project home when starting the administration UI by setting a system property or environment variable at startup:

When pre selecting a project home the project is opened automatically and the project dashboard is displayed.

The project home should point to a project root directory on your local file system that contains the Citrus project sources. You can specify the complete path manually or pick the home directory via the file browser.

Once you have specified the project home you are ready to hit the Open button. Citrus will read the project information and open the project dashboard. The administration UI is looking for several things in your project in order to gain information about the project. The files scanned are:

In case one of these mentioned files and directories is not present in your project sources the UI will not open the project due to invalid project sources. Sometimes projects use different file locations and project source file names for some reason. Fortunately you can customize thee folder path and file name settings on admin UI startup.

When you are using a different project layout than expected there are different approaches to customizing these project settings. First of all you can use system properties when starting the administration UI application:

As you can see we can customize the project file paths that are scanned by the UI. This enables us to open projects with different project file locations. Please refer to the complete list of available system properties in chapter system configuration.

The exact same parameters as seen in the system properties are also available when set as environment variables. The admin UI will automatically read those environment settings on startup. So you can adjust the project file locations using environment variables, too. Please see the complete list of available environment settings in chapter system configuration.

The administration UI is a web application that is started as standalone Spring Boot application or as a deployment in a Java web application server. The admin UI application uses some general settings and customization parameters that describe how the UI should behave. You can set those parameters as system properties or environment variables on server startup in order to tell the UI how to load projects for instance.

The dashboard gives you a quick overview of what your project looks like. Citrus reads information about your project such as name, package, description, test count, latest reports and so on.

The project dashboard is a good starting point to discover your project with all projects settings and tests.

Each Citrus project has properties and settings that influence the administration UI. These properties are project names, descriptions, versions and source folders. You can review and change these project related settings with an HTML form on the project settings page.

Some project settings are read only at the moment, e.g. we do not support renaming of projects yet. If you want to rename a project or change the project version you need to do this manually in the Maven POM configuration for now.

If you save the project settings the administration UI will save the changes to the project settings file citrus-project.json which is located in your project home directory. This file uses the Json syntax and looks like follows:

This project Json file is automatically created whenever the admin UI opens a project on your local file system. This file should be part of your coder versioning platform in order to save settings related to that project. When the project is reopened the UI will read project settings from that file in order to make sure that the project is loaded with the exact same settings as in the past. So you can also adjust this file manually in order to manipulate the way the UI is opening your project.

Endpoints are essential in a Citrus project. They define client and server components as well as producer and consumer for different message transports.

First of all the list of all available endpoints in the project is displayed. Each endpoint represents a message transport such as SOAP, JMS, REST, Mail, FTP and so on. You can add new endpoints using the New context menu on the right. You need to chose the endpoint type first. Then a HTML form is displayed holding the endpoint settings.

Click save to add the new endpoint. Citrus is working with Spring XML configuration files. This means that the new endpoint component is saved as XML Spring bean to the basic Spring application context file. Usually this is a file located in src/test/resources/citrus-context.xml in your project. After you have saved the new component you will see that a new entry has been added to this file.

You can also edit endpoint components in the administration UI. Just click an an existing endpoint component and you will see the HTML form with all the settings to this endpoint.

If you save the changes Citrus will again change the Spring bean component in the XML configuration file. You can manually review the changes made. All manual changes in the Spring application context will also affect the administration UI. Just hit the reload button in your browser to reload the configuration.

Citrus uses the Spring framework for dependency injection and component configuration. Usually a Citrus project comes with a set of Spring configuration files that define Citrus components and other project related settings. The admin UI scanns the project sources for typical Spring configuration files and displays all components (Spring beans) in that configuraiton.

You can review the beans with all properties and you can edit the Spring configuration files.

Test variables represent a common concept in Citrus. Variables define reusable identifiers and values that are referenced multiple times in a test case. The global variables are visible to all Citrus test cases and represent static constant values valid for the whole project. The global variables are editable via HTML forms on the configuration page:

The variables are saved to the Spring bean configuration as Citrus global-variables component:

Every time Citrus receives a message over some kind of messaging transport the validation mechanism will try to validate the syntax of the message payload with some schema rules. When using XML payloads these are XSD or WSDL files that define the syntax rules. In Citrus you can define schema repositories that hold one to many XML schema definition files. The Citrus XML message validators consult these schema repositories during message validation for matching schema definitions.

The schema repositories and schema definition files are managed on configuration page.

The configuration made here is saved to the Spring bean configuration files as Citrus schema components.

When using Xpath expressions in Citrus XML namespaces may be required to identify elements and attributes in XML payloads. The XML namespaces used in Xpath are identified with a prefix that evaluates to a target namespace value. You can define all namespaces and prefix values globally using the namespace context configuration.

The namespace context configuration is save as Citrus Spring bean component in the application context.

Data dictionaries help to define reusable expressions that manipulate message payloads before a message is sent or received. Usually these are Xpath or JsonPath expressions that overwrite values in message payloads throughout the whole project. Each message payload will consult the data dictionary for translation of values before being sent or received.

This way you can add centralized expressions that overwrite message payload elements in multiple test cases.

The data dictionary configuration is done on the configuration pages.

Functions apply on message payloads and test variables for dynamic value generation. The functions can be used in multiple places throughout the Citrus framework (e.g. payload, header, variables, etc.) Each function is provided with parameters and generates a String value as outcome. This way the user can place functions in order to generate more dynamic test data for instance. There are lots of predefined functions ready for usage in Citrus (e.g. citrus:randomUUID(), citrus:currentDate() and many more).

In addition to that you can create custom functions that implement very specific algorithms matching your very specific project needs. These functions and its implementations are configured here:

Similar to adding custom functions in Citrus you can also add custom validation matcher implementations. The matcher helpers do implement specific validation logic that applies to message validation when receiving messages in Citrus. There are lots of predefined matchers available in Citrus (e.g. @contains()@, @equalsIgnoreCase()@ and many more).

Custom validation matchers are configurable via HTML forms on the configuration pages.

Searching for test cases is very simple. Open the tests page and you will se a search form input field at the top right.

Citrus administration UI will search for tests in your project. These includes XML and Java DSL test cases. The search is a full text search on all test names available. So the result is always a matching list of tests.

You can open the test by selecting the test from the result list.

The test is opened and displayed in test detail panel.

Your project usually contains a lot of tests. All found tests are listed by their class and method. Also you can filter the displayed tests by the Java package. Each test can be opened in a editor for exploring further test details.

The administration UI is able to open your test cases. Both XML and Java DSL test cases are supported.

NOTE: Java DSL test cases might cause some problems when loading the test design view. this is because we do have to make the Java DSL code interpretation more stable.

You can open the tests using the Open context menu. All available test cases are grouped by their package.

Choose a test and open it in order to see the basic test case information such as name, author, status and description.

Next to to the test case info you can view the test source code.

If your test uses the XML DSL to describe the test actions you can also view the XML sources.

At the moment these information is read only. Stay tuned for some code editing features that might come in the future. Another representation of the test sources is the test designer view. The design view brings the test actions to a graphical representation.

Now a very powerful feature is to execute the test using the administration UI. Let’s go and read about test execution.

Test execution is a very powerful feature as it enables you to execute your tests within a browser environment almost everywhere. Just hit the Run button and Citrus will start a new background process that executes the test case immediately. At the moment we do only support Maven test execution. This means that a new Maven process is launched in background executing the test.

As you can see the test log output is forwarded to your browser. Also the test progress and result (success or failure) is tracked by the administration UI. In the messages table you are able to review all messages (inbound/outbound) that were part of the test run.

The message panel displays all inbound and outbound messages. Click on the message row to see the message content details. The mechanism for tracking inbound and outbound messages during a test run is done with either the admin connector library that you need to activate in your project. If for some reason you are not able to activate the connector library in your project the administration UI will try to read the messages from the normal Citrus logging output. This of course is only working if you have logging enabled in addition to using at least with logging level DEBUG.

If non of these approaches is working for you the admin UI will not display exchanged messages after the test run.

The next feature is quite experimental. In the test design view Citrus tries to give you a graphical representation of the test actions in your test. Each test action is displayed as a graphical node. If you enter the action with the mouse or if you click on a test action node some more details are displayed.

NOTE: The test design view is not complete for all test actions. Some actions may not be displayed or may have limited display.

The administration UI is able to read and parse basic TestNG and JUnit reports. Usually these reports are written after each test run to the build output directory of your project. The admin UI will automatically find those reports and display the results to you.

When a test case is failing for some reason exception and failure information will be provided.

The administration UI is available as Docker image (consol/citrus-admin:latest). You can pull the image and link it to your local Citrus project:

The command above loads the Docker image and runs a new Citrus web UI container. The container is provided with a volume mount that makes the current directory accessible from within the container. This current directory is then used as project home so the admin UI will automatically open the Citrus project from that directory. Once the container is running you can point your local browser to link:[http://localhost:8080] in order to access the web UI.

The CITRUS_ADMIN_PROJECT_HOME environment setting is optional and is used to automatically open a project on container startup. You can leave out this setting in order to select a project folder in your mounted working directory when starting the web UI.

In case you do not have a Citrus project ready yet, the admin UI can also create a new project for you. It is possible to run a Maven archetype on container startup that creates a complete new project for you. You can set the Maven archetype coordinates (groupId, artifactId, version) as environment variables when running the container.

The UI will load the Maven archetype and create the project sources when the container is started. The new project gets its Maven coordinates from another environment setting:

Another way to load a new project on container startup is to specify a git repository URL. The Citrus admin Docker container will then load the project sources from that git repository on startup:

The command above will load the project sources from git with URL https://github.com/account/citrus-project.git and open that project afterwards. The git repository of course should hold the Citrus project sources. In case the Citrus project is located in a sub module in that git repository you can load that sub module by specifying additional environment properties:

With these options we are able to start the Docker image as container with special customizations via environment settings. Please refer to the complete list of supported environment variables in chapter system configuration.

The citrus-admin Docker image works great with the Fabric8 Docker Maven plugin (https://dmp.fabric8.io/). You can add the plugin configuration as follows in your Maven POM:

Now you can build the images locally with Maven calling

After that you should have a set of new images on your Docker host. You can run these images as Docker container.

When using Docker images it is good practice to provide environment variables that are able to overwrite general properties in the application in order to adjust the container behavior. The Docker image is able to set several environment properties. For a detailed list of these variables and their meaning in the admin UI web application please refer to chapter setup environment variables.