Configuring different output directories with Serenity BDD and Maven

Serenity BDD is an open source automated testing library geared towards writing high quality, highly maintainable automated acceptance testing, and using these acceptance tests to produce world-class living documentation. In this article, we look at how to get Serenity to generate its reports in different directories, in both simple and multi-module Maven projects.

By default, Serenity generates its reports in the target/site/serenity directory. This follows Maven conventions and works for most projects. However, sometimes teams prefer to place the reports in a different directory. In this article, we will look at how to do this.

Single-module maven projects

The simplest way to define a different output directory is to set the serenity.outputDirectoryproperty in your serenity.properties file (which lives in the project directory) or in the serenity.conf file.

A simple serenity.properties file would look like this:

serenity.project.name = "My Special Project"
serenity.test.root =  "net.serenitybdd.demos.todos.features"
serenity.outputDirectory = target/site/reports

An example of an equivalent serenity.conf file is shown here:

serenity {
  project.name = "My Special Project"
  test.root = "net.serenitybdd.demos.todos.features"
  outputDirectory  = target/site/reports
}

This will configure Serenity to write reports to the target/site/reports directory rather than to the usual target/site/serenity directory. The test.root property is also important if you are writing your tests in JUnit - this tells Serenity what package root to use as a starting point for the requirements reporting. The package tree underneath this package will become the requirements tree in the reports.

If you use the serenity.conf file, you need to do two things to make sure the reporting process finds it correctly. First of all, make sure it is in the src/main/resource folder, and not in src/test/resources. Secondly, you need to add a dependency to your project in the serenity-maven-plugin (because Maven plugins don't use the same dependencies as your main project, and in particular don't include a dependency on your project). You can do this as shown here:

<plugin>
    <groupId>net.serenity-bdd.maven.plugins</groupId>
    <artifactId>serenity-maven-plugin</artifactId>
    <configuration>
        <tags>${tags}</tags>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>net.serenitybdd.demos.todos</groupId>
            <artifactId>myproject</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <id>serenity-reports</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

This configuration will use the serenity.conf file stored in the src/main/resources folder of the todo-app project. The <executions> section ensures that the Serenity reports are generated after the tests have finished.

Multi-module Maven projects

Some projects use a multi-module structure, where one module is responsible for running the acceptance tests and generating the reports, and other modules are responsible for other areas. For example, suppose you have a multi-module Maven project that looks like this, where your Serenity tests live in the acceptance module:

+ myproject
  pom.xml
    + domain
      pom.xml
      ...
    + acceptance
      pom.xml  
      + src
         + main
           + resources
              serenity.conf  
      ...
  serenity.properties    

You can configure the reports either in the serenity.conf file in the src/main/resourcesfolder of the acceptance module, or by placing a serenity.properties file at the root directory.

In both cases, report directories are resolved relative to the module sub-directory, not the parent directory. So if you wanted to generate your reports in a folder called 'serenity-reports' directly underneath the parent directory, you would need to configure your serenity.conf file like this:

serenity {
  project.name = "My Special Project"
  test.root = "net.serenitybdd.demos.todos.features"
  outputDirectory  = ../serenity-reports
}

Just like for the single-module project, you need to

The tricky thing with configuring multi-module Maven projects is that the aggregation phase (where the bulk of the HTML reports are generated) does not have access to all of the classpath resources as when you run the tests. For example, if you add configuration details in the src/test/resources/serenity.conf file, these will not be available during the aggregation phase. So if you configure

<plugin>
    <groupId>net.serenity-bdd.maven.plugins</groupId>
    <artifactId>serenity-maven-plugin</artifactId>
    <configuration>
        <tags>${tags}</tags>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>net.serenitybdd.demos.todos</groupId>
            <artifactId>acceptance</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <id>serenity-reports</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

You can now run the acceptance tests in the acceptance module from the root directory (for example, if you are configuring the build as part of a Jenkins build job) like this:

$ mvn clean verify -pl acceptance -am

This will run the tests in the acceptance module, after having built any modules that the acceptance module depends on, and generate the reports in the folder specified in the serenity.conf or serenity.properties file.