ApplicationContext Class

Every AUT that is hooked by Squish has a corresponding ApplicationContext object. These objects provide the following properties and functions. (For examples of use see How to Use ApplicationContext Objects.)

Functions

ApplicationContext applicationContext(name)

This function returns the ApplicationContext object whose ApplicationContext.name matches the given name or an invalid ApplicationContext object if no such context exists.

String applicationContext.environmentVariable(name)

This function returns the value of the AUT process environment variable called name or an empty string if no such environment variable exists.

bool applicationContext.isFrozen(timeout)

This function returns a false value if the application responds before the timeout (in seconds) expired; otherwise it returns a true value.

applicationContext.detach()

This function detaches from a previously started (or attached) application.

If the respective application has been started with ApplicationContext startApplication(autName) Squish will attempt to close it, and eventually (if still running) forcefully close it.

If the respective application has been attached to with ApplicationContext attachToApplication(autName) Squish will leave it running but detach from it, thus leaving the application running. The application can then be attached to with ApplicationContext attachToApplication(autName) again.

After detaching from an application one should not access any of its objects anymore. (This would typically be done by using object references which had been retrieved before detaching.)

If the application context of applicationContext.detach() is the current application context, then the current application context will be changed to another (random) application context. So one must make sure to make the desired application context the current one before proceeding. (See SequenceOfApplicationContexts applicationContextList(), ApplicationContext currentApplicationContext() and setApplicationContext(contextHandle).)

String applicationContext.readStderr()

This function reads and returns everything which the application has written to the stderr stream since the last call to readStderr, or since the application started if there has been no previous call.

String applicationContext.readStdout()

This function reads and returns everything which the application has written to the stdout stream since the last call to readStdout, or since the application started if there has been no previous call.

SequenceOfApplicationContexts applicationContextList()

This function returns an array (a tuple in Python) of handles to all the existing application contexts.

ApplicationContext attachToApplication(autName)

ApplicationContext attachToApplication(autName, squishserver_host)

ApplicationContext attachToApplication(autName, squishserver_host, squishserver_port)

ApplicationContext attachToApplication(autName, squishserver_host, squishserver_port, timeoutSecs)

This function causes Squish to attach to the application called autName and returns a handle to its application context. The autName must be the name of an application that has been registered with the squishserver as an attachable AUT. See Configuring squishserver. No command line options can be given since the application should already be running.

