1

Installation and startup

The video 'Installation & Trial License' first explains the download and installation of QF-Test, then (starting at min 8:20) the installation of a trial license.

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-8.0.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-8.0.1-sfx.exe instead.

Linux (section 1.3)

On Linux and other Linux systems please unpack the archive QF-Test-8.0.1.tar.gz.

macOS (section 1.4)

The disk-image QF-Test-8.0.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 35.2 you can find best practices about the QF-Test installation.

1.1

System requirements

1.1.1

Hard- and Software

QF-Test itself runs with Java 17. The required 64bit 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 system under test (SUT) uses Java it should typically use its own JRE, not that of QF-Test. The Java command for the SUT can be configured separately when creating the setup sequence for your SUT. Supported Java versions for the SUT are listed below.

For a QF-Test installation you need to reserve about 1 GB on your hard disk. The required RAM to work with QF-Test is in the same region but depends on the sizes of your test suites and the length of your test run, see I've got a long-running test and QF-Test runs out of memory. How can I prevent that? . Note that you need to add the resources required by the SUT.

1.1.2

Supported technologies - QF-Test

The following table summarizes the officially supported versions of operating systems and required software for this QF-Test version 8.0.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.

Note In QF-Test version 7.0 support for 32 bit software was deprecated for removal in a future QF-Test version.

Java 17 is shipped with QF-Test. QF-Test runs on JDK/JRE 17 or higher on the following operating systems:

1.1.3

Supported technologies - System under Test

The following table summarizes the officially supported versions of operating systems and required software for this QF-Test version 8.0.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.

The system under test can be run on the same operating systems as QF-Test, for restrictions see Supported operating systems for QF-Test.

Note Support for 32bit software was deprecated in QF-Test version 7.0 and removed in version 8.0. However, testing of 32bit native Windows applications remains supported.

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-8.0.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.

Silent Installation
For an automatic distribution on test systems it might be necessary to install QF-Test silently. QF-Test supports this kind of installation because the installer is based on Inno Setup. This allows to use nearly all documented parameters from https://jrsoftware.org/ishelp/index.php?topic=setupcmdline at the installation of QF-Test.

You can perform a silent default installation with QF-Test-8.0.1.exe /VERYSILENT.
If you want to not create a Deskop icon you can run QF-Test-8.0.1.exe /VERYSILENT /MERGETASKS="!desktopicon". This executes a standard installation without the task "desktopicon".
Both the minisetup-admin.exe and minisetup-noadmin.exe can also be installed silently. For example via minisetup-admin.exe /VERYSILENT.

Please note that the installation for all users always requires elevated administrative rights. To also automatically accept the Windows UAC dialog the calling process must already have elevated rights. The parameter /CURRENTUSER does not help here, because the installation always requires elevated rights independent of installing for all or just the current user.
An exception of this rule is minisetup-noadmin.exe, which allows to configure an already installed QF-Test for the current user only. It does not need elevated rights.

Instead of performing a silent installation you can also use the portable self-extracting archive QF-Test-8.0.1-sfx.exe.

1.2.2

Unpacking the self-extracting archive QF-Test-8.0.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-8.0.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-8.0.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-8.0.1\bin\qfconfig.exe to achieve the same.

A 64bit Java 17 Runtime Environment is installed with QF-Test into its installation folder. It is recommended to use it.

The dialog also lets you adjust the maximum amount of memory to be used by QF-Test with a default of 1024 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 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-8.0.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 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-8.0.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-8.0.1 and run the setup script provided (setup.sh).

The setup script will create the directories log, jythongroovy 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 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>(deprecated) 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 1024 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-8.0.1.dmg disk image and copy the QF-Test app to your Applications directory (or any other folder) and start it from there.

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

The video 'Installation & Trial License' first explains the download and installation of QF-Test, then (starting at min 8:20) the installation of a trial license.

The video 'License update' shows how to update a license.

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 licensewith 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 43.

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 7.1) and reports (see chapter 23).

The setup script for Linux offers to create a symbolic link from /usr/local/bin to the qftest start script in the qftest-8.0.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 43.

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"="-Xmx1024m";"Xms"="-Xms16m";}'
defaults write de.qfs.qftest /de/qfs/qftest/ \
        -dict-add JVMArguments/ '{"args"="";}'

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.

Last update: 9/10/2024 Copyright © 1999-2024 Quality First Software GmbH