One of our Developers put together a nice Maven Integration document that will go out with our website refresh later this month.  Given the popularity of Maven, I thought I would share it before the site-refresh goes live!

Install Maven

This guide assumes you already have Java and Maven 2 installed. If you don’t have Maven, you can follow the installation instructions on the Maven website.

Open a command prompt with access to Maven so that you can follow the rest of the instructions in this guide.

Install LiquidTest into your local Maven repository

Maven projects cannot depend on JARs that are not Maven artifacts, which means that you can’t just drop LiquidTest into your classpath as you would with other build systems. Instead you’ll need to install LiquidTest into your local repository so that Maven can see it and your tests can depend on it.

Suppose you’ve obtained liquidtest-nodeps-1.0.17.jar and you’d like to tell Maven about it. Run the following command in the same directory as the JAR file:

$ mvn install:install-file \
      -Dfile=liquidtest-nodeps-1.0.17.jar \
      -DgroupId=local.jadeliquid.liquidtest \
      -DartifactId=liquidtest-nodeps \
      -Dversion=1.0.17 \
      -Dpackaging=jar

Package and install you LiquidTest license key

LiquidTest looks for its license key and other configuration parameters in a liquidtest.properties file on its classpath. There are a few ways to achieve this, but one of the simplest is to add your configuration to its own JAR and install it into Maven’s local repository.

Start by creating your liquidtest.properties file. It should contain at least the following line:

licenseKey=<INSERT YOUR LIQUIDTEST LICENSE KEY HERE>

You can add other LiquidTest configuration properties if you like.

Now, add your properties file to its own JAR archive with the following command:

$ jar -cvf liquidtest-properties.jar liquidtest.properties

The final step is to add this JAR to your repository as you did with LiquidTest itself:

$ mvn install:install-file \
      -Dfile=liquidtest-properties.jar \
      -DgroupId=local.jadeliquid.liquidtest \
      -DartifactId=liquidtest-properties \
      -Dversion=1.0-SNAPSHOT \
      -Dpackaging=jar

Create a Maven project

If you don’t already have a Maven project, you’ll need to create one by entering the following:

$ mvn archetype:create \
      -DgroupId=com.example.myproject \
      -DartifactId=my-project

This will create a skeleton project in the my-project/ directory. You can replace the group and artifact IDs with something more suitable for your project.

Add the FailSafe plugin for integration testing

The FailSafe plugin is used for integration testing in Maven. To use it, add the following to your project’s pom.xml:

<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>failsafe-maven-plugin</artifactId>
        <version>2.4.3-alpha-1</version>
        <executions>
          <execution>
            <id>integration-test</id>
            <goals>
              <goal>integration-test</goal>
            </goals>
          </execution>
          <execution>
            <id>verify</id>
            <goals>
              <goal>verify</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

Add LiquidTest dependencies

Add these dependencies to your project’s pom.xml so that the integration-test phase can use LiquidTest to run your tests:

<project>
  [...]
  <dependencies>
    [...]
    <dependency>
      <groupId>local.jadeliquid.liquidtest</groupId>
      <artifactId>liquidtest-nodeps</artifactId>
      <version>1.0.17</version>
      <scope>integration-test</scope>
    </dependency>
    <dependency>
      <groupId>local.jadeliquid.liquidtest</groupId>
      <artifactId>liquidtest-properties</artifactId>
      <version>1.0-SNAPSHOT</version>
      <scope>integration-test</scope>
    </dependency>
    [...]
  </dependencies>
  [...]
</project>

Update the JUnit dependency to JUnit 4

Maven’s default project configuration uses JUnit 3, which is no good if you’re using LiquidTest to generate JUnit 4 test files. Luckily this is easy to fix: find the JUnit <version>3.8.1</version> element in your pom.xml and replace the version number with a more suitable one. You can specify a particular version of JUnit with <version>4.3.1</version>, or request any version of JUnit 4 with <version>[4.0,)</version>.

You will also need to add JUnit to the integration-test lifecycle phase. To do this, replace <scope>test</scope> with <scope>test integration-test</scope>.

Here's how your project's <dependencies> configuration should appear after making these changes:

<project>
  [...]
  <dependencies>
    [...]
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>[4.0,)</version> <!-- version 4.0 or greater -->
      <scope>test integration-test</scope> <!-- needed by integration-test -->
    </dependency>
    [...]
  </dependencies>
  [...]

Enable support for Java 5 constructs

Maven uses Java 1.3 syntax by default, which is no good if you want to compile JUnit 4 tests with annotations. To remedy this, explicitly set the Java source and target versions in the compiler plugin's configuration using the following code:

<project>
  [...]
  <build>
    [...]
    <plugins>
      [...]
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.5</source> <!-- use Java 5 syntax -->
          <target>1.5</target> <!-- required for Java 5 syntax -->
        </configuration>
      </plugin>
      [...]
    </plugins>
    [...]
  </build>
  [...]
</project>

Add LiquidTest tests to your Maven tree

By default, FailSafe will look for test files using the pattern **/*IT.java. Create a test file with a name ending in IT and add it to your project's src/test/java/ tree at the appropriate package location.

For example, this test script would be placed at src/test/java/com/example/myproject/SampleIT.java:

package com.example.myproject;
 
import static org.junit.Assert.assertEquals;
 
import org.junit.Test;
import org.junit.runner.RunWith;
 
import com.jadeliquid.liquidtest.Browsers;
import com.jadeliquid.liquidtest.TestBrowser;
import com.jadeliquid.liquidtest.plugin.junit4.BrowserRunner;
 
@RunWith(BrowserRunner.class)
public class SampleIT
{
	public TestBrowser browser;
 
	@Test
	@Browsers("Firefox2.0")
	public void rfcHref()
	{
		browser.load("example.com");
		assertEquals("http://www.rfc-editor.org/rfc/rfc2606.txt",browser.getNodeAttribute("//*[text()='RFC \n  2606']", "href"));
	}
 
}

Run your tests in Maven

Now that everything is set up, you should be able to invoke Maven to run your LiquidTest integration tests:

$ cd my-project
$ mvn verify

Once Maven has downloaded any needed dependencies it will use LiquidTest to execute your tests. You should see summary results in your terminal, and detailed results should appear in the target/failsafe-reports/ directory in your Maven project tree.