Manual

1
Installation and startup

The installation of QF-Test on the supported operating systems is explained in detail in the subsequent sections. The following packages are available for download:

Windows (section 1.2)
On Windows QF-Test is normally installed via the setup program QF-Test-4.4.1.exe which requires administrator privileges. If you are lacking the required permissions or prefer to keep all QF-Test files together in one place you can unpack the self-extracting archive QF-Test-4.4.1-sfx.exe instead.
Linux / Unix (section 1.3)
On Linux and other Unix systems please unpack the archive QF-Test-4.4.1.tar.gz.
macOS (section 1.4)
The disk-image QF-Test-4.4.1.dmg is provided for the installation on macOS.

It is possible to have different versions of QF-Test installed in parallel. Existing configuration files will not be overwritten during setup.

In section 30.2 you can find best practices about the QF-Test installation.

1.1
System requirements
1.1.1
Prime precondition

QF-Test itself requires Java 8. A 64 bit Java Runtime Environment (JRE) is provided with QF-Test, so Java does not need to be installed on your system unless required by the SUT.

Note If your environment and/or your system under test (SUT) requires to still use Java 7 or even Java 6, that is still possible. The Java command for the SUT can be configured separately when creating the setup sequence for your SUT. In case of Java 6, older versions of Jython and Groovy are used automatically.

1.1.2
Supported technology versions

The following table summarizes the officially supported versions of operating systems and required software for this QF-Test version 4.4.1. Support for additional systems and versions may be available on request but is not owed by QFS. Another option to get support for older software can be to use one of the older QF-Test versions that are still available for download at https://www.qfs.de/en/qf-test/download.html.

Technology Version restriction Comment
Operating system
Windows7, 8, 8.1, 10, Server 2008 R2, 2012, 2016 
Linux No special restrictions.
Unix Swing and JavaFX testing possible on Solaris, HP-UX, AIX,...
macOS Swing, JavaFX and Web testing possible.
Java
JDK/JRE 8 for QF-Test; 6 - 11 for the SUT 
Swing All platforms.
JavaFX8 and higherAll platforms.
SWT3.7 - 4.7Windows and Linux GTK only. For Eclipse/SWT 3.5 - 3.6 simply download https://archive.qfs.de/pub/qftest/swt_legacy.zip and extract the contents into the swt directory of your QF-Test installation.
Web Browser
QF-Driver connection mode
Internet Explorer11 
Firefox38 - 43 
ChromeCurrent stable Chromium version (57), part of the QF-Test distributionWindows only.
WebDriver connection mode, requires Java 8
Edge  
ChromeAs supported by the included ChromeDriver, currently the latest three Chrome versions, i.e. 69, 70, and 71  
FirefoxAs supported by the included GeckoDriver, i.e. currently 57 and greater incl. 60esr. Headless Firefox starting at version 57 (recommended min. 58)
Safari  
AJAX Toolkits
Detailed list of supported toolkits in section 45.3
Table 1.1:  Supported technology versions
1.2
Windows Installation

On Windows QF-Test can be installed in two variants.

1.2.1
Installing via the Windows setup file QF-Test-4.4.1.exe

This setup requires administrator privileges and follows the Windows standard of separating read-only program files from writable configuration files. If an older QF-Test version is detected it is also possible to skirt Windows standards and install QF-Test and its system configuration together at the place of the old installation.

4.2+ Windows compliant installation
Program files are saved to C:\Program Files\QFS\QF-Test or whichever target directory you choose. The system configuration with writable data is stored in %PROGRAMDATA%\QFS\QF-Test, irrespective of the selected target directory.

Note %PROGRAMDATA% usually refers to the directory C:\ProgramData but the name may vary depending on the Windows system. By default is is hidden in Windows Explorer. A simple way to navigate to this directory is to enter %PROGRAMDATA% into the address bar of Windows Explorer. In a PowerShell window use cd $env:PROGRAMDATA, in a cmd console window cd /d %PROGRAMDATA% to change to the respective drive and directory.

