Skip to end of metadata
Go to start of metadata

Overview

Q7 Server is a tool for distributed automated execution of Q7 tests.  It has an arbitrary number of Q7 agents (workers) installed on other machines. The client for Q7 Server is a maven plugin, which uploads tests and application binaries to server and then server distributes all tests across available workers, so that overall execution time goes down with increasing number of workers. The results are delivered automatically back to the maven plugin and stored in JUnit XML format (Bamboo and Hudson automatically support this, so that failed tests are shown in web interface). Once the Q7 server and agents are up and running, there is no need to do any manual operations to run tests – everything is done during Maven build. 

The Q7 Server is a headless application and should work fine wrapped into a service (just need to make sure that its workspace directory is writeable), however Q7 Agents require active UI session in order to start applications under test and collect screenshots on test failures. 

Download

Here are download links for Q7 Server and Agent:

Command-line usage

Both Q7 server and agent are headless command-line Eclipse applications.

Server command-line args

The base command-line for Q7 server is the following (assuming that Q7 server resides in q7server folder. 

java -jar q7server/plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar -application com.xored.q7.cloud.server.app.headless -data q7serverWorkspace <rest of arguments>

Server arguments are summarized in table below.

Arg nameDescription
port​Port number to listen on for commands from agents. This argument must match to serverPort arg of agent command line.
telnetPort

Port to open ECL shell on. Default value is 2323.

httpPortPort to open Web management interface on, see Server Administration section below.
sitesDirLocal directory which will be publicly accessible by http. Some optional update sites or different Q7 runtimes can be put into this folder, see Dealing with Q7 Runtimes below.

Also any general-purpose Eclipse framework command-line arguments can be specified, see Eclipse help here – http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fruntime-options.html. For instance, to configure Xmx java argument for server, use -vmargs -Xmx256m.

Agent command-line args

The base command-line for Q7 agent is the following (assuming that Q7 agent resides in q7agent folder).

java -jar q7agent/plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar -application com.xored.q7.cloud.agent.app.headless -data q7agentWorkspace <rest of arguments>

During startup, Q7 Agent starts searching for available port to bind to starting from port #4000, so there's no need to pass a port via command line. 

The rest of agent arguments are summarized in table below.

Arg nameDescription
serverHostHost name or IP address of Q7 server
serverPortPort number of Q7 Server, must match to port parameter of Q7 Server.
licenseUrlLicense URL of Q7 license server. During startup agent connects to it and checks out Q7 runner license.
telnetPortPort number to open ECL shell. The default value is 2323.
portPort number to open ECL server.
skipTagsOptional list of Q7 tags this agent cannot handle. This option is useful only when agents are not equal, for example, some tests require specific context, like presence of database. Such tests can be marked with certain tags and then agents which don't provide this capability can be configured to skip these tests (tests will be executed on other agents)

As with Q7 server, any general-purpose Eclipse framework command-line arguments can be specified, see Eclipse help here – http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fruntime-options.html. For instance, to configure Xmx and max permgen space size, use -vmargs -Xmx256m -XX:MaxPermSize=256m.

Wrapping server and agent into script loop

In order to provide automatic launching of server and agent in case of abnormal termination (process killed/JVM crashed) we wrap server launching in a simple bash/cmd script which automatically restarts applications. For example, here's how our bash-script for Q7 server looks like:

#! /bin/bash
while true; do
 java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8001,suspend=n \
 -jar eclipse/plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar \
 -application com.xored.q7.cloud.server.app.headless \
 -data ./workspace \
 -consoleLog \
 -telnetPort 2323 \
 -port 7504 -vmargs -Xms80m -Xm256m -XX:MaxPermSize=256m 1>/dev/null 2>./err.txt
done

Client Maven Plugin

POM Configuration

Client maven plugin is a way to send tests for an execution to server during Maven build. Below is a step-by-step description of writing pom.xml using this plugin. The pom.xml should be placed in a project with Q7 tests. 

At first, start with a definition of basic project properties like group id, artifact id and version. Set packaging to q7test.

Then, add Xored Q7 repository to pluginRepositories so that Maven can download Q7 Client. 

 <pluginRepositories>
   <pluginRepository>
     <id>q7-releases</id>
     <name>Xored Q7 Maven repository</name>
     <url>http://maven.xored.com/nexus/content/repositories/q7-releases/</url>
   </pluginRepository> 
 </pluginRepositories>

Extract Q7 version to properties to ease further modifications

Begin build configuration for Q7 maven plugin:

Specify Q7 Server HTTP URL in q7server element

 <q7server>
   http://localhost:80 
 </q7server>

Configure Q7 client version

Outline on which platforms tests should be executed in form of {osgi.os}.{osgi.ws}.{osgi.arch}:

Specify AUT location(s) for each available platform. For instance, if your AUT is built using the same Maven build and products are located in another directory, it can look like this (here we use the standard Maven baseDir property which points to location of current project, so that we can specify AUT location relative to our tests):

Another option to specify AUT is to provide an HTTP URI Template like this:

<aut>
  <uri>http://maven.xored.com/nexus/content/repositories/thirdparty/eclipse/sdk/3.7.0/sdk-3.7.0-[classifier].[ext]</uri>
</aut> 

 

The classifier and ext are replaced by platform classifier (i.e. win32.win32.x86) on agent during execution. At first, it replaces ext with zip.md5 to check whether AUT has been updated and download is required. If download is required, it replaces ext with zip. This layout is convenient when AUT is deployed to Nexus repository, like here – http://maven.xored.com/nexus/content/repositories/thirdparty/eclipse/sdk/3.7.0/

Also, inside <aut> element it is possible to specify extra features which need to be installed into application-under-test in form of update sites, more information on this can be found on Q7 Runner page – http://help.xored.com/display/Q7/Q7+Runner#Q7Runner-Injectionoptions.

This feature is particularly useful if product has no RCP, i.e. it is built just as an update site. In this case, instead of making RCP just for tests, it is possible to "install" the update site into some standard AUT, like Eclipse SDK, right on Q7 Agents before the test execution, like this:

<aut>
  <uri>http://maven.xored.com/nexus/content/repositories/thirdparty/eclipse/sdk/3.7.0/sdk-3.7.0.zip</uri>
  <injections> 
    <!-- All features from koneki.ldt --> 
    <injection>
      <site>http://download.xored.com/q7/dogfood/koneki.ldt</site>
    </injection>
    <!-- DLTK from Indigo repository -->
    <injection>
      <site>http://download.xored.com/mirrors/indigo</site>
      <features>
        <feature>org.eclipse.dltk.core.feature.group</feature>
      </features>
    </injection>
  </injections>
</aut> 

 

In this particular example above all sites are remotes, however it is possible to specify the local update site using Maven's ${project.baseUri} as prefix. In this case Q7 client will automatically upload local update site to Q7 server to make it accessible for agents.

Specify an execution timeout via test options element:

Optionally add arbitrary metadata associated with this build:

Finally, close the plugin configuration and the rest of elements tags:

        </configuration>
      </plugin>
    </plugins>
  </build>
</project> 

 

Dealing with Q7 Runtimes

Q7 Agents include pre-bundled Q7 runtime and add it into AUT. However, once the server-agents infrastructure is up and running, it is inconvenient to reinstall all agents just because of newer bugfix version of Q7. For this purpose, it is possible to put a Q7 Runtime into a sites directory on Q7 Server (see sitesDir command-line argument for server) and then just configure AUT to use this version in your client POM via injections. For example, you put Q7 Runtime into sites/q7runtime-1.2.3 folder and then add the following injections configuration inside <aut> element:

<injections>
  <injection>
    <!-- server host and server HTTP port (see httpPort server arg) --> 
    <site>http://192.168.2.109:5009/sites/q7runtime-1.2.16/</site>
  </injection>
  <!-- this options prevents injection of Q7 Runtime bundled into agents --> 
  <ignoreOtherInjections>true</ignoreOtherInjections>
</injections> 

Monitoring Q7 Server status

Opening Q7 Server in browser via http://serverHost:httpPort shows a web interface. Via web interface it is possible to:

  • View currently executed test suites (and terminate them)
  • View connected agents and their status
  • View execution history 
  • View session logs
Labels: