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:

Usage

You should specify the version in your project’s plugin configuration:

  
<project>
  ...
  <build>
    <!-- To define the plugin version in your parent POM -->
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.citrusframework</groupId>
          <artifactId>citrus-remote-maven-plugin</artifactId>
          <version>4.4.0</version>
        </plugin>
        ...
      </plugins>
    </pluginManagement>
    <!-- To use the plugin goals in your POM or parent POM -->
    <plugins>
      <plugin>
        <groupId>org.citrusframework</groupId>
        <artifactId>citrus-remote-maven-plugin</artifactId>
        <configuration>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

Goals

citrus-remote:test-jar

Full name

org.citrusframework:citrus-remote-maven-plugin:4.4.0: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

citrus-remote:test-war

Full name

org.citrusframework:citrus-remote-maven-plugin:4.4.0: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

citrus-remote:test

Full name

org.citrusframework:citrus-remote-maven-plugin:4.4.0:test

Description

Triggers the execution of the citrus test by performing a remote API call to the test-server.

Parameters

citrus-remote:verify

Full name

org.citrusframework:citrus-remote-maven-plugin:4.4.0: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

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>

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>

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.