Squish's C++ API
This section covers the C++ API that Squish provides to make it possible to achieve even tighter integration with the AUT, and to solve some specific problems that occasionally arise.
Recording Hints to Influence and Control the Event Recorder
Recording hints allow an application to influence Squish's event recorder while a test engineer records a test script. Using a recording hint an application can insert comments or function calls into the test script at particular points.
Recording hints are made possible by the RecordHint
class. This class is supplied with Squish and is defined in the file recordhint.h
in Squish's include
directory. The public API is implemented inline in this file, so the application only needs to include the file itself—there is no need to link against an additional library.
To see how the RecordHint
class is used in practice, we will review an example.
Let's assume that we have an application which defines a function called myfunc
which we have also wrapped so that a test script can access it. After the user clicks a particular button in the application we want the test script to call myfunc
. To do this, we add the following C++ code at the point where the button click is handled:
Squish::RecordHint myfunc_comment(Squish::RecordHint::Comment, "Call myfunc"); myfunc_comment.send(); Squish::RecordHint myfunc_caller(Squish::RecordHint::Function, "myfunc"); myfunc_caller.send();
Now when recording a script and clicking on the button, two extra lines in the test script will be generated, as the code snippet below illustrates:
def main(): ... clickButton("....") # Call myfunc myfunc()
function main() { ... clickButton("...."); // Call myfunc myfunc(); }
sub main { ... clickButton("...."); # Call myfunc myfunc(); }
# encoding: UTF-8 require 'squish' include Squish def main # ... clickButton("....") # Call myfunc myfunc() # ... end
proc main {} { ... invoke clickButton "...." # Call myfunc invoke myfunc }
This small example shows when and how to use record hints. The complete API is in the recordhint.h
file; look for the RecordHint
class inside the Squish
namespace.
Using the Built-in Hook
In most cases, Squish hooks into the AUT without requiring any special preparation. However, in some cases (e.g., on AIX) this is not possible due to technical limitations of the operating system.
In such cases the built-in hook approach can be used. This requires two tiny changes to the AUT:
- Include the
qtbuiltinhook.h
header file, which can be found in Squish'sinclude
directory, in the application's code where themain
function is defined or where theQApplication
object is created. - Call the
Squish::installBuiltinHook
function as soon as you have created theQApplication
object.
Example:
#include <QApplication> #include "qtbuiltinhook.h" int main(int argc, char **argv) { QApplication app(argc, argv); Squish::installBuiltinHook(); // ... return app.exec(); }
This is the only preparation needed to make your program testable on most platforms that don't support the preloading mechanism. It does not matter if you leave in this code on other platforms, since the function is smart enough to do nothing if it isn't needed.
Note: Enforcing the built-in hook on Windows
On Windows an extra setting is required to enable the built-in hook, please see Enforcing the Built-in Hook for more details.
The Squish::installBuiltinHook
function is very lightweight and won't make any difference to the program's performance. Nonetheless, we recommend removing it for publicly released versions of the program. This can easily be done using an #ifdef
that includes the header and the function call for testing builds and excludes them for release builds.
Details
The Squish::installBuiltinHook
function performs the following actions:
- If the environment variable
SQUISH_PREFIX
is not set, it does nothing and returns immediately. - Otherwise it tries to load the Qt toolkit support library
squishqtwrapper
and its dependencies from thelib
(orbin
) subdirectory in the directory specified bySQUISH_PREFIX
, and tries to resolve and call an initialization function in that library. If it fails to find the library or finds it but fails to resolve the initialization function, it does nothing and returns.
The Squish::installBuiltinHook
function returns true
if the hooking succeeded, that is, the application is executed by Squish; otherwise it returns false
.
Enforcing the Built-in Hook
The built-in hook is meant as a fallback mechanism on platforms where the normal hooking doesn't work. So if you want to use the built-in hook on platforms where Squish supports non-intrusive hooking, Squish will still use the non-intrusive hooking mechanism by default, although the built-in hook is included in the AUT.
Nonetheless, it is possible to force the squishserver to use the built-in hook rather than Squish's non-intrusive hooking mechanism. This can be done by setting a squishserver configuration option (see Configuring ):
squishserver --config usesBuiltinHook aut
Note: Clearing the AUT Hook Setting
At the moment, the only way to delete this setting is to manually edit the squishserver's configuration file. On Unix-like systems, this file is located in $HOME/.squish/ver1/server.ini
and on Windows it is in %APPDATA%\froglogic\Squish\ver1\server.ini
.
To disable the usesBuiltinHook
option, remove the line:
UsesBuiltinHook/aut = "1"
from the server.ini
file.
Attaching to a Running Application with the Built-in Hook
It is also possible to use the built-in hook mechanism to attach to a running application (see Attaching to Running Applications for more details on attaching to a running application).
To make an application attachable with the built-in hook, you must call the Squish::allowAttaching function after the QApplication
has been created. The argument to this function is a port number that the application should listen on for a squishserver to connect to. The function is declared in qtbuiltinhook.h
.
Here is the standard pattern for making an application attachable:
#include <QApplication> #include "qtbuiltinhook.h" int main(int argc, char **argv) { QApplication app(argc, argv); Squish::allowAttaching(11233); //... return app.exec(); }
- Include the file
qtbuiltinhook.h
that is in Squish'sinclude
directory. - Make the application listen on port
11233
.
Rebuild the application with these changes to make it possible for Squish to attach to it. Now start the AUT using the start*aut program supplied with Squish (in the Squish tool's bin
directory):
startaut --uses-builtin-hook aut
This starts the AUT running and listening on the specified port, so you can now attach to it from within a test script. The next step is to register the AUT as an attachable AUT as described in Register the Attachable . See Attaching from a Script for details on how to attach to the application from a test script.
Warning: Troubleshooting Attachable AUTs
In some situations doing the above is not sufficient to make the AUT attachable. In such cases it is necessary to create or adjust up to four environment variables: SQUISH_PREFIX
, LD_LIBRARY_PATH
, DYLD_LIBRARY_PATH
, and PATH
.
In some situations, startaut
cannot be used—for example, if an application is downloaded and started via a web browser. In such cases the built-in hook can be made active by setting the SQUISH_PREFIX
environment variable to point to a Squish for Qt directory.
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.