# Q7 Runner

This document describes Q7 Runner of version 1.3.x. If you are using older version, please refer to Q7 Runner 1.2.x.

# Usage and command-line options

The base command line for Q7 runner looks like this:

## Basic command-line options

The table below summarizes information about arguments, arguments are more or less sorted by decreasing importance

Arg name

Description

Example

Required?

Since
Q7 version
clientIdAccount or organization name at http://q7.xored.com.myusernameYes1.3

clientSecret

Randomly generated secret string from http://q7.xored.com/settings/balance

05fe7462c607c33229e72d402505601016a7d0ea

Yes

1.3
organizationOptional organization name to charge execution from. A specified clientId must be a member of given organizationxoredNo1.3.5

aut

Platform-specific path to application under test

"C:\Downloads\eclipse"

Yes

1.0

import

Semicolon-separated list of project folders with Q7 tests or resources to link. Q7 Runner will perform a recursive search of Q7 projects in each of given folders.

"C:\work\q7project1;c:\work\q7project2", "C:\singleQ7Project"

Yes

1.0

autWsPrefix

File prefix for application-under-test's workspace. The workspace prefix given will be suffixed with incrementing restart index to make sure
no data is lost in case of application-under-test restart, hang or crash.

"C:\work\aut-workspace-"

Yes

1.0

junitReport

File path to save JUnit report with test exec results

"C:\work\q7results.xml"

No

1.0

htmlReport

File path to save HTML report with test exec results

"C:\work\q7results.html"

No

1.0

autConsolePrefix

File prefix for application-under-test process output. It will be appended with incrementing restart index for the same reason as -autWsPrefix arg.

C:\work\aut-console-output-

No

1.0

testOptions

Semicolon-separated list of Q7 Runtime options (see description below)

"testExecTimeout=600"

No

1.0

autArgs

List of arguments for application-under-test separated by semicolon.

-showsplash;org.eclipse.platform

No

1.0

autVMArgs

List of arguments for application-under-test's JVM separated by semicolon.

-Xmx1024m;-XX:MaxPermSize=512m

No

1.0
suitesList of Test suite names separated by semicolon. If this argument is set, Q7 runner executes only test cases from given suites (otherwise it executes all tests from given projects).WindowsOnlyTestsNo1.2.0

skipTags

Semicolon-separated list of tags. Test cases containing any of listed tags are not be executed. The default value is 'skipExecution'.skipExecutionNo1.1

autVM

Java VM to use with application-under-test. By default it is set to the same Java VM which is used for Q7 Runner launching

"C:\Program Files\Java\jre_1.6.0_25"

No

1.0

timeout

Overall execution timeout in seconds, default value is 18000 (5 hours)

3600

No

1.0

connectTimeout

application-under-test connection timeout in seconds, default value is 300 (5 mins). Very unlikely requires to be increased

7200

No

1.0
reportGenerate report with custom reporting renderer. "id;path" format should be used to specify report renderer id and path to export. No1.2.1
noSecurityOverrideIf specified, -eclipse.keyring parameter will not be specified. Also -testOptions could contain "overrideSecurityStorage=false" for same effect. No1.2.1
memoryUsageIf specified, AUT's memory usage information will be printed to the console. No1.3.5
testsSemicolon-separated list of test name glob patterns (* - any chars, ? - exactly one char). If this argument is set Q7 runner executes listed test cases only.

-tests myTest.test or -test myTest*

No1.3.10

## Injection options

Injection mechanism allows to install some extra features into application-under-test before test execution. This might be useful in two cases:

• The project being tested is distributed via update site, so there's no default all-in-one application-under-test. In this case Eclipse SDK (or other eclipse package) can be used as application-under-test and plugins being tested will be installed into it.
• (rarely) Application-under-test contains some extra plugins which are required for testing, but not needed in product for end user

### Injecting from Update Site

This option is similar to installing something into Eclipse application via UI – by specifying update site URL and list of features to be installed.
In command line it is specified as argument with name injection.site where value is update site URL optionally followed by list of features separated by semicolon. If list of features is omitted, then all features from given site will be installed

-injection:site <update-site>(;feature-id1;feature-id2)


It is possible to specify this argument several times to inject features from more than one update site. Note that Q7 does not resolve dependencies automatically, therefore all dependencies of features to install are required to be either explicitly specified, or presented in AUT.

### Injection from directory

This way is similar to dropping some plugins into eclipse/plugins folder:

-injection:dir <path-to-dir>


It is possible to specify this argument several times to inject plugins from more than one directory

## Q7 Runtime options

This table summarizes Q7 runtime options which are rarely need to be modified and can be specified in testOptions argument. In Q7 IDE these options can be set by going to Preferences -> Q7 -> Advanced Options.

Option Name

Default value

Description

passedTestDetailsfalseWhen true, include output of 'take-screenshot' and 'trace' commands into a report
testExecTimeout300Timeout for a single test execution in seconds

contextRunnableTimeout

180000

Context applying timeout.

contextsWaitforjobsTimeout

30000

