Citrus Simulator

Utilizing the synergy of Spring Boot and the Citrus testing framework, the citrus-spring-boot-simulator empowers you to craft your simulator scenarios using either Java or XML. Each interaction with the simulator is logged in an internal database, accessible for review through the REST API or the web UI. We welcome your feedback and contributions with great appreciation!

We are proud to announce that the simulator application is stable and reliable for general use. However, it is important to note that certain experimental features are included as part of our commitment to innovation. These features are introduced with "feature flags" and are still in the developmental phase:

WSDL Generated Scenarios: Automatically create simulator scenarios from a WSDL file.

Swagger Generated Scenarios: Automatically create simulator scenarios from a Swagger API file.

These features are evolving, and with the valuable insights we receive from our community, we are optimistic that they will achieve stability in due course.

Before embarking on your journey with the simulator application, ensure you meet the following prerequisites:

Gradle uses Groovy-based build scripts which we need to add when starting a new simulator project.

The above build script will set up the necessary Spring Boot dependencies and include the basic citrus-spring-boot-simulator dependency. With the Gradle build complete, we’re now ready to build and run the simulator.

Using Maven, you can easily incorporate the simulator into your project. Maven automatically manages the download of all necessary dependencies and project artifacts. Once configured, the simulator can be executed using Spring’s embedded web servers.

Below is a sample pom.xml for a Maven project configured as a Spring Boot application.

The pom.xml file above sets up the Spring Boot application and includes the Citrus Simulator dependency. With this setup complete, the simulator is ready to be built and run.

That’s it, you’re read to write your first Scenario.

To build and run the simulator with Maven, execute the following commands from the command line:

Upon execution, the application should start up and the console will display log output detailing the process. The web server should be active within seconds. After the application is running, open your browser and go to http://localhost:8080 to see the basic simulator user interface. For a more detailed interface, please consult the chapter on the user interface.

The REST default scenario that we’ve included is reachable at http://localhost:8080/services/rest/, where you’ll encounter the default message Welcome to the Citrus simulator.

You are now prepared to utilize the Citrus simulator. The next steps involve comprehending the concepts and crafting some simulator scenarios.

Maven archetypes are templates that can quickly set up a new project structure for you. When starting a new Citrus Simulator project, using a Maven archetype can save you time and effort.

To generate a new project using the Citrus Simulator archetype, run the following command in your terminal:

The -B flag indicates batch mode, which makes the command non-interactive. If you omit this, Maven will interactively ask you for any required values not provided as -D options.

Upon executing the command, Maven will generate a new project based on the specified archetype. This project will be placed in a new directory corresponding to the artifactId you provided. Change into this directory to proceed with building your new simulator project.

Citrus provides various archetypes for different types of simulators, each tailored to a specific protocol or data format:

Choose the archetype that best matches the needs of your project.

With the project’s build and source code established, you can begin coding your simulator scenarios. This project is a standard Java application, which you can develop within your preferred Java IDE. Tools like Maven or Gradle are used to compile and package your simulator into an executable artifact, typically a Spring Boot executable jar.

To optimize your development process, consider using Spring Boot DevTools. This library provides additional development-time features that can greatly enhance your productivity:

To use DevTools, include the following dependency in your build configuration:

With Spring Boot DevTools included, every time you compile your code, the application will restart, recognizing your changes immediately. This makes the development loop much faster and feedback-oriented.

Ensure that your IDE is configured to build the project automatically on each save. If you’re using an IDE like Eclipse or IntelliJ IDEA, they have built-in support for automatic compilation which integrates seamlessly with DevTools.

Remember to disable the DevTools in production environments, as its features are only beneficial in a development setting and may have performance implications for production deployments.

With your development environment optimized, you can now focus on adding functionality and creating comprehensive simulation scenarios for thorough testing and robust service emulation.

Containerizing your Spring Boot application using Docker simplifies deployment and ensures consistency across different environments. There is lots of documentation about this process available online. It’s best to consider multiple sources, especially for a production build! To get started, here’s how to package your Citrus Simulator into a Docker container.

The simulator is a standard Spring Boot application. This means we have a main class that loads the Spring Boot application. If you haven’t set one up already, see how to get started with Gradle or Maven.

This class is the main entrance for all configuration and customization statements. By default, REST support is enabled with all configuration needed. You can enable or disable the message transport support for different technologies via application properties.

When enabled, the simulator’s autoconfiguration for this specific message transport is activated, and all required beans and configuration are loaded at startup.

You can also combine message transports in the simulator application, although this feature is of experimental nature up to now.

