Integrate Citrus with Maven

This tutorial shows you how to setup a new Citrus project with Maven. You will see it is very easy and you are finished within minutes.

In case you already use Maven build tool in your project it is most suitable for you to include Citrus into your Maven build lifecycle. In this tutorial we will setup a project with Maven and configure the Maven POM to execute all Citrus tests during the Maven integration-test phase. First of all we create a new Java project called "citrus-sample". We use the Maven command line tool in combination with Maven's archetype plugin. In case you do not have Maven installed yet it is time for you to do so before continuing this tutorial. See the Maven site for detailed installation instructions. So let's start with creating the Citrus Java project: 

  mvn archetype:generate -DarchetypeCatalog=http://citrusframework.org
  
  [...]
  
  Choose archetype:
  1: http://citrusframework.org -> citrus-archetype (Basic archetype for Citrus integration test project)
  Choose a number: 1 

  Define value for groupId: com.consol.citrus.samples
  Define value for artifactId: citrus-sample
  Define value for version: 1.0-SNAPSHOT
  Define value for package: com.consol.citrus.samples
  
  [...]

Citrus provides a custom Maven archetype. We load the archetype information from "http://citrusframework.org" and choose the Citrus basic archetype. Now you have to define several values for your project: the groupId, the artifactId, the package and the project version. After that we are done! Maven created a Citrus project structure for us which is ready for testing. You should see the following basic project folder structure.

  citrus-sample
  |   + src
  |   |   + main
  |   |    |   + java
  |   |    |   + resources
  |   |   + citrus
  |   |    |   + java
  |   |    |   + resources
  |   |    |   + tests
  pom.xml

The Citrus project is absolutely ready for testing. With Maven we can build, package, install and test our project right away without any adjustments. Try to execute the following commands:

  cd citrus-sample
  mvn package
  mvn integration-test
  mvn install

Congratulations! You just have built the complete project and you also have executed the first Citrus tests in your project. The project comes with a sample Citrus test "SampleTest". You can find this test in "src/citrus/tests" and "src/citrus/java". The Citrus test was automatically executed in the integration test phase in Maven project lifecycle.

The next step would be to import our project into our favorite IDE (e.g. Eclipse, IntelliJ or NetBeans). With Eclipse for instance you have to execute the following command:

  mvn eclipse:eclipse

Now let's import the new Citrus project into the IDE and have a closer look at the basic project files that were generated for you. First of all open the Maven POM (pom.xml). You see the basic Maven project settings, all Citrus project dependencies as well as the ConSol* Labs Maven repositories here. In future you may add other project dependencies, Maven plugins in this file. For now you do not have to change the Citrus Maven settings in your project's POM, however we have a closer look at them:

First of all the ConSol* Labs Maven repositories. Maven will load new versions of Citrus from these servers.

  <repositories>
    [...]
  
    <repository>
      <id>consol-labs-release</id>
      <url>http://labs.consol.de/maven/repository/</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <releases>
        <enabled>true</enabled>
      </releases>
    </repository>
    <repository>
      <id>consol-labs-snapshots</id>
      <url>http://labs.consol.de/maven/snapshots-repository/</url>
      <snapshots>
        <enabled>true</enabled>
        <!-- Policy: always, daily, interval:xxx (xxx=#minutes, 60*24*7=10080), never -->
        <updatePolicy>10080</updatePolicy>
      </snapshots>
      <releases>
        <enabled>false</enabled>
      </releases>
    </repository>
    
    [...]
  </repositories>
  <pluginRepositories>
    [...]
  
    <pluginRepository>
      <id>consol-labs-release</id>
      <url>http://labs.consol.de/maven/repository/</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <releases>
        <enabled>true</enabled>
      </releases>
    </pluginRepository>
    <pluginRepository>
      <id>consol-labs-snapshots</id>
      <url>http://labs.consol.de/maven/snapshots-repository/</url>
      <snapshots>
        <enabled>true</enabled>
        <updatePolicy>10080</updatePolicy>
      </snapshots>
      <releases>
        <enabled>false</enabled>
      </releases>
    </pluginRepository>
    
    [...]
  </pluginRepositories>

The Citrus project libraries as dependencies.

  <dependency>
    <groupId>com.consol.citrus</groupId>
    <artifactId>citrus-core</artifactId>
    <version>1.2.M2</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>com.consol.citrus</groupId>
    <artifactId>citrus-ws</artifactId>
    <version>1.2.M2</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>com.consol.citrus</groupId>
    <artifactId>citrus-http</artifactId>
    <version>1.2.M2</version>
    <scope>test</scope>
  </dependency>

The Citrus Maven plugin capable of test creation and report generation.

  <plugin>
    <groupId>com.consol.citrus.mvn</groupId>
    <artifactId>citrus-maven-plugin</artifactId>
    <version>1.2.M2</version>
    <configuration>
      <author>Mickey Mouse</author>
      <targetPackage>com.consol.citrus</targetPackage>
    </configuration>
  </plugin>

The surefire plugin is responsible for executing all available tests in your project when you run the integration-test phase in Maven:

  <plugin>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.4.3</version>
    <configuration>
      <skip>true</skip>
    </configuration>
    <executions>
      <execution>
        <id>citrus-tests</id>
        <phase>integration-test</phase>
        <goals>
          <goal>test</goal>
        </goals>
        <configuration>
          <skip>false</skip>
        </configuration>
      </execution>
    </executions>
  </plugin>

Last not least the Citrus source directories defined as test sources for Maven:

  <testSourceDirectory>src/citrus/java</testSourceDirectory>
  <testResources>
    <testResource>
      <directory>src/citrus/resources</directory>
      <includes>
        <include>**/*</include>
      </includes>
      <filtering>true</filtering>
    </testResource>
    <testResource>
      <directory>src/citrus/tests</directory>
      <includes>
        <include>**/*.xml</include>
      </includes>
      <excludes>
      </excludes>
    </testResource>
  </testResources>

Finally we are ready to proceed with creating new test cases. So let's add a new Citrus test case to our project. We use the Citrus Maven plugin here, just type the following command:

  mvn citrus:create-test
  Enter test name: MyTest
  Enter test author: Unknown: : Christoph
  Enter test description: TODO: Description: : 
  Enter test package: com.consol.citrus.samples: : 
  Choose unit test framework testng: :

You have to specify the test name, author, description, package and the test framework. The plugin sucessfully generates the new test files for you. On the one hand a new Java class in src/citrus/java and a new XML test file in src/citrus/tests. The test is runnable right now. Try it and execute "mvn integration-test" once more. In the Citrus test results you will see that the new test was executed during integration-test phase along with the other existing test case. You can also run the test manually in your IDE with a TestNG plugin.

So now you are ready to use Citrus! Write test cases and add more logic to the test project. Have fun with it!