Citrus Framework

You can easily create and run Citrus tests with JBang. The JBang tool support in Citrus is described in more detail in reference guide

Running Citrus via JBang does not require any project setup which is a fantastic match for fast prototyping of integration tests. The JBang command will automatically set up everything you need to run the Citrus test. This means you can run your test case sources directly from your command line.

To initialize a test you can run the script citrus@citrusframework/citrus with the init command as follows:

Initialize my-test.yaml

jbang citrus@citrusframework/citrus init my-test.yaml

The command above uses the JBang catalog citrus@citrusframework/citrus located on the Citrus GitHub repository. JBang will automatically resolve all dependencies and execute the command line script tool. This initializes the Citrus test file. You will find the created test source file in the current directory.

my-test.yaml

name: my-test
author: Citrus
status: FINAL
description: Sample test in YAML
variables:
  - name: message
    value: Citrus rocks!
actions:
  - echo:
      message: "${message}"

The JBang script is able to initialize any supported Citrus test domain specific language .java, .xml, .yaml, .groovy or .feature.

You can now run this test source file without any prior project setup using Citrus JBang:

Run my-test.yaml

jbang citrus@citrusframework/citrus run my-test.yaml

The command output will be like this:

Output

INFO 53887 --- [           main] citrusframework.testng.TestNGEngine : Running test source my-test.yaml
INFO 53887 --- [           main] org.testng.internal.Utils           : [TestNG] Running:
INFO 53887 --- [           main] rusframework.report.LoggingReporter :        .__  __                       
INFO 53887 --- [           main] rusframework.report.LoggingReporter :   ____ |__|/  |________ __ __  ______
INFO 53887 --- [           main] rusframework.report.LoggingReporter : _/ ___\|  \   __\_  __ \  |  \/  ___/
INFO 53887 --- [           main] rusframework.report.LoggingReporter : \  \___|  ||  |  |  | \/  |  /\___ \ 
INFO 53887 --- [           main] rusframework.report.LoggingReporter :  \___  >__||__|  |__|  |____//____  >
INFO 53887 --- [           main] rusframework.report.LoggingReporter :      \/                           \/
INFO 53887 --- [           main] rusframework.report.LoggingReporter : 
INFO 53887 --- [           main] rusframework.report.LoggingReporter : C I T R U S  T E S T S  4.5.2
INFO 53887 --- [           main] rusframework.report.LoggingReporter : 
INFO 53887 --- [           main] rusframework.report.LoggingReporter : ------------------------------------------------------------------------
INFO 53887 --- [           main] .citrusframework.actions.EchoAction : Citrus rocks!
INFO 53887 --- [           main] rusframework.report.LoggingReporter : 
INFO 53887 --- [           main] rusframework.report.LoggingReporter : TEST SUCCESS my-test (org.citrusframework)
INFO 53887 --- [           main] rusframework.report.LoggingReporter : ------------------------------------------------------------------------
INFO 53887 --- [           main] rusframework.report.LoggingReporter : 
INFO 53887 --- [           main] rusframework.report.LoggingReporter : 
INFO 53887 --- [           main] rusframework.report.LoggingReporter : CITRUS TEST RESULTS
INFO 53887 --- [           main] rusframework.report.LoggingReporter : 
INFO 53887 --- [           main] rusframework.report.LoggingReporter : SUCCESS (     3 ms) my-test
INFO 53887 --- [           main] rusframework.report.LoggingReporter : 
INFO 53887 --- [           main] rusframework.report.LoggingReporter : TOTAL:		1
INFO 53887 --- [           main] rusframework.report.LoggingReporter : SUCCESS:	1 (100.0%)
INFO 53887 --- [           main] rusframework.report.LoggingReporter : FAILED:		0 (0.0%)
INFO 53887 --- [           main] rusframework.report.LoggingReporter : PERFORMANCE:	0 ms
INFO 53887 --- [           main] rusframework.report.LoggingReporter : 
INFO 53887 --- [           main] rusframework.report.LoggingReporter : ------------------------------------------------------------------------

===============================================
Default Suite
Total tests run: 1, Passes: 1, Failures: 0, Skips: 0
===============================================

Install Citrus JBang app

For a more convenient command line usage you can install Citrus as a JBang app.

Install Citrus as JBang app