squishserver_host and squishserver_port refer to the computer where the desired squishserver is running, and its TCP port. (This is not the host and port of the attachable Attachable AUT. The Attachable AUT's host and port are specified when the Attachable AUT is registered with the squishserver (see Register the Attachable AUT).)

The parameter timeoutSecs is being used after the socket connection to the attachable AUT has been established. If the attachable AUT requires more seconds than specified to respond to the attaching attempt an error will be thrown. If no timeoutSecs is specified the squishserver's (Maximum Startup Time) default is used—this is 20 seconds, unless it has been changed; see Squish Server Settings dialog.

If you want to specify a timeout, but don't want to change the host or port, you can do so by passing an empty string as the host (which will make Squish use the configured host—localhost by default), and by passing -1 as the port.

If attaching fails (e.g,. because the AUT is not running), this function throws an exception that can be caught in the test script. If the exception is not caught an error will be logged as an error in the test script's execution.

See Attaching to Running Applications for more information.

ApplicationContext currentApplicationContext()

This function returns a handle to the current application context.

ApplicationContext defaultApplicationContext()

This function returns a handle to the default application context. It is more reliable to use the ApplicationContext currentApplicationContext() function instead.

setApplicationContext(contextHandle)

This function can be used to change the current application context. The contextHandle object is a handle to an application context that has been returned by the any of the functions that return one—SequenceOfApplicationContexts applicationContextList(), ApplicationContext attachToApplication(autName), ApplicationContext defaultApplicationContext(), ApplicationContext currentApplicationContext(), and ApplicationContext startApplication(autName). If the argument is omitted the default context is activated.

If the contextHandle object is invalid—for example, if it refers to an application that has crashed—a catchable exception (TypeError in Python), will be thrown.

text getClipboardText()

setClipboardText(text)

These functions can be used for getting and setting the clipboard text content on a machine where the AUT is running.

When working with clipboard contents containing line breaks, be aware that their representations (\n and \r\n) are OS-specific.

Note to Linux users: For non-Qt X11 applications this feature does require the xsel tool to be installed. For non-Qt applications with alternative windowing system, this feature is not yet available.

ApplicationContext startApplication(autName)

ApplicationContext startApplication(autName, host)

ApplicationContext startApplication(autName, host, port)

ApplicationContext startApplication(autName, host, port, timeoutSecs)

This function starts the specified application and returns a handle to its application context. The autName parameter should be the name of an application whose path is already registered with the squishserver. See Configuring squishserver.

It is also possible to use the absolute path of an executable or a .jar file for autName. In addition, command line options can be supplied here.

Optionally, as second and third parameters a host and port can be specified. If these parameters are used, instead of connecting to the default host and port (as specified in the squishide's settings or on squishrunner's command line), a connection to the squishserver on the specified host and listening to the specified port will be established. This makes it possible to control multiple applications on multiple computers from a single test script.

The fourth parameter, timeoutSecs (an integer number of seconds) can also be specified. This tells Squish how long it should be prepared to wait for the application to start before throwing an error. If not specified, the squishserver's default is used—this is 20 seconds, and can be changed from Server Settings > Application Behavior > Maximum Startup Time, or by executing squishserver --config AUTTimeout numSeconds.

If you want to specify a timeout, but do not want to specify the host or port, you can do so by passing an empty string as the host (which will make Squish use the configured host—localhost by default), and by passing -1 as the port.

For more about how application context objects can be used, see How to Use ApplicationContext Objects. (See also, the ApplicationContext waitForApplicationLaunch() function.)

ApplicationContext connectTo(target)

ApplicationContext connectTo(target, host)

ApplicationContext connectTo(target, host, port)

This function starts a connection to a remote desktop (e.g., VNC) server and returns a handle to its application context. The target specifies the connection parameters.

The connection target can be either a URL or parameter map. To connect to a VNC server, the parameters of both the URL and parameter map need to conform to RFC 7869, which specifies the following fields:

• scheme - the connection scheme "vnc";
• host - the hostname of the VNC server;
• port - the TCP port of the VNC server. If no port is specified, the default value of 5900 is used;
• VncUsername - the user name used for VNC authentication. Used only if required by the server;
• VncPassword - the password used for VNC authentication. Used only if required by the server.

Squish also offers a "Native" connection protocol which allows the squishserver to connect directly to a user session it is running in, without any need for an additional remote desktop server/authentication. In order to use it, the "os" scheme needs to be specified as a part of the target parameter. The "os" scheme accepts the following fields:

• scheme - the connection scheme "os";
• display - the X11 display string to connect to. If not specified, the default display string will be used. This parameter is only relevant on UNIX-like systems and ignored on Windows and OSX systems.

Remote desktop connections are always routed through a squishserver instance. If the host and port parameters are specified, Squish will use the server listening at the specified address. By default the server parameters specified in the squishide settings or on the squishrunner command line will be used.

For example:

connectTo("vnc://example.com")
connectTo("vnc://example.com:5901")
connectTo("vnc://example.com?VncPassword=secret")
connectTo("vnc://example.com:5901?VncUsername=user&VncPassword=secret")
connectTo("os://")

connectTo({"scheme": "vnc",
           "host": "example.com"})
connectTo({"scheme": "vnc",
           "host": "example.com",
           "port": 5901})
connectTo({"scheme": "vnc",
           "host": "example.com",
           "VncPassword": "secret"})
connectTo({"scheme": "vnc",
           "host": "example.com",
           "port": 5901,
           "VncUsername": "user",
           "VncPassword": "secret"})
connectTo({"scheme": "os"})

connectTo("vnc://example.com");
connectTo("vnc://example.com:5901");
connectTo("vnc://example.com?VncPassword=secret");
connectTo("vnc://example.com:5901?VncUsername=user&VncPassword=secret");
connectTo("os://");

connectTo({scheme: "vnc",
           host: "example.com"});
connectTo({scheme: "vnc",
           host: "example.com",
           port: 5901});
connectTo({scheme: "vnc",
           host: "example.com",
           VncPassword: "secret"});
connectTo({scheme: "vnc",
           host: "example.com",
           port: 5901,
           VncUsername: "user",
           VncPassword: "secret"});
connectTo({scheme: "os"});

connectTo("vnc://example.com");
connectTo("vnc://example.com:5901");
connectTo("vnc://example.com?VncPassword=secret");
connectTo("vnc://example.com:5901?VncUsername=user&VncPassword=secret");
connectTo("os://");

connectTo({"scheme" => "vnc",
           "host" => "example.com"});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "port" => 5901});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "VncPassword" => "secret"});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "port" => 5901,
           "VncUsername" => "user",
           "VncPassword" => "secret"});