4.2+ Installation together with an existing QF-Test version
If an older QF-Test installation is found and there is no system configuration in %PROGRAMDATA%\QFS\QF-Test yet, you choose to follow the Windows compliant installation using %PROGRAMDATA% or to stick with the existing structure and install QF-Test there.

In the first case, after selecting the target directory for the QF-Test program files, the system configuration files are copied - just this once - from the existing installation to %PROGRAMDATA%\QFS\QF-Test.

When installing into the existing structure, QF-Test is installed into that directory and shares the system configuration that is already present there.

In both cases the directory %PROGRAMDATA%\QFS\QF-Test\qftestpath is added to the system PATH and the program files qftest.exe and qftestc.exe are copied there. This allows to start QF-Test from anywhere.

Independent of the installation choice both old and new QF-Test can be run in parallel. In case of the Windows compliant installation with %PROGRAMDATA% the old and new system configuration are independent. If the old structure is kept, all versions share the same system configuration. In the medium to long term we advise to move to %PROGRAMDATA% because the old structure requires changing access rights in the program directory, which is questionable. However, while migrating tests from QF-Test 4.1 to 4.2 it may be convenient to keep both versions close together. The move to a Windows compliant installation using %PROGRAMDATA% can also be made in the course of a later installation.

1.2.2
Unpacking the self-extracting archive QF-Test-4.4.1-sfx.exe

If you don't have administrator privileges or want to keep all QF-Test files together in a single place, unpack the archive QF-Test-4.4.1-sfx.exe at a suitable place. To do so, copy the file to the desired location and execute it there. If 7-Zip is installed on your system you can also right-click the archive to open and extract it with 7-Zip. This will create a directory named qftest at the target location which we will refer to as the root directory of QF-Test and that will also hold QF-Test's system configuration files.

After unpacking the files you can run the program minisetup-noadmin.exe in the sub-directory qftest-4.4.1. It will create associations for the file extensions belonging to QF-Test and optionally a startup menu entry and a desktop icon for QF-Test. If you have administrator privileges you can run minisetup-admin.exe instead which applies the same settings for all users and also adds the directory %PROGRAMDATA%\QFS\QF-Test\qftestpath to the system PATH and copies the program files qftest.exe and qftestc.exe there.

If you'd rather have a fully portable installation instead, you can create a folder named userdir in the qftest directory which will then serve as the user-specific configuration directory in place of %APPDATA%\QFS\QF-Test so that really all files belonging to QF-Test are kept together in one place and no changes are made to the system.

1.2.3
Completing the installation and configuring Java

As the last step each of the setup programs will offer to configure the Java program for QF-Test which is done with the help of a small dialog in which you can make your choices. With a portable installation you can run the program qftest\qftest-4.4.1\bin\qfconfig.exe to achieve the same.

4.2+ A 64 bit Java Runtime Environment is installed with QF-Test into its installation folder. It is recommended to use it. On a 32 bit Windows machine you must provide a Java 8 JDK or JRE yourself. You can either copy a 32 bit JRE 8 into QF-Test's installation directory as ...\qftest-4.4.1\jre\win32 and also chose to use the QF-Test Java or you can install it as the system JRE or in any other convenient place and select that as the alternative Java program.

The dialog also lets you adjust the maximum amount of memory to be used by QF-Test with a default of 512 MB.

The third value to be configured is the language for QF-Test. Normally the language is determined by the system settings, but you can also choose to always use the English or the German version.

The values above are stored in the file launcherwin.cfg in QF-Test's system configuration directory from where they are read by the qftest.exe start program. You can run the configuration program any time from the system menu to change these settings.

1.3
Linux/Unix Installation

First select a convenient directory that will contain this release of QF-Test as well as future updates. Common choices are /opt or /usr/local. Make sure you have write access to this directory and change to it. When upgrading to a new QF-Test version, use the same directory again.

Unpack the .tar.gz archive with tar xfzv QF-Test-4.4.1.tar.gz. This will create a directory named qftest, which we will refer to as the main or root directory of QF-Test. On a Linux/Unix system this also serves as the system directory holding the system configuration files of QF-Test.