jbang trust add https://github.com/citrusframework/citrus/
jbang app install citrus@citrusframework/citrus

Now you can just call citrus and create and run tests with Citrus JBang.

Run my-test.yaml

citrus run my-test.yaml

Run tests

You can directly run test sources with Citrus JBang. This includes test sources written in Java (.java), XML (.xml), YAML (.yaml), Groovy (.groovy) or as a Cucumber Gherkin feature file (.feature).

Java test sources

Initialize MyTest.java

citrus init MyTest.java

MyTest.java

import org.citrusframework.TestCaseRunner;
import org.citrusframework.annotations.CitrusResource;

import static org.citrusframework.actions.CreateVariablesAction.Builder.createVariables;
import static org.citrusframework.actions.EchoAction.Builder.echo;

public class MyTest implements Runnable {

    @CitrusResource
    TestCaseRunner t;

    @Override
    public void run() {
        t.given(
            createVariables().variable("message", "Citrus rocks!")
        );

        t.then(
            echo().message("${message}")
        );
    }
}

Run MyTest.java

citrus run MyTest.java

XML test sources

Initialize my-test.xml

citrus init my-test.xml

my-test.xml

<test name="EchoTest" author="Christoph" status="FINAL" xmlns="http://citrusframework.org/schema/xml/testcase"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://citrusframework.org/schema/xml/testcase http://citrusframework.org/schema/xml/testcase/citrus-testcase.xsd">
  <description>Sample test in XML</description>
  <variables>
    <variable name="message" value="Citrus rocks!"/>
  </variables>
  <actions>
    <echo message="${message}"/>
  </actions>
</test>

Run my-test.xml

citrus run my-test.xml

YAML test sources

Initialize my-test.yaml

citrus init my-test.yaml

my-test.yaml

name: EchoTest
description: "Sample test in YAML"
variables:
  - name: "message"
    value: "Citrus rocks!"
actions:
  - echo:
    message: "${message}"

Run my-test.yaml

citrus run my-test.yaml

Groovy test sources

Initialize my-test.groovy

citrus init my-test.groovy

my-test.groovy

import static org.citrusframework.actions.EchoAction.Builder.echo

name "EchoTest"
description "Sample test in Groovy"

variables {
  message="Citrus rocks!"
}

actions {
  $(echo().message('${message}'))
}

Run my-test.groovy

citrus run my-test.groovy

Cucumber feature sources

Initialize my-test.feature

citrus init my-test.feature

my-test.feature

Feature: EchoTest

  Background:
    Given variables
    | message | Citrus rocks! |

  Scenario: Print message
    Then print '${message}'

Run my-test.feature

jbang --deps org.citrusframework.yaks:yaks-standard:0.20.0 citrus run my-test.feature

NOTE: Many of the predefined Cucumber steps (e.g. Then print '<message>') in Citrus are provided in a separate Citrus child project called YAKS. You need to add additional project dependencies for that steps to be loaded as part of the JBang script. The --deps option adds dependencies using Maven artifact coordinates. You may add the additional modules to the jbang.properties as described in the next section.

Additional JBang dependencies

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:

org.citrusframework:citrus-base
org.citrusframework:citrus-jbang-connector
org.citrusframework:citrus-groovy
org.citrusframework:citrus-xml
org.citrusframework:citrus-yaml
org.citrusframework:citrus-http
org.citrusframework:citrus-validation-json
org.citrusframework:citrus-validation-xml

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:

jbang.properties

# Declare required additional dependencies
run.deps=org.citrusframework:citrus-camel:4.5.2,\
org.citrusframework:citrus-testcontainers:4.5.2,\
org.citrusframework:citrus-kafka:4.5.2

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.

IMPORTANT: In case you want to run Cucumber BDD Gherkin feature files and use the predefined steps included in the YAKS project, you need to add this YAKS runtime dependency accordingly: org.citrusframework.yaks:yaks-standard:0.20.0

Run from clipboard

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).

Run YAML test from Clipboard

citrus run clipboard.yaml

List tests

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

List running tests

citrus ls

Command output

PID   NAME         STATUS  AGE 
19201 my-test.yaml Running 20s

JBang sample ∞

Install Citrus JBang app

Run tests

Java test sources

XML test sources

YAML test sources

Groovy test sources

Cucumber feature sources

Additional JBang dependencies

Run from clipboard

List tests