Table of Contents

Excerpt

Table of Contents

absoluteUrl

...

true

Installing the

...

LivingDoc Maven Plugin

In order to install the GreenPepper Image Added Maven Plugin, it is necessary to add a plugin entry to your project's pom.xml.

Code Block

language	xml

<plugin>
	<groupId>com.greenpepper<<groupId>info.novatec.testit.livingdoc</groupId>
	<artifactId>greenpepper<artifactId>livingdoc-maven-plugin</artifactId>
	<version>4<version>1.0.0-SNAPSHOT<0</version>
	...
	<!-- further configuration here -->
</plugin>

For automatic downloads and upgrades, it is possible to add additional repositories to your project's pom.xml like this:

Code Block

language	xml

<repositories>
	<repository>
		<id>novatec</id>
		<url>http://nexus.novatec-gmbh.lan/content/groups/public</url>
		<snapshots>
			<enabled>true</enabled>
			<updatePolicy>never</updatePolicy>
		</snapshots>
		<releases>
			<enabled>true</enabled>
			<updatePolicy>never</updatePolicy>
		</releases>
</repositories>
 
<pluginRepositories>
	<id>novatec</id>
	<url>http://nexus.novatec-gmbh.lan/content/groups/public</url>
	<snapshots>
		<enabled>true</enabled>
		<updatePolicy>never</updatePolicy>
	</snapshots>
	<releases>
		<enabled>true</enabled>
		<updatePolicy>never</updatePolicy>
	</releases>
</pluginRepositories>

Configuring the GreenPepper Maven Plugin

Considering the default Maven Build Lifecycle, there are three phases in which the GreenPepper Maven Plugin is used.

During the Pre-Integration Test, the plugin is used to compile and copy the fixture classes of an application. By default, the compiled classes are copied to:
${project.build.directory}/fixture-test-classes/

During the next phase, the Integration Test, the plugin is used to execute the specifications of an application. As the result of an execution, it generates reports in plain HTML or XML file format which are by default stored in:
${basedir}/target/greenpepper-reports/

Finally, during the Post-Integration Test, the plugin creates the fixture jars of an application. These are typically generated in:
${basedir}/target/

