42.7

Processes

In order to enable QF-Test to communicate with the SUT, the SUT's process must be started by QF-Test. For details about how the application is started by QF-Test and which kind of node is most applicable in your case, see chapter 46.

The following nodes are used to start or stop processes, to wait for a connection with the SUT or to wait for the termination of a process and check its exit value. The number of concurrent processes managed by QF-Test is limited only by the underlying system, but you have to assign a unique name to each process by which other nodes will identify it.

We will refer to processes run by QF-Test as clients. QF-Test distinguishes between two types of clients: arbitrary processes that are simply started and stopped and SUT clients, the actual Java applications that QF-Test interacts with.

Standard input and output of a client is redirected to a terminal that you can open from the »Clients« menu. The client's output is also stored in the log of a test run.

42.7.1

Start Java SUT client

This node provides the standard and most flexible way of starting an SUT client. To use it, you must know the Java command that starts your application. If the SUT is run through a script, use a Start SUT client node instead (see chapter 46).

Contained in: All kinds of sequences.

Children: None

Execution: The command line for the program is built from the attributes and the process is started. Its input and output are redirected to QF-Test.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Executable

The Java program to run, typically java or javaw on Windows. If you want to run a specific Java virtual machine you should give the full path name of the executable.

The "Select file" button brings up a dialog in which you can select the program file interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Variable: Yes

Restrictions: Must not be empty

Directory

Here you can set the working directory for the program. If you leave this value empty, the program will inherit QF-Test's working directory.

The "Select directory" button brings up a dialog in which you can select the directory interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Variable: Yes

Restrictions: Must be empty or an existing directory

Class name

The fully qualified name of the Java class of the SUT whose main(String[]) method will be called. If your application is run from an executable jar archive with the -jar parameter, you must leave this attribute empty.

Note QF-Test can only run the main method of the class if both the class itself and the main method are declared public. Please verify this if you get an IllegalAccessException when you try to start your application.

Variable: Yes

Restrictions: Valid class name

Executable parameters

The command line arguments for the Java executable. Put each parameter on a line of its own. Special quoting of whitespace or symbols is not required.

For example to set the classpath, set one line to -classpath and the following line to the desired value of the classpath. You don't need to concern yourself with QF-Test's jar files.

By default, empty parameters will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate parameter.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

Class arguments

These are the arguments that are passed to the main(String[]) method of the class to be started. Again, each argument requires a row of its own and special quoting is not required.

By default, empty arguments will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate argument.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.2

Start SUT client

If your application is normally started through a shell script or a special executable starter, the most convenient way to run it from QF-Test is through this kind of node. Depending on how the application is actually started by this script, some modifications may be required. A typical symptom is that the SUT starts up fine, but the connection to QF-Test is not established. In that case, read chapter 46.

Contained in: All kinds of sequences.

Children: None

Execution: The command line for the program is built from the attributes and the process is started. Its input and output are redirected to QF-Test.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Executable

The program to run. If the executable file is not located in a directory on the PATH you must give the full path name.

The "Select file" button brings up a dialog in which you can select the program file interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Variable: Yes

Restrictions: Must not be empty

Directory

Here you can set the working directory for the program. If you leave this value empty, the program will inherit QF-Test's working directory.

The "Select directory" button brings up a dialog in which you can select the directory interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Note This directory will become the current working directory after executing the program. As a result, a script named, say, ./copy_data will be looked up relative to QF-Test's working directory and not the directory given. Only the path names referred to in the script itself will be resolved relative to the new directory.

Variable: Yes

Restrictions: Must be empty or an existing directory

Executable parameters

The command line arguments for the executable. Put each parameter on a line of its own. Special quoting of whitespace or symbols is not required.

By default, empty parameters will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate parameter.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.3

Start process

To run an arbitrary program during a test, you can either use this node or an Execute shell command node. This node is preferable if you need to pass possibly complex arguments to the executable.

Contained in: All kinds of sequences.

Children: None

Execution: The command line for the program is built from the attributes and the process is started. Its input and output are redirected to QF-Test.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Executable

The program to run. If the executable file is not located in a directory on the PATH you must give the full path name.

The "Select file" button brings up a dialog in which you can select the program file interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Variable: Yes

Restrictions: Must not be empty

Directory

Here you can set the working directory for the program here. If you leave this value empty, the program will inherit QF-Test's working directory.

