Table of contents

Table of contents
Preface
How to use this manual
I
User manual
1
Installation and startup
1.1System requirements
1.1.1Hard- and Software
1.1.2Supported technologies - QF-Test
1.1.3Supported technologies - System under Test
1.2Windows Installation
1.2.1Installing via the Windows setup file QF-Test-.exe
1.2.2Unpacking the self-extracting archive QF-Test--sfx.exe
1.2.3Completing the installation and configuring Java
1.3Linux Installation
1.4macOS Installation
1.5The license file
1.6The configuration files
1.7Starting QF-Test
2
The user interface
2.1The test suite
2.2Basic editing
2.2.1Checking the validity of attribute values
2.2.2Undo
2.2.3Navigating the tree
2.2.4Insertion marker
2.2.5Moving nodes
2.2.6Transforming nodes
2.2.7Tables
2.2.8Packing and Unpacking
2.2.9Sorting Nodes
2.3Advanced editing
2.3.1Searching
2.3.2Replacing
2.3.3Complex searches and replace operations
2.3.4Multiple views
2.3.5Hiding toolbar buttons
3
Quickstart your application
3.1Setup sequence creation – The Quickstart Wizard
3.2Executing the setup sequence
3.3In case the client does not connect ...
3.4Program output and the Clients menu
4
Capture and replay
4.1Recording sequences
4.2Running tests
4.3Recording checks
4.4Fetching data from the UI
4.5Recording components
5
Components
5.1Components of a GUI
5.2Component nodes versus SmartID
5.2.1Improved readability of tests
5.2.2Test-driven development
5.2.3Keyword-driven testing
5.2.4Stability of recognition
5.2.5Maintainability
5.2.6Performance
5.2.7Combining Component nodes and SmartIDs
5.3How to achieve robust component recognition
5.3.1How to judge robust component recognition
5.3.2Opportunities for optimization
5.4Recognition criteria
5.4.1Class
5.4.2Name
5.4.3Feature
5.4.4Extra features
5.4.5Index
5.4.6Geometry
5.4.7Component hierarchy
5.5Component node
5.6SmartID
5.6.1Use cases for SmartIDs
5.6.2SmartID syntax for Class name
5.6.3SmartID syntax for Name
5.6.4SmartID syntax for Feature
5.6.5SmartID syntax for Extra features
5.6.6SmartID with index
5.6.7SmartID syntax for component hierarchies
5.6.8Recording and replaying SmartIDs
5.6.9Component QF-Test ID as SmartID
5.7Scope
5.8Generic components
5.9Sub-items: Addressing relative to a parent component
5.9.1Addressing via index
5.9.2Addressing via QPath
5.9.3Addressing via Items nodes
5.10Troubleshooting component recognition problems
5.10.1Timing synchronisation
5.10.2Recognition
5.11Component tree maintenance
5.11.1Clean up the component tree
5.11.2Update Components
5.12 Inspecting components
5.12.1Show methods
7.0+5.12.2UI Inspector
6
Variables
6.1Variable references
6.1.1Referencing simple variables
6.1.2Referencing group variables
6.1.3Referencing variables in scripts and script expressions
6.2Variable lookup
6.3Defining variables
6.4Variable levels
6.4.1Primary stack
6.4.2Seconday stack
6.5Displaying variables in debug mode – Example
6.6Data types of variables
6.6.1JSON data
6.7External data
6.8Special groups
6.9Immediate and lazy binding
7
Problem analysis and debugging
7.1The run log
7.1.1Error states
7.1.2Navigating the run log tree
7.1.3Run-time behavior
7.1.4Showing return values
7.1.5Accepting values of failed checks as good
7.1.6Split run logs
7.1.7Run log options
7.1.8Creating a test suite from the run log
7.1.9Merging run logs
7.2The debugger
7.2.1Entering the debugger
7.2.2Displaying the current variable values
7.2.3Debugger commands
7.2.4Manipulating breakpoints
7.2.5The debugger window
8
Organizing the test suite
8.1Test suite structure
8.2Test set and Test case nodes
8.2.1 Test management with Test set and Test case nodes
8.2.2Concept
8.2.3Variables and special attributes
8.3Sequence and Test step nodes
8.4Setup and Cleanup nodes
8.5Procedures and Packages
8.5.1Local Procedures and Packages
8.5.2Relative Procedures
8.5.3Inserting Procedure call nodes
8.5.4Parameterizing nodes
8.5.5Transforming a Sequence into a Procedure
8.6Dependency nodes
8.6.1Concept
8.6.2Usage of Dependencies
8.6.3Dependency execution and Dependency stack
8.6.4Characteristic variables
8.6.5Forced cleanup
8.6.6Rolling back Dependencies
8.6.7Error escalation
8.6.8Error handling
8.6.9Name spaces for Dependencies
8.7Documenting test suites
9
Projects
9.1Subprojects
9.2Project View
9.3The file qftest.qpj
10
The standard library
11
Scripting
11.1General
11.2Script expressions
11.3The run context rc
11.3.1Logging messages
11.3.2Performing checks
11.3.3Variables
11.3.4Accessing the SUT's GUI components
11.3.5Calling Procedures
11.3.6Setting options
11.3.7Override components
11.4Fundamentals of the Jython integration
11.4.1Jython Variables
11.4.2Jython Modules
11.4.3Post-mortem debugging of Jython scripts
11.4.4Boolean type
11.4.5Jython strings and character encodings
11.4.6Getting the name of a Java class
11.4.7A complex example
11.5Scripting with Groovy
11.5.1Groovy packages
11.6Scripting with JavaScript
11.6.1JavaScript imports
11.6.2NPM modules
11.6.3Print statements
11.6.4Execution
12
Unit Tests
12.1Java Classes as the Source for the Unit Test
12.2Basics of the Test Scripts
12.2.1Groovy Unit Tests
12.2.2Jython Unit Tests
12.2.3JavaScript Unit test
12.3Injections
12.3.1Component-Injections
12.3.2WebDriver-Injections
12.4Unit Tests in Report
6.0+
13
Android application testing
13.1Preconditions and known restrictions
13.1.1Preconditions
13.1.2Known restrictions
13.2Emulator or real device
13.3Installing Android Studio, emulator and virtual devices (AVD)
13.3.1Android Studio installation
13.3.2Android Studio virtual device configuration
13.4Connecting to a real Android device
13.5Create a QF-Test setup sequence for Android testing
13.5.1Usage of an Android emulator
13.5.2Usage of a real Android device
13.6Record actions and checks for Android
13.7Android utility procedures
6.0+
14
iOS application testing
14.1Preconditions and known restrictions
14.1.1Preconditions
14.1.2Known restrictions
14.2Installing Xcode, Simulators and IDB
14.2.1Xcode Installation
14.2.2iOS Development Bridge (idb) Installation
14.3Testing on a real iOS device
14.4Create a QF-Test Setup sequence for iOS testing
14.5Record actions and checks for iOS
14.6iOS utility procedures
15
Data-driven testing
15.1Data driver examples
15.2General use of Data drivers
15.3Examples for Data drivers
15.4Advanced use
16
Reports and test documentation
16.1Reports
16.1.1Report concepts
16.1.2Report contents
16.1.3Creating reports
16.1.4Customizing reports
16.2Testdoc documentation for Test sets and Test cases
16.3Pkgdoc documentation for Packages, Procedures and Dependencies
17
Test execution
17.1Test execution in batch mode
17.1.1Command line usage
17.1.2Windows batch script
17.1.3Groovy
17.2Executing tests in daemon mode
17.2.1Launching the daemon
17.2.2Controlling a daemon from QF-Test's command line
17.2.3Controlling a daemon with the daemon API
17.3Re-execution of nodes (Rerun)
17.3.1Triggering rerun from a run log
17.3.2Rerunning failing nodes immediately
18
Distributed test development
18.1Referencing nodes in another test suite
18.2Managing Components
18.3Merging test suites
18.3.1Importing Components
18.3.2 Importing Procedures and Testcases
18.4Strategies for distributed development
18.5Static validation of test suites
18.5.1Avoiding invalid references
18.5.2Unused procedures
19
Automated Creation of Basic Procedures
19.1Introduction
19.2How to use the Procedure Builder
19.3Configuration of the Procedure Builder
19.3.1The Procedure Builder definition file
20
Interaction with Test Management Tools
20.1HP ALM - Quality Center
20.1.1Introduction
20.1.2Step-by-step integration guide
20.1.3Troubleshooting
20.2Imbus TestBench
20.2.1Introduction
20.2.2Creating QF-Test template from interactions
20.2.3Importing test execution results
20.3QMetry
20.3.1Introduction
20.3.2Sample Configuration
20.4Klaros
20.4.1Introduction
20.4.2Importing QF-Test results into Klaros
20.5TestLink
20.5.1Introduction
20.5.2Generating template test suites for QF-Test from test cases
20.5.3Execution of test cases
20.5.4Importing QF-Test results into TestLink
21
Integration with Development Tools
21.1Eclipse
21.1.1Installation
21.1.2Configuration of the test nodes
21.2Ant
21.3Maven
21.4Jenkins
21.4.1Install and start Jenkins
21.4.2Requirements for GUI tests
21.4.3Install QF-Test Plugin
7.0+21.5JUnit 5 Jupiter
21.6TeamCity CI
6.0+
22
Integration with Robot Framework
22.1Introduction
22.2Prerequisites and installation
22.3Getting started
22.4Using the library
22.5Creating your own keywords
23
Keyword-driven testing with QF-Test
23.1Introduction
23.2Simple Keyword-driven testing with QF-Test
23.2.1Business-related Procedures
23.2.2Atomic component-oriented procedures
23.3Keyword-driven testing using dynamic or generic components
23.4Behavior-driven testing (BDT)
23.4.1Behavior-Driven Testing (BDT) from technical perspective
23.4.2Behavior-Driven Testing (BDT) from business perspective
23.5Scenario files
23.6Custom test case description
23.7Adapting to your software
24
Usage of QF-Test in Docker Environments
24.1What is Docker?
24.2QF-Test Docker Images
25
Performing GUI-based load tests
25.1Background and comparison with other techniques
25.2Load testing with QF-Test
25.2.1Provision of test systems
25.2.2Conception of the test run
25.2.3Preparing test systems prior to the test run
25.2.4Test execution
25.2.5Evaluating results
25.3Hints on test execution
25.3.1Synchronization
25.3.2Measuring end-to-end response times
25.4Troubleshooting
26
Executing Manual Tests in QF-Test
26.1Introduction
26.2Step-by-step Guide
26.3Structure of the Excel file
26.4The ManualTestRunner test suite
26.5Results
II
Best Practices
27
Introduction
28
How to start a testing project
28.1Infrastructure and testing environment
28.2Location of files
28.2.1Network installation
28.3Component Recognition
29
Organizing test suites
29.1Organizing tests
29.2Modularization
29.3Parameterization
29.4Working in multiple test suites
29.5Roles and responsibilities
29.6Managing components at different levels
29.7Reverse includes
30
Efficient working techniques
30.1Using QF-Test projects
30.2Creating test suites from scratch
30.3The standard library qfs.qft
30.4Component storage
30.5Extending test suites
30.6Working in the script editor
31
Hints on setting up test systems
31.1Using the task scheduler
31.2Remote access to Windows systems
31.3Automated logon on Windows systems
31.4Test execution on Linux
32
Test execution
32.1Dependencies
32.2Timeout vs. delay
32.3What to do if the run log contains an error
III
Reference manual
33
Options
33.1General options
33.1.1Project settings
7.0+33.1.2Saving test suites
33.1.3Display
33.1.4Editing
33.1.5Bookmarks
33.1.6External tools
33.1.7Backup files
33.1.8Library
33.1.9License
33.1.10Updates
33.2Recording options
33.2.1Events to record
33.2.2Events to pack
33.2.3Components
33.2.4Recording sub-items
6.0+33.2.5Recording Window
33.2.6Recording procedures
33.3Replay options
33.3.1Client options
33.3.2Terminal options
33.3.3Event handling
33.3.4Component recognition
33.3.5Delays
33.3.6Timeouts
33.3.7Backward compatibility
7.0+33.4SmartID und qfs:label
6.0+33.5Android
8.0+33.6iOS
33.7UI Inspector options
10.0+33.8Artificial Intelligence
33.9Debugger options
33.10Run log options
33.10.1General run log options
33.10.2Options for splitting run logs
33.10.3Options determining run log content
33.10.4Run log options for screenshots
33.10.5Options for mapping between directories with test suites
33.11Variables
33.12Runtime only
34
Elements of a test suite
34.1The test suite and its structure
34.1.1Test suite
34.2Test and Sequence nodes
34.2.1Test case
34.2.2Test set
34.2.3Test call
34.2.4Sequence
34.2.5Test step
34.2.6Sequence with time limit
34.2.7Extras
34.3Dependencies
34.3.1Dependency
34.3.2Dependency reference
34.3.3Setup
34.3.4Cleanup
34.3.5Error handler
34.4Data driver
34.4.1Data driver
34.4.2Data table
34.4.3Database
34.4.4Excel data file
34.4.5CSV data file
34.4.6Data loop
34.5Procedures
34.5.1Procedure
34.5.2Procedure call
34.5.3Return
34.5.4Package
34.5.5Procedures
34.6Control structures
34.6.1Loop
34.6.2While
34.6.3Break
34.6.4If
34.6.5Elseif
34.6.6Else
34.6.7Try
34.6.8Catch
34.6.9Finally
34.6.10Throw
34.6.11Rethrow
34.6.12Server script
34.6.13SUT script
34.7Processes
34.7.1Start process
34.7.2Execute shell command
34.7.3Launch Android emulator
34.7.4Connect to Android device
34.7.5Connect to iOS device
34.7.6Wait for client to connect
34.7.7Wait for mobile device
34.7.8Launch a mobile app
34.7.9Stop client
34.7.10Wait for process to terminate
34.8Events
34.8.1Mouse event
34.8.2Key event
34.8.3Text input
34.8.4Window event
34.8.5Component event
34.8.6Selection
34.8.7File selection
34.9Checks
34.9.1Check text
34.9.2Check text with AI
34.9.3Boolean check
34.9.4Check items
34.9.5Check selectable items
34.9.6Check image
34.9.7Check geometry
34.10Queries
34.10.1Fetch text
34.10.2Fetch index
34.10.3Fetch geometry
34.10.4Fetch image
34.11WebAPI
34.12Miscellaneous
34.12.1Comment
34.12.2Error
34.12.3Warning
34.12.4Message
34.12.5Set variable
34.12.6Set image
34.12.7Wait for component to appear
34.12.8Load resources
34.12.9Load properties
34.12.10Server HTTP request
34.12.11Unit test
34.13Windows, Components and Items
34.13.1Window
34.13.2Component
34.13.3Item
34.13.4Window group
34.13.5Component group
34.13.6Windows and components
34.14Deprecated nodes
34.14.1Test
35
Exceptions
IV
Technical reference
36
Command line arguments and exit codes
36.1Call syntax
36.2Command line arguments
36.2.1Arguments for the starter script
36.2.2Arguments for the Java VM
36.2.3Arguments for QF-Test
36.2.4Placeholders in the filename parameter for run log and report
36.3Exit codes for QF-Test
37
GUI engines
38
Running an application from QF-Test
39
Technical information about components
39.1Weighting of recognition features for recorded components
39.2Generating the component QF-Test ID
39.3SmartIDs - general syntax
39.4SmartIDs - special characters
39.5Android - list of trivial component identifiers
40
Technical details about miscellaneous issues
40.1Drag&Drop
40.2Timing
40.3Regular expressions
40.4Line breaks under Linux and Windows
40.5Quoting and escaping special characters
40.6Include file resolution
41
Advanced scripting (Jython, Groovy and JavaScript)
41.1Advanced script concepts
41.1.1Module load-path
41.1.2The plugin directory
41.1.3Initialization (Jython)
41.1.4Namespace environment for script execution (Jython)
41.1.5Exception handling
41.1.6Debugging scripts (Jython)
41.2The rc module: Run context API
41.2.1The expand parameter
10.0+41.3 The ai module
41.4The qf module
41.5The Image API
41.5.1The ImageWrapper class
41.6The JSON module
41.7The Assertions module: Natural Language Assertions
41.7.1Motivation
41.7.2API documentation
41.7.3Result handling
42
Controlling native Windows applications via the UIAuto module - without the QF-Test win engine
42.1Proceeding
42.1.1Starting the application
42.1.2Listing the GUI elements of a window
42.1.3Information on single GUI elements
42.1.4Identifiers for GUI elements
42.1.5Actions on GUI elements
42.2Example
42.2.1Starting the application
42.2.2GUI element information
43
Controlling and testing native MacOS applications
43.1Proceeding
43.1.1Starting the application
43.1.2Listing the GUI elements of a window
43.1.3Information on single GUI elements
43.1.4Identifiers for GUI elements
43.1.5Actions on GUI elements
44
Extension APIs
44.1The resolvers module
44.1.1Usage
44.1.2Implementation
44.1.3addResolver
44.1.4removeResolver
44.1.5listNames
44.1.6Accessing 'Best label'
44.1.7 The NameResolver Interface
44.1.8 The GenericClassNameResolver Interface
44.1.9 The ClassNameResolver Interface
44.1.10 The FeatureResolver Interface
44.1.11The ExtraFeatureResolver Interface
44.1.12 The ItemNameResolver Interface
44.1.13 The ItemValueResolver Interface
44.1.14The InterestingParentResolver Interface
44.1.15 The TooltipResolver Interface
44.1.16 The EnabledResolver Interface
44.1.17 The VisibilityResolver Interface
44.1.18 The MainTextResolver Interface
44.1.19 The WholeTextResolver Interface
44.1.20 The BusyApplicationDetector Interface
44.1.21Matcher
44.1.22External Implementation
44.2The ResolverRegistry
44.3 Implementing custom item types with the ItemResolver interface
44.3.1ItemResolver concepts
44.3.2The ItemResolver interface
44.3.3The class SubItemIndex
44.3.4The ItemRegistry
44.3.5Default item representations
44.4 Implementing custom checks with the Checker interface
44.4.1The Checker interface
44.4.2The class Pair
44.4.3 The CheckType interface and its implementation DefaultCheckType
44.4.4The class CheckDataType
44.4.5The class CheckData and its subclasses
44.4.6The CheckerRegistry
44.4.7Custom checker example
44.5Test run listeners
44.5.1The TestRunListener interface
44.5.2The class TestRunEvent
44.5.3The class TestSuiteNode
44.6ResetListener
44.7DOM processors
44.7.1The DOMProcessor interface
44.7.2The DOMProcessorRegistry
44.7.3Error handling
44.8Image API extensions
44.8.1The ImageRep class
44.8.2The ImageComparator interface
44.8.3The ImageRepDrawer class
45
Daemon mode
45.1Daemon concepts
45.2Daemon API
45.2.1The DaemonLocator
45.2.2The Daemon
45.2.3The TestRunDaemon
45.2.4The DaemonRunContext
45.2.5The DaemonTestRunListener
45.3Daemon security considerations
45.3.1Creating your own keystore
45.3.2Specifying the keystore
45.3.3Specifying the keystore on the client side
46
The Procedure Builder definition file
46.1Placeholders
46.1.1Fallback values for placeholders
46.2Conditions for Package and Procedure Definition
46.3Interpretation of the Component Hierarchy
46.4Details about the @CONDITION tag
47
The ManualStepDialog
47.1The ManualStepDialog API
48
Details about transforming nodes
48.1Introduction
48.2Transformation with type changes
48.3Additional transformations below the Extras node
48.3.1Transformations without side-effects
48.3.2Transformations with side-effects
49
Details about the algorithm for image comparison
49.1Introduction
49.2Description of algorithms
49.2.1Classic image check
49.2.2Pixel-based identity check
49.2.3Pixel-based similarity check
49.2.4Block-based identity check
49.2.5Block-based similarity check
49.2.6Histogram check
49.2.7Analysis with Discrete Cosine Transformation
49.2.8Block-based analysis with Discrete Cosine Transformation
49.2.9Bilinear Filter
49.3Description of special functions
49.3.1Image-in-image search
50
Result lists
50.1Introduction
50.2Specific list actions
50.2.1All types of lists
50.2.2Replacing
50.2.3Error list
50.3Exporting and loading results
51
Generic classes
51.1Accordion
51.2BusyPane
51.3Button
51.4Calendar
51.5CheckBox
51.6Closer
51.7ColorPicker
51.8ComboBox
51.9Divider
51.10Expander
51.11FileChooser
51.12Graphics
51.13Icon
51.14Indicator
51.15Item
51.16Label
51.17Link
51.18List
51.19LoadingComponent
51.20Maximizer
51.21Menu
51.22MenuItem
51.23Minimizer
51.24ModalOverlay
51.25Panel
51.26Popup
51.27ProgressBar
51.28RadioButton
51.29Restore
51.30ScrollBar
51.31Separator
51.32Sizer
51.33Slider
51.34Spacer
51.35Spinner
51.36SplitPanel
51.37Table
51.38TableCell
51.39TableFooter
51.40TableHeader
51.41TableHeaderCell
51.42TableRow
51.43TabPanel
51.44Text
51.45TextArea
51.46TextField
51.47Thumb
51.48ToggleButton
51.49ToolBar
51.50ToolBarItem
51.51ToolTip
51.52Tree
51.53TreeNode
51.54TreeTable
51.55Window
52
Doctags
52.1Doctags for reporting and documentation
52.1.1@noreport Doctag
52.2Doctags for Robot Framework
52.3Doctags for test execution
52.4Doctags for Editing
52.5Doctags influencing the procedure builder
A
FAQ - Frequently Asked Questions
B
Release notes
B.1QF-Test version 10.0
B.1.1Version 10.0.2 - January 15, 2026
B.1.2Version 10.0.1 - December 18, 2025
B.1.3Changes that can affect test execution
B.1.4Version 10.0.0 - December 9, 2025
B.2QF-Test version 9.0
B.2.1Version 9.0.6 - September 10, 2025
B.2.2Version 9.0.5 - July 30, 2025
B.2.3Version 9.0.4 - June 11, 2025
B.2.4Version 9.0.3 - April 29, 2025
B.2.5Version 9.0.2 - April 9, 2025
B.2.6Version 9.0.1 - March 12, 2025
B.2.7Changes that can affect test execution
B.2.8Version 9.0.0 - February 20, 2025
B.3QF-Test version 8.0
B.3.1Version 8.0.2 - December 05, 2024
B.3.2Version 8.0.1 - September 11, 2024
B.3.3Changes that can affect test execution
B.3.4Version 8.0.0 - August 8, 2024
B.4QF-Test version 7.1
B.4.1Version 7.1.5 - July 16, 2024
B.4.2Version 7.1.4 - June 12, 2024
B.4.3Version 7.1.3 - April 24, 2024
B.4.4Version 7.1.2 - March 14, 2024
B.4.5Version 7.1.1 - February 27, 2024
B.4.6Changes that can affect test execution
B.4.7Version 7.1.0 - February 20, 2024
B.5QF-Test version 7.0
B.5.1Version 7.0.8 - December 5, 2023
B.5.2Version 7.0.7 - October 11, 2023
B.5.3Version 7.0.6 - September 29, 2023
B.5.4Version 7.0.5 - September 20, 2023
B.5.5Version 7.0.4 - August 30, 2023
B.5.6Version 7.0.3 - Juli 13, 2023
B.5.7Version 7.0.2 - June 22, 2023
B.5.8Version 7.0.1 - May 31, 2023
B.5.9Changes that can affect test execution
B.5.10Version 7.0.0 - April 27, 2023
B.6QF-Test version 6.0
B.6.1Version 6.0.5 - March 15, 2023
B.6.2Version 6.0.4 - November 29, 2022
B.6.3Version 6.0.3 - September 6, 2022
B.6.4Version 6.0.2 - July 20, 2022
B.6.5Version 6.0.1 - June 9, 2022
B.6.6Changes that can affect test execution
B.6.7Version 6.0.0 - May 17, 2022
C
Keyboard shortcuts
C.1Navigation and editing
C.2UI Inspector
C.3Record and replay functions
C.4Keyboard helper
D
Glossary
E
Privacy
E.1Server data for version query
E.2Sending support requests from within QF-Test
E.3Context Information for Online Manual
E.4Request Data on WebDriver Download
E.5Client data in QF-Test log files
F
Third party software
List of figures
List of tables