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();
}

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.

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:

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 platforms that don't support the preloading mechanism. It does not matter if you leave in this code on other platforms, since the the function is smart enough to do nothing if it isn't needed.

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.

15.11.2.2. 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 (Section 15.4.2.3)):

squishserver --config usesBuiltinHook aut

	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.

#include <QApplication>
#include "qtbuiltinhook.h" 

int main(int argc, char **argv)
{
    QApplication app(argc, argv);
    Squish::allowAttaching(11233); 
    //...
    return app.exec();
}

startaut --uses-builtin-hook aut