|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:
QF-Test-4.2.5.exewhich 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.2.5.dmgis 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 28.2 you can find best practices about the QF-Test installation.
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.
|Supported technology versions|
The following table summarizes the officially supported versions of operating systems and required software for this QF-Test version 4.2.5. 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.
||Table 1.1: Supported technology versions|
On Windows QF-Test can be installed in two variants.
|Installing via the Windows setup file
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.
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
irrespective of the selected target directory.
%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
%PROGRAMDATA% to change to the respective drive and directory.
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
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.
|Unpacking the self-extracting archive
If you don't have administrator privileges or want to keep all QF-Test files together in a single place, unpack
QF-Test-4.2.5-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
After unpacking the files you can run the program
minisetup-noadmin.exe in the sub-directory
qftest-4.2.5. 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
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
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.
|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.2.5\bin\qfconfig.exe to achieve the same.
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.2.5\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.
First select a convenient directory that will contain this release of
QF-Test as well as future updates. Common choices are
/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.
tar xfzv QF-Test-4.2.5.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.2.5. 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
cd qftest/qftest-4.2.5 and run one of the two setup scripts
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
The setup script will create the directories
already exist. Additionally it will offer to create a symbolic link
/usr/local/bin directory (or
/usr/bin if there is no
the respective Bourne shell or Korn shell run script for the
You need to have write permission to the
directory for the link to be created.
On Linux QF-Test should normally use its own JRE. Alternatively
java program for QF-Test can be defined now.
Either way it can be overridden at execution time with the
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
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
-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.
To install QF-Test on a macOS System, simply mount the
QF-Test-4.2.5.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.
|The license file|
QF-Test requires a license file to run, which you should have received from Quality First Software GmbH.
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
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
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
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:
license.newin the same directory as the current license. Make sure that this directory and the file
licenseare writable by you.
license.oldand the new, combined license will be written to
license. When you are satisfied that everything is OK, you can remove the files
license.newis 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
argument as described in chapter 37.
|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
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.
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
You can manually move the content of the directory
.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
On macOS it is located at
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
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
and that of the entire system directory with
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
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 17).
The setup script for Linux/Unix offers to create a symbolic link from
/usr/local/bin to the
qftest start script
qftest-4.2.5/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
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 37.
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
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.
||Example 1.1: Resetting startup settings to defaults under macOS|
|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.
|Last update: 07/10/2018
Copyright © 1999-2019 Quality First Software GmbH