Executing a Specification in Java

Introduction

This page describes how to execute a specification using the command line interface that comes with GreenPepper.

Features

 GreenPepper provides a command line interface to execute specifications captured in HTML files. The command line interface has the following features:

• Execution of a single specification file
• Execution of a suite of specifications stored in a directory tree

Running the command line application

Running  GreenPepper requires Java JDK 5.0.

The following libraries are required on the classpath to run the command line interface:

• greenpepper-core-2.1.jar
• your fixture code
• your system under test
• all the external libraries your system under test depends upon

The main class for the command line interface is com.greenpepper.runner.Main.

java -cp greenpepper-core-2.1.jar;fixtures.jar;system-under-test.jar;external-dependency.jar com.greenpepper.runner.Main <arguments>

java -cp greenpepper-core-2.1.jar:fixtures.jar:system-under-test.jar:external-dependency.jar com.greenpepper.runner.Main <arguments>

Arguments

Invoking the command line interface with the --help option brings up the usual help message:

Usage: greenpepper [options] input [ouput]
Run the input specification and produce a report in output file or in directory specified by -o

Options:
    --lazy                    Execute document in lazy mode
-l, --locale LANG             Set application language (en, fr, ...)
-f, --sud CLASS;ARGS          Use CLASS as the system under development and instantiate it with ARGS
-o DIRECTORY                  Produce reports in DIRECTORY (defaults to current directory)
-r CLASS;ARGS                 Use CLASS as the document repository and instantiate it with ARGS (defaults to com.greenpepper.repository.FileSystemRepository)
    --selector CLASS          Use CLASS as the interpreter selector (defaults to com.greenpepper.document.GreenPepperInterpreterSelector)
-s, --suite                   Run a suite rather than a single test (output must refer to a directory)
-t SECTIONS                   Filter input specification to only execute SECTIONS (comma separated list of sections)
    --xml                     Generate XML report (defaults to plain)
    --help                    Display this help and exit
    --version                 Output version information and exit
    --debug                   Enable debug mode

Default options

When no option is given,  GreenPepper defaults to the following rules:

• Input is a single specification, not a suite
• If output is not specified, reports are produced in the current directory
• Report is in plain format
• The operating system locale is used
• The input specification is not filtered
• The specification file must be located on the file system
• Fixtures are created using the default built-in mechanism
• Tables use  GreenPepper formalism
• Lazy mode is disabled
• Debug mode is disabled

Any of the rules above can be overridden using command line switches.

Running with the default options

By default  GreenPepper executes the specification file given as an input and produces a report in the current directory. The name of the report is constructed from the name of the specification.

The specification file has to be an HTML file (with the .html extension) accessible on the file system.  GreenPepper will execute the specification and produce both:

• an execution summary displayed in the terminal window
• a report file, which contains the executed specification annotated with test results

Here's an example:

java -cp ... com.greenpepper.runner.Main example.html

Running example.html
14 example(s): 9 right, 3 wrong, 1 ignored, 1 exception(s) <<< FAILURE!

Specifying an output directory -o

The destination directory for report files can be specified using the -o option.

Alternatively, the output argument can be used to specify the absolute path of the report file.

java -cp ... com.greenpepper.runner.Main -o reports example.html

Running example.html
14 test(s): 9 right, 3 wrong, 1 ignored, 1 exception(s)

Executing a set of specification files (-s, --suite)

 GreenPepper can execute all specification files found in a given directory (recursively) and produce result files in the specified output directory. The suite mode is activated using the -s option.

If the output directory does not exist,  GreenPepper will try to create it. Input files need to be in HTML form and have the .html extension.

java -cp ... com.greenpepper.runner.Main -s -o reports specs

home
  |
  |____ myuser
           |
           |____ workspace
                     |
                     |____ myproject
                               |
                               |____ specs
                                       |
                                       |____ Authentication
                                       |           | 
                                       |           |____ Login.html
                                       | 
                                       |
                                       |____ Authorization
                                                   |
                                                   |____ AccessControl.html                

home
  |
  |____ myuser
           |
           |____ workspace
                     |
                     |____ myproject
                               |
                               |____ reports
                                       |
                                       |____ Authentication.Login_html.html
                                       |
                                       |____ Authorization.AccessControl_html.html

Changing the default Locale (--locale, -l)

It is possible to change the current locale with the --locale or -l option, followed by a valid java 2 letters locale code.

java -cp ... com.greenpepper.runner.Main --locale fr example.html result.html

Filtering out parts of the specification (-t)

When the specification file contains sections identified by tags, it is possible to execute only those parts of the specification that are relevant using the -t option. The -t switch has to be followed by a comma separated list of tags to consider for execution.

java -cp ... com.greenpepper.runner.Main -t authentication,authorization example.html result.html

Producing XML reports (--xml)

It is possible to produce the report file in XML format using the --xml option. The XML format produces an output file that contains both execution statistics and the annotated HTML specification.

java -cp ... com.greenpepper.runner.Main --xml example.html result.html

Using a custom specification repository (-r)

The default is for  GreenPepper to look for specifications on the file system. When you want to use a different specification repository, use the -r option followed by the fully qualified class name of the Repository class and a semi-colon separated list of constructor parameters for that class.

java -cp ... com.greenpepper.runner.Main -r com.greenpepper.runner.repository.VFSRepository example.html result.html

Specifying a custom system under development (--sud)

 GreenPepper will use the DefaultSystemUnderDevelopment unless told otherwise. To specify a different system under development class, use the --sud option followed by the fully qualified class name and a semi-colon separated list of constructor parameters for that class.

java -cp ... com.greenpepper.runner.Main --sud com.greenpepper.systemunderdevelopment.SpringSystemUnderDevelopment;conf/application-context.xml example.html result.html

Changing table formalism (e.g. for Fit compliance)

It is possible to change  GreenPepper table formalism by specifying an InterpreterSelector class with the --selector option. By default  GreenPepper will use its own formalism.

java -cp ... com.greenpepper.runner.Main --selector com.greenpepper.fit.FitInterpreterSelector example.html result.html

Setting lazy mode (--lazy)

Enabling lazy mode changes  GreenPepper behaviour :

• Lazy mode : On a greenpepperized document, all tables that are contained in documents will be skipped until you specify a [greenpepper-example] macro for the table or group of tables you want to be not skipped.
• Not lazy mode (default) : this mode is an Eager mode, it means that all tables will be interpreted.

java -cp ... com.greenpepper.runner.Main --lazy

Setting debug mode (--debug)

Enabling debug mode allows you to have a full view of exceptions stack trace in your  GreenPepper specifications documents. Note that in the normal mode the stack trace are limited.

java -cp ... com.greenpepper.runner.Main --debug