Component test headless mode reference

Headless execution allows you to automate the component test runs from a command line or Ant script without user input and without the product graphical user interface.

Purpose

The command line launches a "headless" workbench (with no user interface for the development environment) and runs component test launch configurations that are found in a specified workspace.
Note: In some environments the length of a command line might be limited. If you encounter errors due to a truncated command line, try replacing parts of the command with variables.

The basic command line syntax to run a component test is as follows:

<Eclipse directory>/jre/bin/java <virtual machine options><mandatory parameters> <optional parameters>

Mandatory parameters

There are three categories of mandatory parameters:
  • Product VM
  • Eclipse
  • Command line
In some environments, you might need to append additional parameters to these commands, depending on your operating system configuration. The parameters for launching the workbench in your environment are located in the system configuration details under System properties in Help > About > Configuration Details. <virtual machine options> are located under the eclipse.vmargs property and the main Eclipse options are located under the eclipse.commands property.
Product VM parameters
-Xj9
Launches the application for command-line mode, along with other parameters listed under Help > About > Configuration Details.
-cp <classpath>/startup.jar org.eclipse.core.launcher.Main
Launches eclipse in headless mode with the specified class path. Use double quotes when the path contains spaces and double backslashes (\\) instead of the backslash character. Here is an example: "C:\\Program Files\\IBM\\Rational\\".
-Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=org.eclipse.emf.ecore.impl.EPackageRegistryImpl
Specifies definitions that are required by some workbench components.
Eclipse parameters
-plugincustomization <plugin customization path>
Replaces the customization path for the plug-in with the path of the pluginCustomization.ini file for your plug-in.
-application com.ibm.r2a.command.line.mode.CommandLineModeApplication
Specifies the application used for component test and profiling.
-data <workspace>
Specifies the location of the workspace where the launch configurations are located. Use double quotes when the path contains spaces, and double backslashes (\\) instead of the backslash character. Here is an example: "C:\\Program Files\\IBM\\Rational\\".
-os linux
Specifies Linux as the operating system.
-ws gtk
A parameter required by some workbench components. This option is mandatory only for Linux.
Command line parameters
-onlyClient ComponentTest
Specifies that the current command line applies only the component feature. If this parameter is omitted, other features might be activated, resulting in poor performance and results unrelated to component tests.
-reportDirectory directory_path
Specifies the directory where report files are to be produced. Use double quotes when the path contains spaces and double backslashes (\\) instead of the backslash character. Here is an example: "C:\\Program Files\\IBM\\Rational\\".

Optional parameters

-profile
Runs all launch configurations in the workspace with component test and profiling engaged.
-persistKind html|xml
Specifies to produce either an HTML or XML report alone. By default, both reports are generated.
-multifile
Produces one report file for each launch configuration. This option applies only to HTML reports. By default, a single report file is produced for all launch configurations invoked from a command line.
-fullreport
Produces a complete report containing all passed, failed, inconclusive, and error test verdicts. By default, only non-passed results appear in the report.
-launch config1 config2 ...
Launches the specified launch configurations. By default, all component test launch configurations contained in the specified workspace are launched. If the specified launch configurations are not for component tests, they are not launched, even if the -profile option is engaged. Use quotes when configuration names contain spaces, for example "My Configuration".
-timeStampMode
Produces results in an intermediate directory named with the timestamp of the test (in the form YYYYMMDD_HHMMSS) in the report directory. Use this option if you plan to run the same launch configuration more than once.

Sample

This sample Ant script for Windows silently runs all the launch configurations that are located in D:\workspace and produces the results in a directory named batch_report located in the workspace:
<?xml version="1.0" encoding="UTF-8">
<project name="MyTestProject" default="ComponentTestHeadless" >

	<target name="ComponentTestHeadless">

		<property name="eclipse_dir" value="D:\\eclipse"/>
		<property name="workspace_dir" value="D:\\workspace"/>
		<property name="options" value=" -onlyClient ComponentTest -reportDirectory ${workspace_dir}\\batch_report -fullreport -timeStampMode"/>

		<exec executable="${eclipse_dir}/jre/bin/java" dir="${eclipse_dir}" vmlauncher="false">
			<arg line="-Xj9 -Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=org.eclipse.emf.ecore.impl.EPackageRegistryImpl -cp ${eclipse_dir}/startup.jar org.eclipse.core.launcher.Main -application com.ibm.r2a.command.line.mode.CommandLineModeApplication -data ${workspace_dir} ${options}" />
		</exec>
	</target>

</project>
Related concepts
Headless execution of component tests
Related tasks
Running component tests from a command line
Running component tests from an Ant script
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.