Standalone simulator for different messaging transports such as Http REST, SOAP WebService, JMS, RMI, mail messaging and more
Clone or download

Citrus Simulator Logo

This is a standalone simulator for different messaging transports such as Http REST, SOAP WebService, JMS, RMI, mail messaging and more.

The simulator provides server APIs for clients and responds with predefined messages according to defined scenarios. The simulator response logic is very powerful and enables us to simulate any kind of server interface.

The simulator uses Spring Boot in combination with the test framework Citrus. You can code simulator scenarios in Java or XML. Each scenario execution on the simulator is stored to an internal database and can be reviewed via web UI in the browser.

Read the simulator user manual for more information.


The Citrus simulator is a normal Spring Boot web application that is started on your local machine. Once started the simulator is capable of handling incoming requests of different message types and messaging transports. Each incoming request executes a predefined scenario that will create a proper response message for the client. Which scenario to execute is identified based on a mapping key that is extracted from the incoming request.

There are multiple ways to identify the simulator scenario from incoming request messages:

  • Message-Type: Each request message type (XML root QName) results in a separate simulator scenario
  • Content based Xpath: Evaluates Xpath expressions on the request payload and uses the expression result as scenario name
  • Content based JsonPath: Evaluates JsonPath expressions on the request payload and uses the expression result as scenario name
  • Header value: Evaluates header name on request and uses header value as scenario name
  • SOAP action: Evaluates SOAP action header on request and uses the value as scenario name
  • REST request mappings: Identifies the scenario based on Http method and resource path on server
  • Request mapping annotations: Uses Spring @RequestMapping annotations on scenarios in order to map incoming requests based on request method and/or request path values

The scenario is able to use the full Citrus test framework power in order to create complex execution logic. The response messages can hold dynamic values and the simulator is able to handle intermediate messages as well as call other APIs within a scenario to perform complex response generating logic. The scenarios are coded in Java classes that use the Citrus test DSL for defining the simulator scenario steps.

You can use any build system you like when building the simulator application. Here we show how to setup everything using Gradle and Maven.

Gradle Quickstart

You can use a usual Spring Boot build script to compile and package the application with Gradle:

buildscript {
    repositories {
    dependencies {

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'org.springframework.boot'

jar {
    group = "com.consol.citrus.simulator"
    baseName = 'citrus-simulator-sample'
    version =  '1.1.0-SNAPSHOT'

repositories {

sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {

Maven Quickstart

When choosing Maven as build tool the pom file is a normal Spring Boot project with all dependencies and plugins.

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





    <!-- Citrus Simulator -->






Simulator logic

As the simulator is a normal Spring boot application we just add a usual main class.

package com.consol.citrus.simulator;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

public class Simulator {

    public static void main(String[] args) {, args);

In addition to that we should define one to many simulator scenarios that execute when requests are received.

package com.consol.citrus.simulator;

import com.consol.citrus.http.message.HttpMessage;
import com.consol.citrus.simulator.scenario.*;
import org.springframework.http.HttpStatus;

public class DefaultScenario extends AbstractSimulatorScenario {

    public void run(ScenarioDesigner designer) {
        designer.echo("Default scenario executed!");

                .message(new HttpMessage("Welcome to the Citrus simulator")

Run as web application

Now you can build and run the simulator application.


./gradlew build bootRun


mvn install spring-boot:run

You will see the application starting up. Usually you will see some console log output. The web server should start within seconds. Once the application is up and running you can open your browser and point to http://localhost:8080. You will see the very basic simulator user interface. For a more detailed user interface please follow the chapter user-interface.

The REST default scenario that we have added is accessible using http://localhost:8080/services/rest/. You will see the default output Welcome to the Citrus simulator coming from default scenario execution.

That's it you are ready to use the Citrus simulator now.

User interface

The simulator application is started as a Spring boot web application. If you open your browser and point to the running simulator instance at http://localhost:8080 you will see a user interface that displays information about the simulator.


The simulator dashboard gives you a quick overview of the numbers and facts on your simulator project. Users can then access an administrative web user interface in order to review the simulator status and list all executed scenarios and their outcome. The simulator Angular2 user interface comes as dependency that is added to the simulator project. In Maven we simply add the following dependency:


To understand the full capabilities of the UI please read the chapter user-interface in reference manual.


  • Implements any of the interfaces: SOAP (WSDL), REST, JMS, File
  • Powerful response simulation (dynamic identifiers, fault simulation, value extraction, etc.)
  • Easy message definition (Citrus Java DSL)
  • XSD schema validation of incoming requests
  • JSON message format handling
  • Powerful header support (SOAP Action, SOAP header fragments, Http headers)
  • Auto generate simulator from Swagger Open API specifications
  • Auto generate simulator from SOAP WSDL files


Documentation can only provide theoretical insights of what the application is capable to provide. Good sample projects help both beginners and experts to reach complete understanding of how the simulator works in different environments.

Following from that we try to provide sample project that demonstrate the simulator usage in real world examples. Please see the following sample projects with complete code available in simulator-samples.

REST sample

SOAP sample

JMS sample

Mail sample

Combined sample


After forking/cloning the source code repository from you can build the application locally with Maven:

mvn clean install

You can start any of the sample simulator projects using maven:

mvn -pl simulator-samples/sample-rest spring-boot:run 

For active development and a short round trip you can use the angular-cli dev-server in order to automatically compile typescript sources on the fly when they change.

mvn -pl simulator-ui package -Pdevelopment

If you change a source file (e.e *.js, *.ts, *.css) the sources will automatically be compiled and copied to the Maven target folder. The running spring-boot application is able to automatically grab the newly compiled sources. Just go to the browser and hit refresh to see the changes. If you change server Java sources spring-boot automatically restarts the web application so you may just hit refresh in your browser, too.

The development server is running on its own port 4200 (http://localhost:4200). To avoid cors issues an api proxy to the backend is provided out of the box. You can configure the proxy settings in proxy.conf.json.

Make sure to start one of the sample projects so that you have a server running that the UI can connect to.


Read the simulator user manual for detailed instructions and features. For more information on Citrus see, including a complete reference manual.