After unpacking a QF-Test archive for the first time, QF-Test's root directory will hold only the version-specific subdirectory qftest-4.4.1. When upgrading, a new subdirectory for the current version will be added.

To finish the installation, change to the specific directory for the current QF-Test version with cd qftest/qftest-4.4.1 and run one of the two setup scripts provided. setup.sh is a plain Bourne shell script while setup.ksh is written for the Korn shell. On Solaris you must run ./setup.ksh. On other Unix systems both scripts should work equally well but the Bourne shell version ./setup.sh is preferred. Note that if you need to use the Korn shell scripts and want to create you own link or start QF-Test directly from its bin directory, you need to use the qftest.ksh start script instead of the plain qftest script.

The setup script will create the directories log, jython groovy and javascript under QF-Test's root directory unless they already exist. Additionally it will offer to create a symbolic link from the /usr/local/bin directory (or /usr/bin if there is no /usr/local/bin) to the respective Bourne shell or Korn shell run script for the qftest command. You need to have write permission to the /usr/local/bin directory for the link to be created.

On Linux QF-Test should normally use its own JRE. Alternatively the default java program for QF-Test can be defined now. Either way it can be overridden at execution time with the -java <executable> argument. The setup script searches PATH and proposes to use the first java program it detects. If you want to use a different program or if none was found, you can enter one. The script determines the JDK version automatically.

Next setting to perform is the maximum amount of memory to be used by QF-Test. As default 512 MB are taken. Alternatively QF-Test can be started with the -J-XmxZZZm command line argument, where ZZZ defines the memory in MB.

Finally the language for QF-Test can be configured. By default the language depends on the system settings, but you can also choose to always use the English or the German version. Note that this setting will affect all QF-Test users. Alternatively you can run QF-Test with the -J-Duser.language=XX option using en for English or de for German.

Those of the above settings that differ from the default are written to the file launcher.cfg in QF-Test's root directory. This file is read by the qftest launch-script and also evaluated during an update of QF-Test.

1.4
macOS Installation

To install QF-Test on a macOS System, simply mount the QF-Test-4.4.1.dmg disk image and copy the QF-Test app to your Applications directory (or any other folder) and start it from there.

NoteUnfortunately, Apple's JavaRuntimeSupport contains a bug, which is present in all versions of Java for macOS since OS X 10.6. and which might lead to a crash of QF-Test during start. The bug has been fixed in OS X 10.11 and in Java for OS X 2015-001. You can avoid the crash by installing the Java SE 6 package posted at https://support.apple.com/kb/DL1572.

Note To configure custom program arguments like memory used by QF-Test or the language there is a separate options-page in the QF-Test options (General->Startup). You can configure the settings there and they will then be applied after restarting QF-Test.

1.5
The license file

QF-Test requires a license file to run, which you should have received from Quality First Software GmbH.

4.0+ Since QF-Test 4.0 the preferred way to activate or update your QF-Test license is by way of the menu »Help«-»Update license...«.
The traditional way as described below is also still valid.

Place the license file into the system directory of QF-Test. On Windows, depending on the type of installation, this will be %PROGRAMDATA%\QFS\QF-Test (see section 1.2) or the root directory of your QF-Test installation as on Linux. Make sure the file is named license with no extension. Some mail clients try to guess the file type and add an extension on their own. When upgrading to a new QF-Test version you can simply keep the license file provided that it is valid for the new version.

Note For a complete list of the directories relevant to QF-Test please open the info dialog via the menu »Help«-»Info« and select the "System info" tab.

If you need to upgrade your license, for example to increase the number of concurrent QF-Test instances or when upgrading to a new version, you will receive a file called license.new from Quality First Software GmbH which is typically not a valid license in itself but must be combined with your current license. To do so, proceed as follows:

  • Place the file license.new in the same directory as the current license. Make sure that this directory and the file license are writable by you.
  • Start QF-Test in interactive mode. QF-Test will detect the license update, verify its validity and offer to upgrade your license file.
  • If you agree, the current license will be renamed to license.old and the new, combined license will be written to license. When you are satisfied that everything is OK, you can remove the files license.old and license.new.
  • If QF-Test doesn't seem to recognize the license upgrade, make sure that the timestamp of the file license.new is newer than that of the file license. Also make sure that no other instance of QF-Test is running on your computer.