In step one ("Installing the GreenPepper 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.

...

language	xml

...

Configuring the LivingDoc Maven Plugin

Within the default Maven Build Lifecycle, there are three phases using the Image Added Maven Plugin.

During the Pre-Integration Test, the plugin is used to compile and copy the fixture classes of an application. By default, the compiled classes are copied to:
${project.build.directory}/fixture-test-classes/

During the next phase, the Integration Test, the plugin is used to execute the specifications of an application. As the result of an execution, it generates reports in plain HTML or XML file format which are by default stored in:
${basedir}/target/livingdoc-reports/

Finally, during the Post-Integration Test, the plugin creates the fixture jars of an application. These are typically generated in:
${basedir}/target/

In step one ("Installing the Image Added 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.

Code Block

language	xml

<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>
	        <resource><repository>
		        <type><!-- fully qualified name of your <directory><!suit --resolver directoryclass, for a specific resource. Example: src/fixture/resourcesinstance: info.novatec.testit.livingdoc.repository.FileSystemRepository --></directory>type>
	            <excludes>
				<root><!-- root directory of the current repository. Example: ${basedir}/src/fixture/specs --></root>
		        <suites>
		       <exclude>**/*.java</exclude> 	<suite><!-- the suit's URI --></suite>
		        </excludes>suites>
	        </resource>repository>
	    </resources> 	    <repositories><repository>
	        <repository> 		        <type><!-- fully qualified name of your suittest resolver class, for instance: com.greenpepper.repository.FileSystemRepository --></type>
				<root><!-- root directory of the current repository. Example: ${basedir}/src/fixture/specs --></root>
		        <suites>
		            <tests>
	            	<suite><<test><!-- the suittest's URI --></suite>test>
		            </suites>tests>
	        </repository>
	    </repositories>
		<goalPrefix><!-- the prefix <repository>that 	will be associated with the plugin (optional, see below "Using the LivingDoc <type><!-- fully qualified name of your test resolver. Maven Plugin"), eg: livingdoc --></type>goalPrefix>
	            <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 GreenPepper Maven Plugin"), eg: greenpepper --></goalPrefix>
	</configuration>
</plugin>

Using the GreenPepper Maven Plugin

Executing specification fixtures

Generally, the goals of the GreenPepper 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 goalPrefix tag within the plugin configuration (see the code box above).

...

Compile fixture sources

Code Block
mvn greenpepper:compile

...

Copy resources to the destination directory

Code Block
mvn greenpepper:resources

...

Execute specifications

Code Block
mvn greenpepper:run

...

Create fixture jars

Code Block
mvn greenpepper:fixture-jar

Download specification files

Code Block
mvn greenpepper:freeze

...

Now that we know which goals exist for the GreenPepper Maven Plugin, let's have a closer look at each of them.

greenpepper:compile

...

Mojo attributes:

...

</configuration>
</plugin>

Using the LivingDoc Maven Plugin

Executing specification fixtures

Generally, the goals of the Image Added 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
Code Block
mvn livingdoc:compile
Copy resources to the destination directory
Code Block
mvn livingdoc:resources
Execute specifications
Code Block
mvn livingdoc:run
Create fixture jars
Code Block
mvn livingdoc:fixture-jar
Download specification files
Code Block
mvn livingdoc:freeze

Goals

Now that we know which goals exist for the Image Added Maven Plugin, let's have a closer look at each of them.

livingdoc:compile

Compiles the fixtures of an application.

Mojo attributes:

Requires a Maven 2.0 project (or higher) to execute
Dependency resolution of artifacts in scope required: test
Automatically executed within the Pre-Integration Test phase

Required parameters

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.

Optional parameters

The optional parameters are exactly the same as in the Maven Compiler Plugin.

Parameter details

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
- Type: java.io.File
- Expression (example): src/fixture/java
fixtureOutputDirectory: Output directory in which the compiled sources are placed.
- Type: java.io.File
- Expression: ${project.build.directory}/fixture-test-classes

livingdoc:resources

Copies resources for the main source code to the main output directory.

Mojo attributes:

Requires a Maven 2.0 project (or higher) to execute
Automatically executed within the Pre-Integration Test phase

Required parameters

Name	Type	Description
fixtureSourceDirectoryresources	File	Source directory containing the fixture classes to be compiledList	List of resources to be copied to the output directory.
fixtureOutputDirectory	File	Output directory in which the compiled sources resources are placedcopied to.

Optional parameters

The optional parameters are exactly the same as in the Maven Compiler Pluginresemble those for the Maven 2 resources plugin.

Parameter details

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 compiledresources: List of resources to be copied to the output directory.
- Type: java.ioutil.FileList
- Expression (example): src/fixture/java: none
fixtureOutputDirectory: Output directory in which the compiled sources are placedthe resources are copied to.
- Type: java.io.File
- Expression: ${project.build.directory}/fixture-test-classes

...

livingdoc:

...

run

Executes Image Added specifications.

Mojo attributes:

Requires a Maven 2.0 project (or higher) to execute
Dependency resolution of artifacts in scope required: test
Automatically executed within the Pre- Integration Test phase

Required parameters

Name	Type	Description
resourcesbasedir	ListFile	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.

Parameter details

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.
- Type: java.util.List
- Expression: none
fixtureOutputDirectory: Output directory the resources are copied to.
- Type: java.io.File
- Expression: ${project.build.directory}/fixture-test-classes

greenpepper:run

...

Mojo attributes:

Requires a Maven 2.0 project (or higher) to execute
Dependency resolution of artifacts in scope required: test
Automatically executed within the Integration Test phase

Required parameters

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	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.

Optional parameters

None.

Parameter details

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.
- Type: java.io.File
- Expression: ${basedir}
classesDirectory: Contains the generated classes of the project under test.

...

- Type: java.io.File
- Expression: ${project.build.outputDirectory}
fixtureOutputDirectory: Contains generated fixture classes of the project under test.

...

- Type: java.io.File
- Expression: ${project.build.directory}/fixture-test-classes

reportsDirectory: Output directory for generated reports.

...

- Type: java.io.File
- Expression: ${project.build.directory}/livingdoc-reports

livingdoc:fixture-jar

Builds the fixture jars.

Mojo attributes:

Requires a Maven 2.0 project (or higher) to execute
Dependency resolution of artifacts in scope required: test
Automatically executed within the Post-Integration Test phase

Required parameters

Name	Type	Description
fixtureOutputDirectory	File	Directory containing the compiled fixture classes.

Optional parameters

None.

Parameter details

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.

...

fixtureOutputDirectory: Directory containing the compiled fixture classes.
- Type: java.io.File
- Expression: ${project.build.outputDirectory}
fixtureOutputDirectory: Contains generated fixture classes of the project under test.
- Type: java.io.File
- Expression: ${project.build.directory}/fixture-test-classes
reportsDirectory: Output directory for generated reports.
- Type: java.io.File
- Expression: ${project.build.directory}/greenpepper-reports

greenpepper:fixture-jar

...

Mojo attributes:

Requires a Maven 2.0 project (or higher) to execute
Dependency resolution of artifacts in scope required: test
Automatically executed within the Post-Integration Test phase

Required parameters

...

- directory}/fixture-test-classes

livingdoc:freeze

Downloads specification files from a remote repository and stores them locally.

Mojo attributes:

Requires a Maven 2.0 project (or higher) to execute
Dependency resolution of artifacts in scope required: test
Not bound to any phase of the default Maven Build Lifecycle

Required parameters

Name	Type	Description
specsDirectory	File	Directory the specification files are downloaded to.
repositories	Repository	suite or test URI of specifications to download.

Optional parameters

None.

Parameter details

Note that the values of the expressions given below are merely default values, so therefore their use is not mandatory.

fixtureOutputDirectory: Directory containing the compiled fixture classesspecsDirectory: 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.
- Type: java.io.File
- Expression: ${project.build.directory}/fixture-test-classes

...

greenpepper:freeze

...

Mojo attributes:

Requires a Maven 2.0 project (or higher) to execute
Dependency resolution of artifacts in scope required: test
Not bound to any phase of the default Maven Build Lifecycle

Required parameters

Name	Type	Description
specsDirectory	File	Directory the specification files are downloaded to.
repositories	Repository	suite or test URI of specifications to download.

...

None.

Parameter details

Note that the values of the expressions given below are merely default values, so 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.
- Type: java.io.File
- Expression: ${basedir}/src/specs

Examples

GreenPepper Core pom.xml

The following code block shows an example of how your GreenPepper Core's pom.xml could look like.

...

language	xml

...

- basedir}/src/specs

Examples

LivingDoc Core pom.xml

The following code block shows an example of how your LivingDoc Core's pom.xml could look like.

Code Block

language	xml

 <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>com.greenpepper<<groupId>info.novatec.testit.livingdoc</groupId>
				<artifactId>greenpepper<artifactId>livingdoc-maven-plugin</artifactId>
				<version>${greenpepperlivingdoc.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/greenpepperlivingdoc-reports</reportsDirectory>
					<reportsType>xml</reportsType>
					<systemUnderDevelopment>com.greenpepper<systemUnderDevelopment>info.novatec.testit.livingdoc.systemunderdevelopment.GreenPepperSystemUnderDevelopment<LivingDocSystemUnderDevelopment</systemUnderDevelopment>
					<resources>
						<resource>
							<directory>src/fixture/resources</directory>
						</resource>
					</resources>
					<repositories>
						<repository>
							<name>Seeds</name>
							<type>com<type>info.greenpeppernovatec.testit.livingdoc.repository.FileSystemRepository</type>
							<root>${basedir}/src/fixture/specs</root>
							<suites>
								<suite>Seeds</suite>
							</suites>
						</repository>
					</repositories>
					<goalPrefix>greenpepper<<goalPrefix>livingdoc</goalPrefix>			
				</configuration>
				<executions>
					<execution>
						<id>greenpepper<<id>livingdoc</id>
						<goals>
							<goal>compile</goal>
							<goal>resources</goal>
							<goal>fixture-jar</goal>
							<goal>run</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
</project>

File System Repository

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.

Code Block

language	xml

	<repositories>	
		<repository>
    		<name>Demo</name>
        	<type>com.greenpepper<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>com.greenpepper<type>info.novatec.testit.livingdoc.repository.FileSystemRepository</type>
           	<root>${basedir}/src/fixture/specs</root>
            <suites>
            	<suite>DemoPhoneBook</suite>
           	</suites>
       	</repository>
	</repositories>

Command line options

...

Skip execution of the GreenPepper tests

Code Block
-Dmaven.greenpepper.test.skip=true

...

Change the report type (default is HTML)

Code Block
-Dmaven.greenpepper.reports.type=xml

...

Stop execution on first failed test

Code Block
-Dmaven.greenpepper.test.stop=true

...

Activate debug mode

Code Block
-Dmaven.greenpepper.debug=true

Ignore failed tests during execution (won't cause Maven to stop execution with an error message)

Code Block
-Dmaven.greenpepper.test.failure.ignore=true

Sonar

Sonar, also known as SonarQube, is an open platform that aims at managing the quality of your code. The Sonar GreenPepper Plugin feeds Sonar with the test reports provided by the GreenPepper Maven Plugin.

Image Removed

The easiest way to produce a Sonar report using GreenPepper test reports is the following:

Code Block
mvn clean integration-test sonar:sonar

The integration-test will trigger the following goals:

greenpepper:compile
greenpepper:resources
greenpepper:fixture-jar
greenpepper:run

Please note that in order to use the Sonar GreenPepper Plugin, the GreenPepper reports need to have XML file format which can be achieved by doing either of the following:

...

Add the reportsType tag to the plugin configuration in your project's pom.xml

Code Block
<reportsType>xml</reportsType>

...


       	</repository>
	</repositories>

Command line options

Skip execution of the LivingDoc tests

Code Block
-Dmaven.greenpepperlivingdoc.reportstest.typeskip=xml

Maven Runner

Configuring a System Under Test can be exhausting if you have a lot of library dependencies. In order to make the configuration process a little easier, the Maven Runner uses your existing pom.xml to automatically
resolve dependencies needed for the execution of specifications, whereby only the dependencies tag is read. Artifacts found will be resolved and added to the classpath of the runner. The project's artifact itself will
also be added to the classpath.

...

true
Change the report type (default is HTML)
Code Block
-Dmaven.livingdoc.reports.type=xml
Stop execution on first failed test
Code Block
-Dmaven.livingdoc.test.stop=true
Activate debug mode
Code Block
-Dmaven.livingdoc.debug=true
Ignore failed tests during execution (won't cause Maven to stop execution with an error message)
Code Block
-Dmaven.livingdoc.test.failure.ignore=true

Version	Old Version 9	New Version Current
Changes made by	Former user	AnisB
Saved on	Feb 19, 2015	Dec 28, 2015

Content Comparison

Versions Compared

Key

Installing the

LivingDoc Maven Plugin

Configuring the GreenPepper Maven Plugin

Configuring the LivingDoc Maven Plugin

Using the GreenPepper Maven Plugin

Executing specification fixtures

greenpepper:compile

Using the LivingDoc Maven Plugin

Executing specification fixtures

Goals

livingdoc:compile

Required parameters

Optional parameters

Parameter details

livingdoc:resources

Required parameters

Optional parameters

Parameter details

livingdoc:

run

Required parameters

Parameter details

greenpepper:run

Required parameters

Optional parameters

Parameter details

livingdoc:fixture-jar

Required parameters

Optional parameters

Parameter details

greenpepper:fixture-jar

Required parameters

livingdoc:freeze

Required parameters

Optional parameters

Parameter details

greenpepper:freeze

Required parameters

Parameter details

Examples

GreenPepper Core pom.xml

Examples

LivingDoc Core pom.xml

File System Repository

Command line options

Sonar

Command line options

Maven Runner