The simulator is capable of loading configuration from system properties, environment variables, and property files. First, the default Spring Boot properties configuration mechanism is supported. Following from that, you can add properties to the application.properties file in your project resources to adjust simulator behavior.

The available simulator properties are grouped into the following configuration classes:

There are several properties that you can use to customize the simulator behavior, such as:

Please refer to the respective configuration property classes to see in detail what property settings are supported.

Citrus operates within the Spring framework ecosystem, and the simulator is constructed as a Spring Boot application. Consequently, configuration is primarily conducted through the addition and customization of Spring beans within the application context. The simulator automatically loads Spring beans defined in the following locations:

All beans delineated within these files are seamlessly integrated into the simulator’s Spring application context upon loading. This process ensures that all necessary configurations are applied to facilitate the desired behavior of the simulator. Furthermore, customizations and additional beans can be added to adapt to more complex scenarios or to extend the simulator’s capabilities beyond its default configuration set.

The simulator offers a comprehensive REST API for interacting with system entities. The following resources are available:

For each listed resource, the following operations are supported:

All REST resources adhere to this pattern, with exceptions noted in subsequent sections.

The scenario mapper implementation determines the association between incoming request messages and simulator scenarios. For each incoming request, a predefined scenario is triggered, which in turn generates the response message for the client. The scenario is selected based on a mapping key, which is extracted from the incoming request.

The simulator utilizes several methods to ascertain the correct scenario from incoming request messages:

When a scenario is identified using a specific mapping key, it is subsequently loaded and executed. Each scenario performs test logic, as defined by Citrus, to provide a suitable response message. Through this mechanism, the simulator can generate complex and dynamic responses.

The following classes implement the various scenario mapping strategies:

Custom scenario mapper implementations are also possible. To introduce a custom mapper, one simply implements the interface methods of the corresponding API and incorporates the custom class into the simulator configuration, as will be detailed later in this documentation.

Simulator scenarios are defined to generate responses for incoming requests, with each scenario corresponding to distinct logic and messages. A scenario first assigns a name for identification by mapping strategies. It is represented by a Java class implementing the SimulatorScenario interface.

Scenarios grant access to the invoked endpoint and allow message transactions through it. Default run methods determine the logic execution pathway, depending on the desired Java DSL API. Inheriting from org.citrusframework.simulator.scenario.AbstractSimulatorScenario is typical for simplifying scenario creation.

Consider the example below for a standard scenario.

By extending AbstractSimulatorScenario, we insert receive and send logic into the run method. The @Scenario annotation defines the scenario name. Citrus Java DSL methods facilitate message handling in the implementation.

Dynamic value extraction from requests for use in responses is also supported:

The ${userName} variable is derived from the request and used to personalize the response. This approach leverages Citrus’s capability to create dynamic responses. Both XML, JSON, and Plaintext payload types are supported by this dynamic mechanism.

Writing various scenarios enables the generation of diverse responses, with unique scenario names linked to values determined by the scenario mapper. This setup allows for the creation of scenarios specific to incoming request messages. Additionally, Citrus’s send and receive operations handle messages across different transport types.

For more information on message transport support, see the chapters REST configuration, WS configuration, JMS configuration and endpoint configuration.

The simulator starts a new scenario instance for each incoming request based on the defined scenario mapping. Sometimes a running scenario instance needs to receive another incoming request. In such cases, the simulator handles the process differently, as the incoming request should not trigger a new scenario instance but should be forwarded to the running scenario.

This process is referred to as intermediate message handling within scenarios. A scenario can activate message correlation for specific requests. Before initiating a new scenario, the simulator always checks all running scenarios for matches with intermediate message correlations. This allows us to receive additional incoming requests within the same scenario instance.

To explain this concept, consider the following simple example.

In the scenario above, a new correlation starts on the header entry X-CorrelationId and the variable value ${correlationId} extracted from the first request. This allows the scenario to receive further incoming request messages with the correlation identifier, ensuring it receives the specific message first, before any other running scenarios.

This mechanism enables a scenario instance to handle more than one incoming request. Message correlation can be based on header values or XPath expressions evaluated within the message payload.

The above example uses XPath expressions to establish a new correlation within the scenario. This ensures that the second incoming request CancelFaxMessage is directed to the same scenario instance.

Intermediate message handling enables the creation of complex scenarios that involve multiple request-response interactions. Message correlation ensures that the relevant requests are processed within the same scenario, without interference from other concurrent scenarios.