If there are any jobs started after context applying, wait for their completion during this time (in milliseconds).

jobDebugjobTimeout

300000

Timeout in milliseconds for jobs scheduled from eclipse Debug plugin.

jobNulifyRescheduleMaxValue

50

If job reschedules itself more than times specified by this parameter, Q7 stops setting delay to 0 (see jobScheduleDelayedMaxtime parameter).

jobSleepingStepTime

200

When job is in sleeping mode (see jobTreatAsSleeingTimeout option), execute commands with given delay (in milliseconds) between commands.

jobSleepingStepTimeout

120000

Wait timeout in milliseconds for stepping jobs (see jobTreatAsSleepingTimeout and jobSleepingStepTime)

jobTreatAsSleepingTimeout

10000

If job executes more than this time (in milliseconds) and sleeps (i.e. executing Thread.sleep() or Object.wait()), then Q7 considers that this job is waiting for some user actions and continues to the next command.

q7ImageCapture

false

Whether to capture screenshot from AUT on every ECL command

timerExecsWaitNullify

100

If Display.timerExec is scheduled for the delay less than this value (in milliseconds), set delay to 0.

autStartupTimeout

300

How many seconds Q7 should wait for application startup.

jobHangTimeout

30000

Job hang skip timeout in milliseconds. If job is running longer than this time, Q7 Runtime considers that it is hung and moves to the next command.

jobSchelduleDelayedMaxtime

600

Max job scheduled delay to be waited for in milliseconds. If job is scheduled with delay less than this value, Q7 sets delay to 0 and waits for job completion (also see jobNullifyRescheduleMaxValue). Otherwise Q7 Runtime does not wait for job completion if it is scheduled with a delay greater than this value.

launchingKillAutOnConnectError

false

Kill AUT on connect error. Whether Q7 should kill application-under-test if it cannot connect to it.

eclExecutionDelay

0

Wait for a given milliseconds between each ECL command. This can be useful when things go wrong at some point and it is hard to determine when by looking at execution. Setting this value to, say, 500, allows to inspect Q7 actions in more details.

workspaceClearForceGc

true

Forces garbage collection on workspace cleanup.

diagramPartLocatorFeatureIdentityNames

id,title

Use following EMF features for part identity

diagramPartLocatorIdentity

ClassName

Non EMF object identity method

diagramPartLocatorNameFeatureSupport

true

EMF object identity by 'name feature' support

diagramPartLocatorTextSupport

true

Use text content for part identity

These options can be set in command line like this:

-testOptions jobHangTimeout=60000;contextRunnableTimeout=120000

# Setting proxy

When Q7 runner executed on a machine behind a proxy server, it is possible to specify proxy settings via Java's system properties (see http://docs.oracle.com/javase/6/docs/technotes/guides/net/proxies.html):

java -Dhttp.proxyHost=my-local-proxy -Dhttp.proxyPort=8080 -jar ...

# Examples

## Sample Windows launch script

A script like this can be used as a starting point for creating a cmd-script for launching Q7 runner on Windows

REM !!! Replace the two values below with your Q7 account information (http://q7.xored.com/settings/balance)
SET Q7_CLIENT_ID=q7 client id
SET Q7_CLIENT_SECRET=q7 client secret

REM !!! Replace the value below with the path to the directory there
REM application under test (AUT) is located.
SET AUT=C:\absolute\path\to\your\application\directory

REM The place there Q7 tests project is located, by default that is
REM q7workspace directory under user home directory
SET PROJECT=%USERPROFILE%\q7workspace

REM Path to unpacked Q7 Runner, default is C:\Users\User\q7runner
SET RUNNER=%USERPROFILE%\q7runner

REM Path to directory with test results, default is C:\Users\User\q7results
SET RESULTS=%USERPROFILE%\q7results

REM Remove results dir if present
IF NOT EXIST %RESULTS% GOTO NORESULTS
RMDIR /S /Q %RESULTS%

:NORESULTS
md %RESULTS%

java -jar %RUNNER%/plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar ^
-data %RESULTS%/runner-workspace/ ^
-aut %AUT% ^
-autWsPrefix %RESULTS%/aut-workspace ^
-autConsolePrefix %RESULTS%/aut-output ^
-htmlReport %RESULTS%/q7report.html ^
-junitReport %RESULTS%/q7report.xml ^
-import %PROJECT% ^
-clientId %Q7_CLIENT_ID% ^
-clientSecret %Q7_CLIENT_SECRET%

## Sample Mac OS X/linux command

Below is a typical command line for executing a single project with Q7 tests with saving JUnit and HTML reports. We assume the following:

1. Q7 Runner is downloaded and unpacked into /Users/q7user/runner-example/eclipse
2. Application-under-test is downloaded and unpacked into /Users/q7user/runner-example/aut
3. Q7 Project with tests is stored in /Users/q7user/runner-example/q7tests

Note that on Windows the caret symbol (^) should be used instead of backslash for line continuation

java -jar /Users/q7user/runner-example/eclipse/plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar  \