In case you need to specify a special name or location for the license file or work with more than one license, this can be achieved with help of the -license <file> argument as described in chapter 39.

1.6
The configuration files

Note For a complete list of the directories relevant to QF-Test please open the info dialog via the menu »Help«-»Info« and select the "System info" tab.

QF-Test saves all of its window configuration and those global options that represent personal preferences together in a file named config located in the QF-Test user configuration directory which also holds run-logs for tests run in interactive mode, profile directories for web testing and temporary files for editing and running scripts.

4.2+ On Windows the user configuration directory defaults to %APPDATA%\QFS\QF-Test for new installations. If that directory doesn't exist and you already used a QF-Test version older than 4.2 on the same system that created the directory .qftest in your home directory for the user configuration, QF-Test will continue to use that .qftest directory.
You can manually move the content of the directory .qftest to %APPDATA%\QFS\QF-Test and delete .qftest afterwards. QF-Test since version 4.2.0 will then use this directory only. You should not move the files if you still want to use a version older than 4.2.0!
On Linux the user configuration directory is always ~/.qftest.
On macOS it is located at /Users/<username>/Library/Application Support/de.qfs.apps.qftest.
The personal config file is not read when QF-Test is run in batch mode (see section 1.7). Irrespective of the system default you can always specify an explicit location for the user configuration directory as a whole with the -userdir <directory> command line argument and just for the user config file with -usercfg <file>.

System specific options that need to be shared between users are saved in a file called qftest.cfg in the system configuration directory which also serves as the home for the license file, script modules, Java plugins and other customization files. On Windows the location of the system configuration directory depends on the installation variant (c.f. section 1.2). It is either located in %PROGRAMDATA%\QFS\QF-Test or in the root directory of QF-Test.
On Linux and macOS the default system configuration directory is the root directory of QF-Test.
The location of the system config file can be changed with the command line argument and -systemcfg <file> and that of the entire system directory with -systemdir <directory>.

1.7
Starting QF-Test

QF-Test can be run in two modes. In normal mode QF-Test is the editor for test-suites and run-logs and the control center for running programs, capturing events and executing tests. When run with the -batch argument, QF-Test goes into "batch" mode. Instead of opening an editor window, the test-suites given on the command line are loaded and executed automatically without the need for supervision. The result of the test is reflected in QF-Test's exit code, optional run-logs (see section 8.1) and reports (see chapter 18).

The setup script for Linux/Unix offers to create a symbolic link from /usr/local/bin to the qftest start script in the qftest-4.4.1/bin directory under QF-Test's root directory. That way you can simply enter qftest at the shell prompt to launch the application.

On Windows a menu shortcut is created as well as an optional desktop icon. You can either launch QF-Test from one of these or by double-clicking a test-suite or a run-log, since these files are associated with the QF-Test application. To run QF-Test from the console type qftest.

When run from the command line, QF-Test offers a wide range of arguments for customization, like selecting the Java VM to use. These are explained in detail in chapter 39.

In case different versions of QF-Test are installed at the same time, a specific version can be started by calling the qftest executable directly from the respective qftest-X.Y.Z/bin directory.

Mac In case QF-Test is not starting up anymore because of some incorrect settings under Options->General->Startup the default startup settings need to be restored. This can be done through running the following two commands from a macOS shell terminal.

defaults write de.qfs.qftest /de/qfs/qftest/ \
        -dict-add JVMOptions/ '{"Xmx"="-Xmx512M";"Xms"="-Xms16m";}'
defaults write de.qfs.qftest /de/qfs/qftest/ \
        -dict-add JVMArguments/ '{"args"="";}'
Example 1.1:  Resetting startup settings to defaults under macOS

1.8
Firewall Security Warning

On startup of QF-Test and/or the System Under Test (SUT) via QF-Test you might get a security warning from the Windows firewall asking whether to block Java or not. As QF-Test communicates with the SUT by means of network protocols, this must not be blocked by the local firewall in order to allow automated testing.