The "Select directory" button brings up a dialog in which you can select the directory interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Note This directory will become the working directory of the newly started process. It does not affect the working directory of QF-Test. As a result, a program named, say, ./startserver will be looked up relative to QF-Test's working directory and not the directory given. Only the path names referred to in the program itself will be resolved relative to the given directory.

Variable: Yes

Restrictions: Must be empty or an existing directory

Executable parameters

The command line arguments for the executable. Put each parameter on a line of its own. Special quoting of whitespace or symbols is not required.

By default, empty parameters will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate parameter.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.4

Execute shell command

This node is a convenient way to execute shell commands during a test. The shell that will execute the command can be specified with the command line arguments -shell <executable> and -shellarg <argument> for QF-Test. The default for Linux is /bin/sh, on Windows either command.com or cmd.exe is used, the value of the COMSPEC environment variable. When the shell is started it is treated like every other process started by QF-Test, so you can kill it or wait for it to terminate and check its exit code.

Contained in: All kinds of sequences.

Children: None

Execution: A shell is started to execute the command. Its input and output are redirected to QF-Test.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Shell command

The command to execute in the shell. Enter this just as you would at the command prompt.

WindowsOn Windows systems, quoting of arguments with blanks can be a little tricky. If you're using the standard Windows shell, simply use double quotes as always, for example dir "C:\Program Files". If you're using a Linux shell on Windows by specifying the -shell <executable> command line argument, use single quotes instead, i.e. ls 'C:/Program Files'.

Variable: Yes

Restrictions: Must not be empty

Directory

Here you can set the working directory for the shell. If you leave this value empty, the shell will inherit QF-Test's working directory.

The "Select directory" button brings up a dialog in which you can select the directory interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Variable: Yes

Restrictions: Must be empty or an existing directory

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.5

Start web engine

This node is used to start a web browser specifically for web testing. If the process for the SUT is already running, this node can also be used to open an additional browser window in the same process.

Contained in: All kinds of sequences.

Children: None

Execution: The command line for the browser program is built from the attributes and the process is started. Its input and output are redirected to QF-Test.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Browser type

The kind of browser to start. Officially supported values are currently "firefox" (or "mozilla") for Mozilla Firefox, "chrome" for Google Chrome, "edge" for Microsoft Edge, "opera" for Opera, "safari" for Apple Safari, "headless-firefox" for Mozilla Firefox without visible window, "headless-chrome" (or "headless") for Google Chrome without visible window, and "headless-edge" for Microsoft Edge without visible window.

Variable: Yes

Restrictions: Legal values are "ie", "firefox" (or "mozilla"), "chrome", "edge", "msedge", "opera", "safari", "headless-firefox", "headless-chrome" (or "headless")", and "headless-edge".

Directory of browser installation

For most browsers this field can be left empty. For Firefox with QF-Driver connection mode the installation directory of the browser must be specified here. When connecting via CDP-Driver or WebDriver, the default installation of the given browser is used. If several versions of that browser can be installed in parallel, a specific version may be chosen be specifying its installation directory here.

Variable: Yes

Restrictions: Must be empty or an existing directory.

Browser connection mode

QF-Test can connect to a browser in three different ways: By embedding the browser in a Java VM (the traditional QF-Driver mode), directly via Chrome DevTools Protocol or via Selenium WebDriver. Further information about connection modes and those support for browsers can be found in section 51.3. This attribute determines what to do in cases, when more than one connection mode is available for a browser. Possible values are:

Prefer QF-Driver

Prefer QF-Driver mode if possible, otherwise use CDP-Driver or WebDriver. This is the standard, used also if this attribute is left empty.

QF-Driver only

Exclusively use QF-Driver mode.

Prefer CDP-Driver

Prefer CDP-Driver mode if possible, otherwise use QF-Driver or WebDriver.

CDP-Driver only

Exclusively use CDP-Driver mode.

Prefer WebDriver

Prefer WebDriver mode if possible, otherwise use QF-Driver or CDP-Driver.

WebDriver only

Exclusively use WebDriver mode.

Variable: Yes

Restrictions: Must be empty or one of the values 'Prefer QF-Driver', 'QF-Driver only', 'Prefer CDP-Driver' or 'CDP-Driver only', 'Prefer WebDriver' or 'WebDriver only'

Executable

The Java program to start the browser with, typically java or javaw on Windows. If you want to run a specific Java virtual machine you should give the full path name of the executable.