It might be possible that unexpected errors occur during simulations. But how would you know that this is the case, you might ask yourself? It could as well be, that someone just wanted this simulation to respond with an HTTP 500 code.

That’s why we’ve invented the custom HTTP 555 status code: Simulation failed with an Exception!

The error can be asserted from the client side, the body containing more detailed information.

The Citrus Simulator offers different modes of operation to accommodate various testing scenarios and requirements. These modes dictate how the simulator executes the test scenarios. It comes with two modes, a synchronous and an asynchronous one, providing flexibility in how interactions are simulated and tested.

By understanding and appropriately configuring the execution modes of the Citrus Simulator, you can tailor the simulation environment to best suit your testing needs, whether you require precise control over scenario execution or need to simulate high-volume, concurrent interactions.

In some cases, it may be useful to keep the database schema in mind. The following diagram illustrates the database schema as defined in the package org.citrusframework.simulator.model, which should be considered the source of truth. This visual representation can help understand the relationships and structure of the database entities.

Registering simulator scenarios at runtime is a perfectly valid approach. However, it’s crucial to ensure that the scenario cache used by the simulator remains synchronized.

A "Scenario" in this context is not a database entity but rather a conceptual object that exists only during runtime. Essentially, these are simply Spring beans. The ScenarioLookupService is responsible for tracking these scenarios but cannot do so automatically. Therefore, after making modifications, it’s necessary to call ScenarioLookupService#evictAndReloadScenarioCache() to update the cache.

The following Java source code illustrates how to register a custom scenario and update the scenario cache:

With REST support enabled, various configuration options are available, typically via a SimulatorRestAdapter implementation:

The adapter allows customization of REST handling, such as implementing different scenario mappers or adding handler interceptors.

Note: By default, the REST support uses the HttpRequestAnnotationScenarioMapper to search for @RequestMapping annotations on scenario classes.

The urlMappings method defines the access path to the simulator’s REST API. Assuming the Spring Boot application runs on port 8080, the API would be accessible at:

Clients can send requests like GET, POST, DELETE to this endpoint, and the simulator will respond based on the executed scenario.

Customize the simulator REST support by extending SimulatorRestAdapter in a custom class:

Annotate your custom class with @Component to override the default REST adapter behavior. Now, the REST API will be accessible at http://localhost:8080/my-rest-service/*.

Extend the adapter directly in the main application class for further customizations:

For more advanced configurations, extend SimulatorRestSupport:

This approach allows you to override auto-configuration features like requestCachingFilter or handlerMapping.

By default, the simulator maps incoming requests to scenarios using mapping keys evaluated from the requests. When utilizing REST support, @RequestMapping annotations on scenarios can also be used:

In the above example, any POST request to /services/rest/simulator/hello with the user query parameter will be mapped to the HelloScenario.

HTTP responses in REST APIs should include appropriate status codes. This can be easily specified using Citrus’s Java DSL:

Citrus’s HTTP Java DSL simplifies setting request methods, query parameters, and status codes. Refer to the Citrus documentation for more details on using this API.

The simulator is equipped to interpret Swagger (OpenAPI V3.0) specifications, using them to automatically generate scenarios for each defined operation. This feature streamlines the process of creating a simulator that mirrors real-world API behavior based on the Swagger documentation.

To utilize this feature, the Swagger API file should be configured within the simulator’s settings. Below is an example of how to set up Swagger support:

In the above configuration, the HttpScenarioGenerator bean is defined with the location of the Swagger API file (swagger/petstore-api.json) and the context path for the API. The HttpRequestPathScenarioMapper is set to handle the REST scenarios generated from the Swagger specification.

Additionally, a custom fallback endpoint adapter is defined for handling unmatched requests or validation errors.

Upon startup, the simulator dynamically generates scenarios for each operation in the Swagger API file. These scenarios are available for review in the simulator’s user interface.

Consider the following sample operation from the Swagger API file:

This operation would prompt the simulator to generate scenarios that validate requests against the defined criteria and provide appropriate responses, including handling different HTTP methods and query parameters.

Important: The current implementation primarily focuses on generating scenarios for successful cases, like 200 OK responses. Other variations, such as error responses, are not automatically generated but can be manually added.

The simulator’s response to requests is based on the generated scenarios. For a valid request, it would provide a response as defined in the Swagger specification. Conversely, for an invalid request (e.g., missing required parameters), the simulator would respond with an error, such as 404 NOT_FOUND.

Swagger support can also be configured using system properties or environment variables, providing an alternative to programmatically setting up the HttpScenarioGenerator.

Of course, the same can be achieved using environment variables.

