Download/install
Q7 Runner is headless cross-platform eclipse application. Just download it from http://dl.xored.com/q7/1.2.22/products/q7.runner-1.2.22.zip, unpack and you are ready to go.
Node ID and license file
In order to function Q7 Runner requires node-locked license file. To get Node ID of current machine, the following command line can be used:
java -jar /path/to/q7/runner/plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar -application com.xored.q7.licensing.util
The output of this command should look like this:
Node ID of this machine: 659d27b6-036d-41c8-988d-40b594826e0e Please email support@xored.com with this node id to get your license file By default Q7 Runner assumes that license file path is ${user.home}/userID.q7.runner.license, to specify custom location: - Use -licenseFile <path-to-file> arg when using Q7 Runner from command-line - Add <q7><licenseFile>path-to-file</licenseFile></q7> element into plugin configuration when using Q7 Maven Plugin
Starting from version 1.2 it is possible to get a Q7 runner license file without contacting support. To get an evaluation license file, follow these steps:
- Go to http://www.xored.com/products/q7/q7-license/
- Select
Q7 Runner
from Product combo box. - Fill the rest of the fields and submit the form.
- You'll get an e-mail with your credentials from http://licensing.xored.com
- Log in to your profile, find a Q7 Runner license, paste your node ID and press 'Activate' button
- Download a license file and use it with Q7 Runner.
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 |
---|---|---|---|---|
licenseFile | Path to Q7 license file. Default value is |
| No | 1.0 |
aut | Platform-specific path to application under test |
| Yes | 1.0 |
import | Semicolon-separated list of project folders with Q7 tests or resources to link |
| 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 |
| Yes | 1.0 |
junitReport | File path to save JUnit report with test exec results |
| No | 1.0 |
htmlReport | File path to save HTML report with test exec results |
| 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 |
| No | 1.0 |
testOptions | Semicolon-separated list of Q7 Runtime options (see description below) |
| No | 1.0 |
autArgs | List of arguments for application-under-test separated by semicolon. |
| No | 1.0 |
autVMArgs | List of arguments for application-under-test's JVM separated by semicolon. |
| No | 1.0 |
suites | List of Test suite names separated by comma. Will include all test cases from suites. All other tests will be ignored. | No | 1.2.0 | |
skipTags | Semicolon-separated list of tags. Test cases containing any of listed tags are not be executed | skipExecution | No | 1.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 |
| 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 |
report | Generate report with custom reporting renderer. "id;path" format should be used to specify report renderer id and path to export. | No | 1.2.1 | |
noSecurityOverride | If specified, -eclipse.keyring parameter will not be specified. Also -testOptions could contain "overrideSecurityStorage=false" for same effect. | No | 1.2.1 | |
memoryUsage | If specified, AUT's memory usage information will be printed to the console. | No | 1.2.23 |
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
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 |
---|---|---|
testExecTimeout | 300 | Timeout 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
Examples
Typical usage
Below is a typical command line for executing a single project with Q7 tests with saving JUnit and HTML reports. We assume the following:
- Q7 Runner is downloaded and unpacked into
/Users/q7user/runner-example/eclipse
- Application-under-test is downloaded and unpacked into
/Users/q7user/runner-example/aut
- 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 \ -application com.xored.q7.runner.headless \ -data /Users/q7user/runner-example/runner-workspace/ \ -aut /Users/q7user/runner-example/aut/ \ -autWsPrefix /Users/q7user/runner-example/aut-ws- \ -autConsolePrefix /Users/q7user/runner-example/aut-console- \ -htmlReport /Users/q7user/runner-example/q7report.html \ -junitReport /Users/q7user/runner-example/q7report.xml \ -import "/Users/q7user/runner-example/q7tests"