Command line Configuration

Owned by Sebastian Letzel
Last updated: Dec 05, 2015 by AnisB
6 min read


Arguments

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

Usage: livingdoc [options] input [output]
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 														
							  info.novatec.testit.livingdoc.repository.FileSystemRepository)
	--selector CLASS          Use CLASS as the interpreter selector (defaults to info.novatec.testit.livingdoc.document.LivingDocInterpreterSelector)
-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
    --stop                    Stop the execution of the specification on the first failure

Default options

When no option is given,  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  formalism
  • Lazy mode is disabled
  • Debug mode is disabled
  • Will not stop the execution on first failure

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

Running with the default options

By default  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.  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:

Running with default options

Executing the command:

java -cp ... info.novatec.testit.livingdoc.runner.Main example.html

might display the following in the terminal window:

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.

 

Specifying an output directory

Executing the command:

java -cp ... info.novatec.testit.livingdoc.runner.Main -o reports example.html

might display the following in the terminal window:

Running example.html
14 test(s): 9 right, 3 wrong, 1 ignored, 1 exception(s)
and produce a report file named example.html in the reports directory.

 

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

 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,  will try to create it. Input files need to be in HTML form and have the .html extension.

 

Running a suite of specifications

To execute all specification files found in the /home/myuser/workspace/myprojects/specs directory and produce output in the /home/myuser/workspace/myprojects/reports directory, use the following command from the /home/myuser/workspace/myprojects directory:

java -cp ... info.novatec.testit.livingdoc.runner.Main -s -o reports specs

If the specs directory looks like this:

home 
 | 
 |__ myuser 
	 | 
	 |__ workspace 
		| 
		|__ myproject 
			| 
			|__ specs 
			  | 
			  |__ Authentication 
			  |	  | 
			  |	  | __ Login.html 
			  | 
			  |__ Authorization 
				  | 
				  |__ AccessControl.html
The reports directory would then contain the following files:

 

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.

 

Changing the locale

Running the application in french is done like this:

java -cp ... info.novatec.testit.livingdoc.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.

 

Filtering the specification

We can execute only the sections of the specification marked with the authentication and authorization tags like this:

java -cp ... info.novatec.testit.livingdoc.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.

Producing XML reports

We can execute only the sections of the specification marked with the authentication and authorization tags like this:

java -cp ... info.novatec.testit.livingdoc.runner.Main --xml example.html result.html

 

Using a custom specification repository (-r)

The default is for  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.

 

Changing the specification repository

To use the VFSRepository issue the command:

java -cp ... info.novatec.testit.livingdoc.runner.Main -r info.novatec.testit.livingdoc.runner.repository.VFSRepository example.html result.html

 

Specifying a custom system under development (--sud)

 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.

Changing the system under development

To use the SpringSystemUnderDevelopment with the application-context.xml file located in the conf directory, use the command:

java -cp ... info.novatec.testit.livingdoc.runner.Main --sud info.novatec.testit.livingdoc.systemunderdevelopment.SpringSystemUnderDevelopment;conf/application-context.xml example.html result.html

 

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

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

 

Enabling Fit compliance mode

 

As an example, to enable Fit compliance, use the class info.novatec.testit.livingdoc.fit.FitInterpreterSelector available in the livingdoc-extensions-fit.jar. This will cause  to use Fit formalism for tables and support Fit basic interpreters:

java -cp livingdoc-extensions-fit.jar;... info.novatec.testit.livingdoc.runner.Main --selector info.novatec.testit.livingdoc.fit.FitInterpreterSelector example.html result.html

Setting lazy mode (--lazy)

Enabling lazy mode changes  behavior :

  • Lazy mode : On a LivingDoc enabled document, all tables that are contained in documents will be skipped until you specify a livingdoc\-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.
Enabling lazy mode

To enable lazy mode, use the command:

java -cp ... info.novatec.testit.livingdoc.runner.Main --lazy

Setting debug mode (--debug)

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

Enabling debug mode

To enable debug mode, use the command:

java -cp ... info.novatec.testit.livingdoc.runner.Main --debug

Stop on first failure (--stop)

Stop on first failure

To stop the execution of a specification when a failure is detected, use the command:

java -cp ... info.novatec.testit.livingdoc.runner.Main --stop