The default value is ${qftest:java} which is the Java program that QF-Test itself runs on.

The "Select file" button brings up a dialog in which you can select the program file interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Variable: Yes

Restrictions: Must not be empty

Executable parameters

Special command line arguments for the java executable in which the browser is embedded. Can be used to specify the available memory (default is 200MB), define system properties, enable debugging, etc. Put each parameter on a line of its own. Special quoting of whitespace or symbols is not required.

By default, empty parameters will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate parameter.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.6

Start PDF client

Use this node to load the PDF document to be tested into a viewer, which QF-Test will start as a client process. Please refer to chapter 18 for information about the testing of PDF documents.

Contained in: All kinds of sequences.

Children: None

Execution: The viewer is started and the PDF document loaded.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

PDF document

The PDF document to be opened. If a relative path is specified it is resolved relative to the directory containing the current test suite.

The "Select file" button brings up a dialog in which you can select the program file interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Variable: Yes

Restrictions: Must not be empty

Page of PDF document

The page to show.

An integer number is interpreted as page number. A string in quotation marks is interpreted as page name.
Example:
5 opens page number 5
"Index IV" opens the page with the name Index IV

Variable: Yes

Restrictions: Must be a integer number or valid page name in quotation marks.

Password

If the document requires a password, it can be specified here.

Note When using a password it may be desirable to avoid having the password show up as plain text in the test suite or a run log. To that end the password can be encrypted by inserting the plain-text password, right-clicking and selecting »Encrypt text« from the popup menu. Please be sure to specify a password salt before encrypting via the option Salt for crypting passwords.

Variable: Yes

Restrictions: Empty or a valid password, if required only.

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.7

Start windows application

Launch and attach to a native Windows application. Please refer to chapter 15 for further information about Windows testing.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Windows application

The Windows executable to be launched.

Variable: Yes

Restrictions: Must not be empty

Directory

Here you can set the working directory for the program. If you leave this value empty, the program will inherit QF-Test's working directory.

The "Select directory" button brings up a dialog in which you can select the directory interactively. You can also get to this dialog by pressing Shift⁠+⁠Return or Alt⁠+⁠Return, when the focus is in the text field.

Variable: Yes

Restrictions: Must be empty or an existing directory

Window title

The title of the window to attach to.

You can select »Escape text for regular expressions« from the context menu for escaping special characters of regular expressions of that text.

Variable: Yes

Restrictions: Valid regexp if required.

As regexp

If this attribute is set, the title is interpreted as a regexp (see section 49.3) instead of a plain string.

Variable: Yes

Restrictions: None

Timeout

Time limit in milliseconds.

Variable: Yes

Restrictions: >= 0

Executable parameters

There is one tab for each of the following parameter lists:

The command line arguments for the Windows executable. Put each parameter on a line of its own. Special quoting of whitespace or symbols is not required. Parameters that start with "-qfengine:" are directly forwarded to the QF-Test win-engine process.

By default, empty parameters will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate parameter.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.8

Attach to windows application

Attach to a native Windows application. Please refer to chapter 15 for further information about Windows testing.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Window title

The title of the window to attach to. Via -pid <process ID> you can also specify the ID of the process. Via -class <class name>, the UI Automation class name of a window can be defined.

You can select »Escape text for regular expressions« from the context menu for escaping special characters of regular expressions of that text.

Variable: Yes

Restrictions: Must not be empty. Valid regexp if required.

As regexp

If this attribute is set, the title is interpreted as a regexp (see section 49.3) instead of a plain string.

Variable: Yes

Restrictions: None

Timeout

Time limit in milliseconds.

Variable: Yes

Restrictions: >= 0

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.9

Launch Android emulator

Use the node to start an Android emulator and connect to it. Quickstart your application helps you to set up a sequence for launching the emulator and starting an app along with the appropriate waiter nodes. Please have a look at chapter 16 for detailed information on testing of Android apps.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Name of the Android emulator to use

The name of the emulator to be used, as shown, for example, in the Android Virtual Device Manager in the column 'Name' (see Android studio screen showing available AVDs). Using the variable deviceName you do not need to hardcode it here.

Note In case you want to use an emulator created after you started QF-Test it may not be showing in the drop down list. Then, just type the name in the text field.

Variable: Yes

Restrictions: Must not be empty

Executable parameters