To further enhance dynamic message handling, data dictionaries can be used. These dictionaries allow for centralized manipulation of message content via JsonPath expressions, making the interaction with the simulator more dynamic and adaptable.

Data dictionaries are defined in property files, with mappings that dictate how message content should be manipulated:

These mappings apply to both incoming and outgoing messages, ensuring that the simulator’s responses are dynamic and contextually relevant, adhering to the constraints and possibilities defined in the Swagger specification.

Once SOAP support is enabled in the simulator, various configuration options become available. The most straightforward method is to add a SimulatorWebServiceAdapter implementation to the classpath. This adapter provides several configuration methods.

This adapter defines methods to configure the simulator’s SOAP message handling, such as adding different scenario mapper implementations or endpoint interceptors. The servletMappings method defines client access to the simulator’s SOAP service. For example, if the Spring Boot application runs on port 8080, the SOAP service would be accessible at:

Clients can send SOAP calls to this endpoint, and the simulator will respond with appropriate SOAP responses based on the executed scenario. You can customize the simulator’s SOAP support by extending SimulatorWebServiceAdapter in a custom class:

The class is annotated with @Component so that Spring recognizes it and overrides the default SOAP adapter behavior. By customizing the servletMappings method, the SOAP simulator API will be accessible under a new endpoint URI:

For direct integration with the Spring Boot main application class, extend SimulatorWebServiceAdapter as shown:

For more advanced configurations, extend SimulatorWebServiceSupport:

This configuration allows overriding features like the messageDispatcherServlet in the SOAP support auto-configuration.

When using SOAP services, you might want to respond synchronously with a SOAP message. Since the simulator handles SOAP communication automatically, you can define the response message directly in the scenario.

The Citrus Java DSL provides SOAP-specific methods for specifying request and response data. The SOAP envelope is handled automatically, so there’s no need to include it here. The receive operation verifies the SOAP action header value, and you can specify the synchronous SOAP response message.

Next, we will discuss how to send SOAP faults as response messages.

When using SOAP, you may need to send back a SOAP fault message. The default Web Service scenario implementation allows sending fault responses.

In this example, the sendFault() method is used to create a SOAP fault message. The simulator adds the SOAP envelope and fault details, allowing you to choose between a success response or a SOAP fault.

The simulator can read WSDL specifications to auto-generate scenarios for each defined operation. These operations include request and response message data, which the simulator uses to generate basic scenarios.

To set up WSDL support, see the following example:

In the configuration above, a WsdlScenarioGenerator bean is set up with the WSDL file location xsd/Hello.wsdl. A custom fallback endpoint adapter is also defined for handling unmatched requests or validation errors.

Upon startup, the generator creates scenarios for each operation in the WSDL file.

Consider the following WSDL file sample:

This WSDL defines operations like hello, with request and response message structures.

Generated scenarios validate requests against the XSD schema in the WSDL and generate appropriate responses. Dynamic values in responses adhere to the schema rules.

Communication in generated scenarios follows this pattern:

For invalid requests, such as those with incorrect SOAP actions, the simulator responds with a default SOAP fault, as defined in the fallback endpoint adapter.

Once the JMS support is enabled on the simulator we have different configuration options. The most comfortable way is to add a SimulatorJmsAdapter implementation to the project. The adapter provides several configuration methods.

The adapter defines methods that configure the simulator JMS handling. For instance we can add another scenario mapper implementation or enable automatic SOAP envelope handling.

The destinationName defines the incoming JMS destination to poll as a consumer. The connectionFactory is mandatory in order to connect to a JMS message broker.

You can simply extend the adapter in a custom class for adding customizations.

As you can see the class is annotated with @Component annotation. This is because the adapter should be recognized by Spring in order to overwrite the default JMS adapter behavior. The custom adapter just overwrites the connectionFactory and destinationName methods so the JMS simulator will connect to the ActiveMQ message broker and listen for incoming requests on that queue JMS.Queue.simulator.inbound.

This is the simplest way to customize the simulator JMS support. We can also use the adapter extension directly on the Spring boot main application class:

Once this is done the simulator polls the target destination for new incoming request messages. As usual the simulator maps incoming requests to simulator scenarios for execution. Inside the scenario you can receive the JMS request messages as usual using the scenario endpoint. The scenario logic is then able to provide a response message that is sent back to the synchronous reply destination if any is specified.

For asynchronous communication we can define normal JMS destination endpoints in Citrus in order to autowire those in the scenario.

As you can see we are able to create several JMS endpoints in Citrus. We can autowire those endpoints in a scenario for sending back an asynchronous response.