connectTo({"scheme" => "os"});

connectTo("vnc://example.com");
connectTo("vnc://example.com:5901");
connectTo("vnc://example.com?VncPassword=secret");
connectTo("vnc://example.com:5901?VncUsername=user&VncPassword=secret");
connectTo("os://");

connectTo({"scheme" => "vnc",
           "host" => "example.com"});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "port" => 5901});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "VncPassword" => "secret"});
connectTo({"scheme" => "vnc",
           "host" => "example.com",
           "port" => 5901,
           "VncUsername" => "user",
           "VncPassword" => "secret"});
connectTo({"scheme" => "os"});

connectTo "vnc://example.com"
connectTo "vnc://example.com:5901"
connectTo "vnc://example.com?VncPassword=secret"
connectTo "vnc://example.com:5901?VncUsername=user&VncPassword=secret"
connectTo "os://"

connectTo [ dict create "scheme" "vnc"
                        "host" "example.com" ]
connectTo [ dict create "scheme" "vnc"
                        "host" "example.com"
                        "port" 5901 ]
connectTo [ dict create "scheme" "vnc"
                        "host" "example.com"
                        "VncPassword" "secret" ]
connectTo [ dict create "scheme" "vnc"
                        "host" "example.com"
                        "port" 5901
                        "VncUsername" "user"
                        "VncPassword" "secret" ]
connectTo [ dict create "scheme" "os" ]

Properties

String applicationContext.commandLine

This read-only property holds the command line that the application was started with.

String applicationContext.cwd

This read-only property holds the application's current working directory.

String applicationContext.host

Every application context is connected to a squishserver process. This read-only property holds the computer/host name or TCP/IP address of the computer where the squishserver process is running and which this application context is connected to.

If this application context has been created by ApplicationContext startApplication(autName) then this property also denotes the computer/host name or TCP/IP address of the computer where the AUT is running.

bool applicationContext.isRunning

This read-only property is true if the communication between squishserver and Squish Hook in the AUT is still active, otherwise false.

The communication between squishserver and Squish Hook is shutting down when the Squish Hook is shutting down. The Squish Hook in turn is shutting down when the AUT is shutting down. (For example in case of Qt, when the main Qt event loop exits.)

However, the AUT shut down is not necessarily immediate: An AUT can perform lengthy operations shortly before finally exiting, and so for some amount of time isRunning can be false even though the AUT process is still alive.

String applicationContext.name

This read-only property holds the application's name. On most platforms and GUI toolkits this is the application's process name.

int applicationContext.pid

This read-only property holds the application's process identifier.

int applicationContext.port

Every application context is connected to a squishserver process. This read-only property holds the TCP port number of the squishserver process which this application context is connected to.

time applicationContext.startTime

This read-only property holds the time when the application was started. (The property's data type varies depending on the scripting language used.)

int applicationContext.totalTime

This read-only property holds the amount of time that the AUT process has been scheduled in user and kernel modes measured in milliseconds.

int applicationContext.usedMemory

This read-only property holds the amount of memory used by the AUT process. For Windows operating systems, the value corresponds to the working set size in bytes. For Linux operating systems, the value corresponds to the resident set size (RSS), in bytes. For macOS, it is also the RSS, but in Kbytes.

String applicationContext.osName

This read-only property holds the name of the OS the AUT is running on. Possible names include:

• "Android" — Android
• "Darwin" — macOS and iOS
• "Linux" — Linux
• "QNX" — QNX
• "SunOS" — Solaris
• "Windows" — Windows