QF-Test communicates with the emulator via a Java program started additionally to the emulator, running in the background. Here, you can specify parameters for that Java program. Put each parameter on a line of its own. Special quoting of whitespace or symbols is not required. Sample: -Xmx1G to assign 1 GB memory to the Java program.

By default, empty parameters will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate parameter.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

Emulator arguments

The command line arguments for the emulator to be launched, for example -no-snapshot-save. Put each parameter on a line of its own. Special quoting of whitespace or symbols is not required.

By default, empty arguments will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate parameter.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.10

Connect to Android device

The node connects to a running Android emulator or a real device. Quickstart your application helps you to set up a sequence for connecting to an Android device, either emulator or real, and starting an app along with the appropriate waiter nodes. Please have a look at chapter 16 for detailed information on testing of Android apps.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Name of the Android device to use

The name of a real Android device attached to the computer or the emulator. The available names are shown in the drop down list. Alternatively, you will find them via the menu item »Running Android Devices« in the menu »Extras«.

You do not need to hardcode the name if you use the variable deviceName instead.

Note In case you want to use a real Android device attached to the computer after you started QF-Test it may not be showing in the drop down list. Then, just type the name in the text field. The same applies to an emulator you created after you started QF-Test.

Variable: Yes

Restrictions: Must not be empty

Executable parameters

QF-Test communicates with the real device, respectively the emulator, via a Java program started additionally to the emulator, running in the background. Here, you can specify parameters for that Java program. Put each parameter on a line of its own. Special quoting of whitespace or symbols is not required. Sample: -Xmx1G to assign 1 GB memory to the Java program.

By default, empty parameters will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate parameter.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.11

Connect to iOS device

The node attaches QF-Test to a physically connected or a simulated iOS device. If required, the Simulator is started as well. Quickstart your application helps you to set up a sequence for checking the iOS test sysstem requirements, connecting to an iOS device and starting an app, along with the appropriate waiter nodes. Please have a look at chapter 17 for detailed information on testing of iOS apps.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

Name of (simulated) iOS device

The name of a real iOS device attached to the computer or a simulated iOS device. QF-Test will try to find the best match for the given name with the available devices, so to run with any (simulated) iPhone, it is enough to simply put the string iPhone here.

You do not need to hardcode the name if you use the variable deviceName instead.

Variable: Yes

Restrictions: Must not be empty

Executable parameters

QF-Test communicates with the iOS device using a Java-based controller application. Here, you can specify parameters for that Java program. Put each parameter on a line of its own. Special quoting of whitespace or symbols is not required. Sample: -Xmx1G to assign 1 GB memory to the Java program.

By default, empty parameters will be ignored. In case you explicitly want to pass an empty command line argument (i.e. ''), you can deactivate the option Ignore empty argument lines when starting a client .

If the value in one a line is expanded from a variable to a List or an Array, then every element of the object is used as a separate parameter.

See subsection 2.2.5 about how to work with the tables.

Variable: Yes

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.12

Wait for client to connect

This node is used to make sure that the connection to a client is established. If after a configurable timeout the client is still not connected, a ClientNotConnectedException is thrown. You can also use the Variable for result attribute to store the result into a variable and the Throw exception on failure attribute to suppress the exception.

Contained in: All kinds of sequences.

Children: None

Execution: QF-Test waits until either the connection to the Java client is established or the timeout is up.

Attributes:

Client

The name of the Java client to wait for.

Variable: Yes

Restrictions: Must not be empty

Timeout

Time limit in milliseconds.

Variable: Yes

Restrictions: >= 0

GUI engine

The GUI engine to wait for. Only relevant for SUTs with more than one GUI engine as described in chapter 45.

Variable: Yes

Restrictions: See chapter 45

Variable for result

This optional attribute determines the name for the result variable of the action. If set, the respective variable will be set to 'true' for a successful check or wait and to 'false' in case of failure.

Note If this attribute is set, the attribute Error level of message is ignored and no error is reported. The attribute Throw exception on failure always remains effective, so it is possible to set a result variable and still throw an exception.

Variable: Yes

Restrictions: None

Local variable

This flag determines whether to create a local or global variable binding. If unset, the variable is bound in the global variables. If set, the topmost current binding for the variable is replaced with the new value, provided this binding is within the context of the currently executing Procedure, Dependency or Test case node. If no such binding exists, a new binding is created in the currently executing Procedure, Dependency or Test case node or, if there is no such node in the topmost node on the variables stack, falling back to the global bindings if necessary. See chapter 6 for a detailed explanation of variable binding and lookup.