In this sample above we receive the scenario request message as usual using the scenario endpoint. After that we send back a response on the replyEndpoint which has been injected to the scenario using the @Autowired annotation.

In general scenarios can interact with all Citrus endpoints that get defined as Spring beans in the application context configuration.

When dealing with synchronous communication the message producer waits for a reply message on a reply destination. This reply destination handling is automatically done within the simulator. So when we have synchronous communication we simply send back a response message using the scenario endpoint. The simulator makes sure that the response is provided to the waiting producer on the reply destination.

The synchronous JMS communication needs to be enabled on the JMS simulator adapter.

This completes the JMS communication support within the simulator. Read more about other messaging transports such as Http REST or SOAP in this documentation.

As we are using generic Citrus endpoint components as inbound source we need to configure those endpoint components. The most comfortable way is to add a SimulatorEndpointComponentAdapter implementation to the classpath. The adapter provides several configuration methods.

The adapter defines methods that configure the endpoint component used as inbound source. As usual we can set the scenario mapper implementation or add automatic SOAP envelope support.

More importantly we need to define an inbound endpoint that is used as source for scenarios. Let’s have a simple endpoint component adapter example.

The custom adapter defines a Citrus mail server endpoint that should be used as inbound source. Any mail message that arrives at this mail server component will trigger a new simulator scenario then. Also we overwrite the scenario mapper implementation. The sample uses a content based XPath mapper that uses the mail subject value as scenario mapping key.

As mail server endpoint support is not included by default in the simulator we need to add some Citrus dependencies to our project. In Maven we simply add the following dependency to the project POM.

This configuration would lead us to a mail server that responds to incoming mail messages base on the mail subject. So we can have several simulator scenarios for different mail messages.

The scenario implementation above is listening for mail messages of subject Hello. The mail XML marshalling is automatically done by Citrus. This is the usual way how the Citrus mail component handles mail messages and responses. That means we can use the default Citrus features in our simulator, too. The scenario sends back a positive mail response to the calling client.

This is how we can use any Citrus endpoint component as simulator inbound source. This gives us the opportunity to support a huge set of message transports and message types in our simulator applications. Each incoming request on the endpoint component triggers a new simulator scenario.

To integrate the advanced Angular-based UI into your simulator project, add the following Maven dependency:

Replace ${citrus.simulator.version} with the appropriate version of the Citrus Simulator you are using. This information can typically be found in the project documentation or the repository where the simulator is hosted.

Upon successful integration and starting the simulator, the Angular-based UI becomes accessible at http://localhost:8080, automatically enhancing the default user interface without any additional configuration. The simulator dashboard provides a comprehensive overview of your project, presenting key metrics and insights at a glance.

The "Scenarios" tab within the user interface displays all scenarios available for automatic mapping upon handling incoming requests. This tab not only lists the scenarios but also offers functionalities such as initiating scenario executions directly from the UI.

Selecting any scenario from the list opens a detailed view of that specific scenario. This view includes comprehensive information about the scenario, such as the messages processed during executions and the results of each execution, providing valuable insights into the behavior and outcome of the scenario.

Each scenario detail page is designed to offer a deep dive into the scenario’s workings, including the input and output data, any validations or assertions applied, and a step-by-step breakdown of the scenario’s execution path. This level of detail aids in understanding each scenario’s role within the simulator and troubleshooting any issues that may arise.

Every execution of a scenario within the simulator is meticulously recorded, with the results readily accessible through the user interface for review and analysis.

This view also provides rich filter possibilities, by name, status and so on. Even by headers of recorded messages.

Message header filtering uses a specific syntax.

Combining multiple patterns: Separate multiple filter expressions with a semicolon (;). They will be combined using logical AND operators. (e.g., source=myApp; status=active)

There is a helping dialog available to the right of the message-header input field.

For instances when you require more detailed information or are unable to locate specific data within the simulator’s UI, the "Entities" drop-down menu offers a solution. Located at the top of the user interface, this menu provides direct access to all database entities used by the simulator, allowing for an in-depth review of the underlying data.

Starter implementations are executable in the simulator user interface. The starter is able to define parameters that should be filled out before the starter performs its actions. In the starter class you can specify the parameters as follows:

The sample above defines a parameter called greeting. The parameter is of type textbox and has a default value Hi there!. This parameter information is used to aut generate a HTML form in the simulator user interface. You can specify as multiple parameters of different types.

Parameters can be required or optional and receive a label that is displayed in the HTML form. Also you can add default values.