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