In order to predefine the option use Enable 'Local variable' attribute by default.

Variable: No

Restrictions: None

Error level of message

This attribute determines the error level of the message that is logged in case of failure. Possible choices are message, warning and error.

Note If the attribute Throw exception on failure is set, this attribute is irrelevant and if Variable for result is set this attribute is ignored.

Variable: No

Restrictions: None

Throw exception on failure

Throw an exception in case of failure. For 'Check...' nodes a CheckFailedException is thrown, for 'Wait for...' nodes the respective specific exception.

Variable: No

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.13

Wait for mobile device

This node is used to make sure that the connection to a virtual or real Android device has been established. If after a configurable timeout, the Android device still has not been connected a ClientNotConnectedException is thrown. If QF-Test detects before the end of the timeout that a connection cannot be established it will throw a ConnectionFailureException.

Contained in: All kinds of sequences.

Children: None

Execution: QF-Test waits until either the connection to the emulator or the real device has been established or the timeout is up.

Attributes:

Client

The name of the Android or iOS client to wait for.

Variable: Yes

Restrictions: Must not be empty

Timeout

Time limit in milliseconds.

Variable: Yes

Restrictions: >= 0

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.14

Open browser window

This node opens a particular web page in a new browser window in a running web engine process. You should start that process via a Start web engine node.

Contained in: All kinds of sequences.

Children: None

Execution: Open a given web-page in the already running web engine process.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

URL

The URL of the web page to be shown in the browser. As a special case the URL "about:nowindow" can be used to start the SUT process without opening an initial browser window. In that state, cache or preference settings for the browser can be modified which may be a prerequisite for opening a given URL. The browser window with the actual target URL can then be opened via another Open browser window node.

Variable: Yes

Restrictions: Must not be empty

Name of the browser window

This attribute can be ignored unless you need to test a web application with multiple open browser windows holding similar documents. In that case the Name of the browser window attribute can be used to identify the browser window. Here you can specify the name for the browser window to be opened. You find a brief description how to handle multiple browser windows in FAQ 25.

Variable: Yes

Restrictions: None

Geometry of browser window

These optional attributes for the X/Y coordinate, width and height can be used to specify the geometry of the browser window to open.

Variable: Yes

Restrictions: Width and height must not be negative.

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.15

Launch a mobile app

Use the node to install and start a mobile app. Quickstart your application helps you to set up a sequence for launching the emulator/simulator - or attaching to a real Android or iOS device or running emulator/simulator - and starting an app along with the appropriate waiter nodes. Please have a look at chapter 16 for detailed information on testing of mobile apps.

Attributes:

Client

This is the identifier for the SUT client. It must remain unique as long as the process is alive. Other nodes will refer to the client by this name.

Variable: Yes

Restrictions: Must not be empty

APK/APP/IPA file path

The path of the mobile app to use. If you want to specify the path relative to the test suite, use the variable ${qftest:suite.dir} (cf. section 6.8). Sample: ${qftest:suite.dir}/apps/myapp.apk.

In case the app has been preinstalled and the .apk/.app/.ipa file is not available you can start the app via the attributes Package / Bundle ID und Activity (only for Android).

Variable: Yes

Restrictions: Must not be empty

Force app reinstallation

Select the attribute to install the app in any case, irrespective of an existing installation of the app on the Android emulator, the iOS simulator or real device.

Note Whether the reinstallation will delete existing settings and data of the app depends on the place where they have been saved.

Variable: No

Restrictions: None

Launch app

Select the attribute to start the app.

Variable: No

Restrictions: None

Package / Bundle ID

The package name of the Android app or the bundle id of the iOS app to be launched. Only required in case the .apk/.app/.ipa file cannot be specified with the attribute APK/APP/IPA file path. You also need to specify the attribute Activity (only for Android). You can either use the Android Debug Bridge to get the package name or launch or attach to an Android emulator or real device, start the app manually and record a component. The package name will then be recorded in the top level node of the component hierarchy.

Variable: Yes

Restrictions: None

Activity (only for Android)

The activity name of the Android app to be launched. Only required in case the .apk file cannot be specified with the attribute APK/APP/IPA file path. You also need to specify the attribute Package / Bundle ID. You can use the Android Debug Bridge to get the activity name.

Variable: Yes

Restrictions: No

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.16

Stop client

