Maven remote plugin
The Citrus Maven Remote plugin can be used for packaging all Citrus tests into a test-server and for accessing this test-server via a remote API call. At present the following remote API calls are supported:
- Execute the citrus-integration tests.
- Poll the test-server, checking whether the test execution has completed.
This provides an alternative means of executing tests to the usual surefire and failsafe maven plugins that execute the tests locally within the scope of the maven build. The main benefit of using this approach however is that the Citrus tests can be built and run inside of a docker container. This makes it easier to execute the tests and mock the endpoints used by the system under test that may otherwise not be possible in certain containerized environments.
System Requirements
The following specifies the minimum requirements to run this Maven plugin:
Library | Version |
---|---|
Maven | 3.3 |
JDK | 1.8 |
Memory | No minimum requirement. |
Disk Space | No minimum requirement. |
Usage
You should specify the version in your project’s plugin configuration:
Goals
Goal | Description |
---|---|
citrus-remote:test-jar | Assembles an executable JAR file containing the test-server and all test cases. |
citrus-remote:test-war | Assembles a WAR file that contains all test cases that can be deployed in any servlet container. |
citrus-remote:test | Triggers the execution of the test cases on the remote test-server |
citrus-remote:verify | Checks the results of the test execution on the remote test-server, waiting if necessary for the completion of the test execution. |
citrus-remote:help | Display help information on citrus-remote-maven-plugin. To display parameter details call: mvn citrus-remote:help -Ddetail=true -Dgoal=<goal-name> |
citrus-remote:test-jar
Full name
org.citrusframework:citrus-remote-maven-plugin:4.3.3:test-jar
Description
Packages all integration tests into a JAR file that can be executed.
After creation the JAR file, which contains a test-server, can be started manually using: java -jar <jar-file>
Parameters
Name | Type | Description |
---|---|---|
finalName | String | The prefix used for the executable jar filename. The format used is <finalName>-citrus-tests.jar. Default value is: ${project.build.finalName}. |
mainClass | String | The class that is executed when the jar file is run. Default value is: org.citrusframework.remote.CitrusRemoteServer |
skip | Boolean | Skip the creation of the executable JAR file. Default value is: false. Can also be set using ${citrus.remote.plugin.skip} |
skipTestJar | Boolean | Skip the creation of the executable JAR file. Default value is: false. Can also be set using ${citrus.skip.test.jar} |
testJar | Embedded | The test jar configuration. Refer to the Test JAR configuration for details. |
assembly | Embedded | The assembly configuration. Refer to the Assembly configuration for details. |
citrus-remote:test-war
Full name
org.citrusframework:citrus-remote-maven-plugin:4.3.3:test-war
Description
Packages all integration tests into a WAR file.
After creation the WAR file can be deployed in any standard servlet container.
Parameters
Name | Type | Description |
---|---|---|
finalName | String | The prefix used for the WAR filename. The format used is <finalName>-citrus-tests.war. Default value is: ${project.build.finalName}. |
skip | Boolean | Skip the creation of the WAR file. Default value is: false. Can also be set using ${citrus.remote.plugin.skip} |
skipTestWar | Boolean | Skip the creation of the war file. Default value is: false. Can also be set using ${citrus.skip.test.war} |
testJar | Embedded | The test jar configuration. Refer to the Test JAR configuration for details. |
assembly | Embedded | The assembly configuration. Refer to the Assembly configuration for details. |
citrus-remote:test
Full name
org.citrusframework:citrus-remote-maven-plugin:4.3.3:test
Description
Triggers the execution of the citrus test by performing a remote API call to the test-server.
Parameters
Name | Type | Description |
---|---|---|
report | Embedded | The report configuration. Refer to the Report configuration for details. |
run | String | The run configuration. Refer to the Run configuration for details. |
server | String | The server configuration. Refer to the Server configuration for details. |
skip | Boolean | Skip the creation of the executable jar file. Default value is: false. Can also be set using ${citrus.remote.plugin.skip} |
skipRun | Boolean | Skip the running of the tests. Default value is: false. Can also be set using ${citrus.remote.skip.test} |
timeout | Integer | Http connect timeout in milliseconds. Default value is: 60000. Can also be set using ${citrus.remote.plugin.timeout} |
citrus-remote:verify
Full name
org.citrusframework:citrus-remote-maven-plugin:4.3.3:verify
Description
Checks the results of the test-execution. If any tests fail then verify MOJO will fail causing the maven build to fail.
Parameters
Name | Type | Description |
---|---|---|
failIfNoTests | Boolean | Fail build if not tests were executed. Default value is: true. Can also be set using ${citrus.remote.failIfNoTests} |
report | Embedded | The report configuration. Refer to the Report configuration for details. |
skip | Boolean | Skip the creation of the executable jar file. Default value is: false. Can also be set using ${citrus.remote.plugin.skip} |
Assembly configuration
The citrus-remote-maven-plugin provides out of the box assembly descriptors for building the war and executable-jar files.
default executable-jar assembly:
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsd">
<id>citrus-tests</id>
<formats>
<format>jar</format>
</formats>
<includeBaseDirectory>false</includeBaseDirectory>
<dependencySets>
<dependencySet>
<outputDirectory>/</outputDirectory>
<useProjectArtifact>false</useProjectArtifact>
<useProjectAttachments>true</useProjectAttachments>
<unpack>true</unpack>
<scope>test</scope>
</dependencySet>
</dependencySets>
</assembly>
default war-assembly:
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.0.0 http://maven.apache.org/xsd/assembly-2.0.0.xsd">
<id>citrus-tests</id>
<formats>
<format>war</format>
</formats>
<includeBaseDirectory>false</includeBaseDirectory>
<dependencySets>
<dependencySet>
<outputDirectory>/WEB-INF/lib</outputDirectory>
<useProjectArtifact>false</useProjectArtifact>
<useProjectAttachments>true</useProjectAttachments>
<unpack>false</unpack>
<scope>test</scope>
<excludes>
<exclude>org.eclipse.jetty:jetty-webapp</exclude>
<exclude>org.eclipse.jetty.websocket:websocket-server</exclude>
<exclude>org.eclipse.jetty.websocket:websocket-servlet</exclude>
</excludes>
</dependencySet>
</dependencySets>
<fileSets>
<fileSet>
<directory>${project.basedir}/src/test/resources/WEB-INF</directory>
<outputDirectory>WEB-INF</outputDirectory>
<includes>
<include>**/*</include>
</includes>
</fileSet>
</fileSets>
</assembly>
You can overwrite the defaults by configuring your own assembly. For details on how to create an assembly refer to the maven-assembly-plugin. To overwrite the default use one of the following approaches:
Assembly configuration using a file
<assembly>
<descriptor>
<file>${project.basedir}/citrus-assembly/citrus-war-assembly.xml</file>
</descriptor>
</assembly>
Assembly configuration using a reference
<assembly>
<descriptor>
<ref>my-assembly</ref>
</descriptor>
</assembly>
and then make sure to add the my-assembly.xml file under my-assembly-descriptor
+-- src
| `-- main
| `-- resources
| `-- assemblies
| `-- myassembly.xml
Assembly configuration using an inline assembly
<assembly>
<descriptor>
<inline>
<formats>
<format>war</format>
</formats>
<includeBaseDirectory>false</includeBaseDirectory>
</inline>
</descriptor>
</assembly>
Server configuration
The remote-maven-plugin uses a remote API call to trigger the test execution or to verify the results. The url of the test-server can be configured as shown below:
<server>
<url>http://citrus.remote-test-server.org/integration-citrus-test</url>
</server>
Report configuration
Report configuration such as output directory and file names.
The default configuration can be overwritten as shown below:
<report>
<directory>citrus-reports</directory>
<summaryFile>citrus-summary.xml</summaryFile>
<htmlReport>true</htmlReport>
<saveReportFiles>true</saveReportFiles>
</report>
Name | Type | Description |
---|---|---|
directory | String | The report directory. Default value is: citrus-reports. Can also be set using ${citrus.report.directory} |
summaryFile | String | The summary file name. Default value is: citrus-summary.xml. Can also be set using ${citrus.report.summary.file} |
htmlReport | Boolean | Enable/disable HTML report generation. Default value is: true. Can also be set using ${citrus.report.html} |
saveReportFiles | Boolean | Get reporting files from server and save them in report output directory. Default value is: true. Can also be set using ${citrus.report.save.files} |
Run configuration
Run configuration for test execution on remote server.
This can be configured as shown below:
<run>
<classes>
<class>com.consol.smoketests.IntegrationTestIT</class>
</classes>
<packages>
<package>com.consol.integrationtests</package>
</packages>
<includes>
<include>^.*IT$</include>
</includes>
<async>true</async>
<pollingInterval>10000</pollingInterval>
<systemProperties>
<spring.profiles.active>TEST</spring.profiles.active>
</systemProperties>
</run>
Name | Type | Description |
---|---|---|
classes | String | A list of citrus test classes to be executed |
packages | String | A list of packages to use to locate the tests to be executed |
includes | String | A list of patterns for locating tests to be executed |
async | Boolean | If true the test execution does not wait for all tests to complete before returning. Default value is: false (wait for tests to complete). Can also be set using ${citrus.remote.run.async} |
pollingInterval | Integer | The polling interval in milliseconds when checking for test execution completion. This is required when the tests are executed asynchronously (async=true). Default value is: 10000. Can also be set using ${citrus.remote.run.polling.interval} |
systemProperties | String | The list of systemProperties to set when starting the test execution. |
Test JAR configuration
The testJar configuration can be used for configuring which tests should be included in or excluded from the assembled JAR or WAR file. The default configuration:
- includes all tests
- uses the classifier tests as a suffix in the JAR or WAR filename (e.g. integration-citrus-tests.war)
The default configuration can be overwritten as shown below:
<testJar>
<classifier>tests</classifier>
<includes>
<include>^.*IT$</include>
</includes>
<excludes>
<exclude>^.*Skip_IT$</exclude>
</excludes>
</testJar>
The files to be included or excluded can be specified as fileset patterns which are relative to the input directory whose contents is being packaged into the test JAR.