Table of Contents
In order to install the Maven Plugin, it is necessary to add a plugin entry to your project's pom.xml.
<plugin> <groupId>info.novatec.testit.livingdoc</groupId> <artifactId>livingdoc-maven-plugin</artifactId> <version>1.0.0</version> ... <!-- further configuration here --> </plugin> |
Within the default Maven Build Lifecycle, there are three phases using the Maven Plugin.
In step one ("Installing the Maven Plugin") we had a look on a short block of code where it said "further configuration here". Below you find an example of how said configuration could look like.
<plugin> <groupId>info.novatec.testit.livingdoc</groupId> <artifactId>livingdoc-maven-plugin</artifactId> <version><!-- your version of the LivingDoc Maven Plugin --></version> <configuration> <source><!-- your source version --></source> <target><!-- your target version --></target> <fixtureSourceDirectory><!-- source directory of your fixtures, for example: src/fixture/java --></fixtureSourceDirectory> <fixtureOutputDirectory><!-- output directory of the compiled fixture classes, for example: target/fixture-test-classes --></fixtureOutputDirectory> <specsDirectory><!-- destination for downloaded specification files, for example: src/sprecs--></specsDirectory> <reportsDirectory><!-- destination for generated HTML reports, for example: target/livingdoc-reports</reportsDirectory> <reportsType><!-- the file format of your reports (XML or HTML, default is HTML) --></reportsType> <resources> <resource> <directory><! -- directory for a specific resource. Example: src/fixture/resources--></directory> <excludes> <exclude>**/*.java</exclude> </excludes> </resource> </resources> <repositories> <repository> <type><!-- fully qualified name of your suit resolver class, for instance: info.novatec.testit.livingdoc.repository.FileSystemRepository --></type> <root><!-- root directory of the current repository. Example: ${basedir}/src/fixture/specs --></root> <suites> <suite><!-- the suit's URI --></suite> </suites> </repository> <repository> <type><!-- fully qualified name of your test resolver. --></type> <tests> <test><!-- the test's URI --></test> </tests> </repository> </repositories> <goalPrefix><!-- the prefix that will be associated with the plugin (optional, see below "Using the LivingDoc Maven Plugin"), eg: livingdoc --></goalPrefix> </configuration> </plugin> |
Generally, the goals of the Maven Plugin correspond to the phases of the default Maven Build Lifecycle (with exception of the Freeze goal). Therefore, in order to interact with our fixture sources, we only have to tell Maven until which goal it should run.
NOTE: In order to use a prefix as we do below, it might be necessary to define the goal Prefix tag within the plugin configuration (see the code box above).
Compile fixture sources
mvn livingdoc:compile |
Copy resources to the destination directory
mvn livingdoc:resources |
Execute specifications
mvn livingdoc:run |
Create fixture jars
mvn livingdoc:fixture-jar |
Download specification files
mvn livingdoc:freeze |
Now that we know which goals exist for the Maven Plugin, let's have a closer look at each of them.
Compiles the fixtures of an application.
Mojo attributes:
Name | Type | Description |
---|---|---|
fixtureSourceDirectory | File | Source directory containing the fixture classes to be compiled. |
fixtureOutputDirectory | File | Output directory in which the compiled sources are placed. |
The optional parameters are exactly the same as in the Maven Compiler Plugin.
Note that the values of the expressions given below are merely default values, so their use is not mandatory.
fixtureSourceDirectory: Source directory containing the fixture classes to be compiled
Expression (example): src/fixture/java
fixtureOutputDirectory: Output directory in which the compiled sources are placed.
Copies resources for the main source code to the main output directory.
Mojo attributes:
Name | Type | Description |
---|---|---|
resources | List | List of resources to be copied to the output directory. |
fixtureOutputDirectory | File | Output directory the resources are copied to. |
The optional parameters resemble those for the Maven 2 resources plugin.
Note that the values of the expressions given below are merely default values, so their use is not mandatory.
resources: List of resources to be copied to the output directory.
fixtureOutputDirectory: Output directory the resources are copied to.
Executes specifications.
Mojo attributes:
Name | Type | Description |
---|---|---|
basedir | File | Base directory of the project under test (can be obtained in the unit tests using System.getProperty("basedir")) |
classesDirectory | File | Contains the generated classes of the project under test. |
fixtureOutputDirectory | File | Contains generated fixture classes of the project under test. |
repositories | Repository | suite or test URI of specifications to test. |
reportsDirectory | File | Output directory for generated reports. |
stopOnFirstFailure | Boolean | Stops the specification's execution on the first failure if set to true. |
testFailureIgnore | Boolean | Ignores test failures if set to true. Although this is not recommended, there are several occasions where it might come in handy. |
None.
Note that the values of the expressions given below are merely default values, so their use is not mandatory.
basedir: Base directory of the project under test.
classesDirectory: Contains the generated classes of the project under test.
Expression: ${project.build.outputDirectory}
Builds the fixture jars.
Mojo attributes:
Name | Type | Description |
---|---|---|
fixtureOutputDirectory | File | Directory containing the compiled fixture classes. |
None.
Note that the values of the expressions given below are merely default values, so their use is not mandatory.
fixtureOutputDirectory: Directory containing the compiled fixture classes.
Downloads specification files from a remote repository and stores them locally.
Mojo attributes:
Name | Type | Description |
---|---|---|
specsDirectory | File | Directory the specification files are downloaded to. |
repositories | Repository | suite or test URI of specifications to download. |
None.
Note that the values of the expressions given below are merely default values, therefore their use is not mandatory.
specsDirectory: Destination directory for specifications to be downloaded. Specifications are stored in a subdirectory named after the given repository and optionally in a subdirectory named after the suite.
The following code block shows an example of how your LivingDoc Core's pom.xml could look like.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <artifactId>livingdoc-core</artifactId> <packaging>jar</packaging> <name>${project.subproject.title}</name> <parent> <groupId>info.novatec.testit.livingdoc</groupId> <artifactId>livingdoc</artifactId> <version>1.0.1</version> </parent> <build> <resources> <resource> <directory>src/main/filter</directory> <filtering>true</filtering> <targetPath>../filtered-sources</targetPath> <includes> <include>**/*.java</include> </includes> </resource> <resource> <directory>src/main/resources</directory> <filtering>false</filtering> </resource> </resources> <plugins> <plugin> <groupId>info.novatec.testit.livingdoc</groupId> <artifactId>livingdoc-maven-plugin</artifactId> <version>${livingdoc.maven.plugin.version}</version> <configuration> <source>1.7</source> <target>1.7</target> <fixtureSourceDirectory>src/fixture/java</fixtureSourceDirectory> <fixtureOutputDirectory>target/fixture-test-classes</fixtureOutputDirectory> <specsDirectory>src/specs</specsDirectory> <reportsDirectory>target/livingdoc-reports</reportsDirectory> <reportsType>xml</reportsType> <systemUnderDevelopment>info.novatec.testit.livingdoc.systemunderdevelopment.LivingDocSystemUnderDevelopment</systemUnderDevelopment> <resources> <resource> <directory>src/fixture/resources</directory> </resource> </resources> <repositories> <repository> <name>Seeds</name> <type>info.novatec.testit.livingdoc.repository.FileSystemRepository</type> <root>${basedir}/src/fixture/specs</root> <suites> <suite>Seeds</suite> </suites> </repository> </repositories> <goalPrefix>livingdoc</goalPrefix> </configuration> <executions> <execution> <id>livingdoc</id> <goals> <goal>compile</goal> <goal>resources</goal> <goal>fixture-jar</goal> <goal>run</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project> |
In the following example, the specifications will be saved in ${basedir}/src/fixture/specs, as specified in the root element. The first repository will save its specifications in a subdirectory called Demo, the second one in a subdirectory called DemoPhoneBook.
<repositories> <repository> <name>Demo</name> <type>info.novatec.testit.livingdoc.repository.FileSystemRepository</type> <root>${basedir}/src/fixture/specs</root> <suites> <suite>Demo</suite> </suites> </repository> <repository> <name>DemoPhoneBook</name> <type>info.novatec.testit.livingdoc.repository.FileSystemRepository</type> <root>${basedir}/src/fixture/specs</root> <suites> <suite>DemoPhoneBook</suite> </suites> </repository> </repositories> |
Skip execution of the LivingDoc tests
-Dmaven.livingdoc.test.skip=true |
Change the report type (default is HTML)
-Dmaven.livingdoc.reports.type=xml |
Stop execution on first failed test
-Dmaven.livingdoc.test.stop=true |
Activate debug mode
-Dmaven.livingdoc.debug=true |
Ignore failed tests during execution (won't cause Maven to stop execution with an error message)
-Dmaven.livingdoc.test.failure.ignore=true |