This node forcibly terminates a client process started by QF-Test. If the process has already terminated, nothing is changed. Otherwise, if the client is an SUT client, QF-Test first tries to call the Java method System.exit(-1) in the SUT to achieve a clean shutdown. If the client is not an SUT client or the process is still alive after the exit call, the process is killed and its exit code is set to -1. WindowsNote: On Windows child processes started by a process are not terminated when the parent process is killed. As explained in chapter 46, the java program for the SUT is not started directly by QF-Test, but through an intermediate program. This means that when the System.exit(-1) call fails to terminate the SUT for some reason, the process for the SUT's Java VM will be left hanging around.

Contained in: All kinds of sequences.

Children: None

Execution: Terminates the last process that was started under the given name.

Attributes:

Client

The client name of the process that is to be killed.

Variable: Yes

Restrictions: Must not be empty

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None

42.7.17

Wait for process to terminate

This node waits until a process that was started by QF-Test terminates. If a given time limit is exceeded and the process is still alive. Per default a ClientNotTerminatedException is thrown. Otherwise the client's exit code is read and tested against a given value. You can also use the Variable for result attribute to store the result into a variable and the Throw exception on failure attribute to suppress the exception.

Contained in: All kinds of sequences.

Children: None

Execution: Waits for the end of a process and checks its exit value unless the timeout is exceeded.

Attributes:

Client

The client name of the process to wait for.

Variable: Yes

Restrictions: Must not be empty

Timeout

Time limit in milliseconds.

Variable: Yes

Restrictions: >= 0

Expected exit code

If this attribute is set it is used to validate the exit code of the process. The type of the comparison is defined by prepending one of the four operators ==, !=, < and >. Just a number without preceding operation test for equality. If the test fails, an UnexpectedExitCodeException is thrown. The exception won't be thrown, if the attribute Throw exception on failure is not set.

Examples: If this attribute is set to 0, every exit code that is not 0 causes an exception. This is the same as for ==0. A value of >0 causes an exception for every exit code equal to or less than 0. This exception can be suppressed by un-checking the attribute Throw exception on failure.

Variable: Yes

Restrictions: See above

Variable for result

This optional attribute determines the name for the result variable of the action. If set, the respective variable will be set to 'true' for a successful check or wait and to 'false' in case of failure.

Note If this attribute is set, the attribute Error level of message is ignored and no error is reported. The attribute Throw exception on failure always remains effective, so it is possible to set a result variable and still throw an exception.

Variable: Yes

Restrictions: None

Local variable

This flag determines whether to create a local or global variable binding. If unset, the variable is bound in the global variables. If set, the topmost current binding for the variable is replaced with the new value, provided this binding is within the context of the currently executing Procedure, Dependency or Test case node. If no such binding exists, a new binding is created in the currently executing Procedure, Dependency or Test case node or, if there is no such node in the topmost node on the variables stack, falling back to the global bindings if necessary. See chapter 6 for a detailed explanation of variable binding and lookup.

In order to predefine the option use Enable 'Local variable' attribute by default.

Variable: No

Restrictions: None

Error level of message

This attribute determines the error level of the message that is logged in case of failure. Possible choices are message, warning and error.

Note If the attribute Throw exception on failure is set, this attribute is irrelevant and if Variable for result is set this attribute is ignored.

Variable: No

Restrictions: None

Throw exception on failure

Throw an exception in case of failure. For 'Check...' nodes a CheckFailedException is thrown, for 'Wait for...' nodes the respective specific exception.

Variable: No

Restrictions: None

QF-Test ID

At the moment the QF-Test ID attribute has no meaning for this type of node.

Variable: No

Restrictions: Must not contain any of the characters '\', '#', '$', '@', '&', or '%' or start with an underscore ('_').

Delay before/after

These attributes cause a delay before or after the execution of the node. If a value is empty, the Default delay from the global options is used.

Variable: Yes

Restrictions: Valid number >= 0

Comment

Here you can enter a comment that explains the purpose of this node. This is the preferred way of documenting the test suite.

Note For detailed documentation, especially for Test set, Test case or Procedure nodes, this text area might not be the right place. There are many excellent editors that are much better suited to this task. The option External editor command lets you define an external editor in which comments can be edited conveniently by pressing Alt⁠+⁠Return or by clicking the button.

You can trigger special behaviors of some nodes using doctags, please see Doctags.

If you enter text in the comment field of a Component node, the node will be considered as 'used' when you want to mark or delete unused components.

Variable: Yes

Restrictions: None