Squish reference manual

In addition to the Squish documentation, froglogic also provides an online knowledge base of Squish -related hints, tips, tricks, and examples at kb. Each of these platforms has its own unique look and feel—right down to the ordering of buttons in dialogs or sheets, and in the case of macOS the arrangement of menus and menu items. Furthermore, the appearance of applications can vary depending on the theme being used.

In view of these differences—and the fact that the Squish IDE's continual development means that screenshots are not always of the most recent release—keep in mind that the Squish IDE screenshots shown in this manual may look different from the Squish IDE that you see running on your own computers.

This is nothing to worry about since it doesn't affect Squish 's functionality; but it does mean that sometimes when you look for a particular toolbar, dialog, or sheet button, it may not be in exactly the same place in your Squish IDE as shown in a screenshot.

Look and feel differences don't stop Squish from being able to do cross-platform testing. This is because Squish identifies GUI objects by their properties rather than by, say, their coordinates. This means that a Squish test suite that tests an application running on one platform can be used unchanged to test the same application running on another platform, even if say, the order of dialog buttons is different on the two platforms. Or, when you know what you're looking for—for example, a particular function—you can click the Search tab.

In the Search tab's Keywords editor enter all or part of the name of a function case is ignored and a list of relevant links will appear. Alt Modifier. The form shown here works for Python and JavaScript. For Perl and Ruby replace the period with two colons, e.

The mouseButton can be any one of: MouseButton. LeftButton , MouseButton. MiddleButton , MouseButton. Windows test suites also support two more possible mouse button specifiers, MouseButton. PrimaryButton and MouseButton. These values respect the global Windows setting which can be use to swap the mouse buttons. If the buttons are not swapped the default , the left button is the primary button.

Otherwise, the right button is the primary button. Many of the APIs' functions apply to particular objects, so being able to identify the object of interest is particularly important. Squish provides several naming schemes, but the ones normally used are symbolic names and real names. Symbolic names are the most robust in the face of AUT changes, but real names can sometimes be more convenient to use.

For example:. In practice it would be tedious to give every single widget a unique object name and currently only Qt supports it , so this approach is most often used when there are two or more identical widgets in the same form. For those toolkits that don't have object names we can use introspection when there are two or more identical widgets. Examples of both approaches are given in the User Guide Chapter 5.

The most common situation is where we need to identify unnamed objects. This can be done using symbolic names or by matching an object's unique set of property values.

This tool can provide an object's symbolic name and its property-based real name. Another approach is to create a dummy test, interact with the objects of interest and then look in Squish 's object map to see the names that Squish uses, and copy any that are needed. Here's an example that shows both approaches for finding an unnamed object of type QTextEdit.

The waitForObject function waits for the identified object to be ready visible and enabled and then returns a reference to it. On the whole it is best to use symbolic names since they are more robust in the face of AUT changes, since they only require us to update the Object Map Section 7.

Note that for most GUI toolkits the type property is mandatory when using real names. Squish objects blend in seamlessly with the scripting language's native objects. This means that you can use standard language features to construct objects of the wrapped types, invoke member functions, and get, set, and iterate over properties on these objects. Here are some simple examples; many more examples are shown in the User Guide Chapter 5.

For Tcl we must use the enum function to get enum values. See Tcl Notes Section 6. Object findObject objectName ;. This function finds and returns a reference to the object identified by the symbolic or real multi-property name objectName or raises a LookupError exception if no such object can be found. The given name can also be a native script dictionary resp. This function is best used for non-visible objects. For visible objects it is much better to use the waitForObject function instead.

This function finds and returns a list of object references identified by the symbolic or real multi-property name objectName. Because it can return multiple object references, the name must not contain the occurrence property. SequenceOfObjects object. This function takes an object reference as returned by the findObject function or by the waitForObject function , and returns a list of the object 's child objects.

The return type is scripting language-specific, e. Examples are given below. Test Cases that rely on the order of the children encountered in this list, may find that the order changes or even possibly, new children appear in the list due to many different factors, such as:. Object object. This function converts the given object to an object of the type specified by the typeName string.

A suitable object can be obtained using the waitForObject function or the findObject function. In this example, if variant is a variable of type QVariant and it holds a QFont object, the underlying QFont object will be returned. If the object is invalid or null or if the typeName is unrecognized or if the conversion isn't possible e.

This function can also do other kinds of conversions, e. See also, the cast function which can be used for downcasting which object. In Qt5, Squish can extract pointers to custom QObject -derived classes from QVariant and cast them to the correct type - provided the custom class is registered with QMetaType. The "magic" is to not object. This function creates a null pointer or object with the specified type as type. Boolean object. This function returns a true value if the object with the symbolic or real multi-property name objectName exists; otherwise it returns a false value.

If you know that a particular object exists and you just want to access it for example, to examine its properties or to perform an action on it or with it , then use the waitForObject function if the object is visible; or use the findObject function if the object is hidden.

This function takes an object reference as returned by the findObject function or by the waitForObject function , and returns the parent object. If the given object has no parent, the function returns a null value - the exact type of which depending on the scripting language i. None in Python, null in JavaScript, nil in Ruby etc. KeyValueMap object. This function takes an object reference as returned by the findObject function or by the waitForObject function , and returns a key—value map that holds all of the object 's properties.

The keys are property names and the values are the property values. For Tcl the data is written to an array whose name must be given as an additional parameter. The same array should not be used in a second or subsequent call unless you call array unset on it before each use.

ScreenRectangle object. This function takes an object reference as returned by the findObject function or by the waitForObject function , and returns the bounding rectangle for the object in screen coordinates. These values are identical to what Squish uses during object highlight.

The values may however not be identical to toolkit specific geometry information since Squish may further limit the global bounding rectangle to what is really visible on screen i. Image object. This function takes an object reference as returned by the findObject function or by the waitForObject function , and returns a screenshot of its current visual as an Image Object Section 6.

The screenshot behavior can be configured through entries passed via the optional parameterMap argument. The default value is 1 second to allow the AUT to react to the latest inputs and reach a stable state before taking a screenshot. Reducing it to 0 may be useful to improve the test execution time, especially in case of a series of consecutive grabScreenshot calls.

This function returns a list of all of the AUT's top-level objects. This function will perform a search of the template image as stored in imageFile on the display also showing the currently running application. On success the location of the found image is returned as a ScreenRectangle. Functions like mouseClick or tapObject can then emulate a user interaction on the detected location. The search for the sub-image is performed left to right, top to bottom.

The first successful match is returned. For selection of other matches use the occurrence parameter as described below. All available screens making up the desktop will be searched. At least on Windows and Xbased systems. For searches on multi-screen setup on macOS please inquire with technical support.

The search behavior can be configured through entries passed via the optional parameterMap argument. By default the first match with index 1 will be returned. Index values 2 and higher will select consecutive matches as far as available.

In this mode some differences between the template image and the desktop screenshot are allowed. The default value is the value of testSettings. A correlation higher than the threshold is considered a match against the template image. Usable values for this parameter usually fall between The default value is the value of the testSettings. This parameter is ignored if the tolerant parameter is set to false. In this mode the template image is expanded into a series of images of different sizes.

Those image are subsequently used as template images for the image search. The resized template image sizes will span between minScale and maxScale of the original image size.

This parameter is ignored if either the tolerant or the multiscale parameters are set to false. This function will perform a single check of the screen content only. If it fails to find the sub-image an exception will be thrown. A call is useful in case a the presence of the sub-image is almost certain or b a quick check of the presence is wanted. In all other cases the waitForImage function is preferred for timing-independent look-ups. The matching algorithm performs a pixel-by-pixel color value comparison.

In case a search region is specified as the last argument, the search is performed only within the area corresponding to it. It can also be a special string value "all", in which case all top-level objects are used.

The search region can also be an Image object. In such case no new screenshots are taken and the specified image is used instead. Currently it is not possible to limit the search scope to a portion of an Image object; please use the Image. String getOcrText [parameterMap] , [searchRegion] ;. This function will perform optical character recognition on the display also showing the currently running application and return all text lines.

The OCR will be performed over all available screens making up the desktop. Use an empty string to use the OCR engine defaults. This parameter is used only with engines that support profiles.

These options are passed to the OCR engine after loading the specified profiles. The source image is upscaled by that factor before it is passed to the OCR engine. The default value is 3. It can be set to a lower value to improve the OCR performance in case the text is rendered with a large font.

In case a search region is specified as the last argument, the OCR is performed only within the area corresponding to it. Currently it is not possible to limit the OCR scope to a portion of an Image object; please use the Image. This function will perform optical character recognition on the display also showing the currently running application and search for the specific text within the result set.

It will return a searchRegion object corresponding to the location of the text. By default the first text match with index 1 will be returned. This function will perform a single OCR of the screen content only. If it fails to find the specified text an exception will be thrown. A call is useful in case a the presence of the text is almost certain or b a quick check of the presence is wanted.

In all other cases the waitForOcrText function is preferred for timing-independent look-ups. It will return a sequence of ScreenRectangle objects corresponding to the locations of the specified text.

Boolean waitFor condition ;. The condition is a piece of code to evaluate, passed as a string or as a function reference, and that is expected to return a Boolean value. The waitFor function loops one or more times, and on each iteration it executes the condition code and reads its return value.

After each execution, if the condition code's return value is true , waitFor will finish and return true. Otherwise, the waitFor function will perform another iteration, that is, execute the condition code again, and again check its return value, repeating endlessly—or until the condition code returns true , in which case waitFor will finish and return true.

This function is designed as a quick and easy way to poll for a condition in the AUT, where each condition execution takes a very short time typically a fraction of a second , and always returns true or false.

This is useful if you want to synchronize your script execution to a certain state in the AUT. Boolean waitFor condition , timeoutMSec ;. If the condition code returned false , the waitFor function checks to see if the time it has been running has exceeded the timeoutMSec —if it has, waitFor finishes and returns false ; otherwise it does another iteration, starting with another execution of the condition code.

ApplicationContext waitForApplicationLaunch ;. Waits for a new application to start up, which Squish then hooks into. If the hooking succeeds it returns an ApplicationContext object representing the application that was started. This is used by Squish for test scripts which access multiple applications which are started by the AUT. See also, Application Context Section 6.

The optional parameter timeoutSecs an integer number of seconds can be specified to tell Squish how long it should be prepared to wait for the application to appear before throwing an error.

If specified, this value overrides squishrunner 's default AUT timeout. If not specified the squishserver 's default is used—this is 20 seconds, unless it has been changed; see Squish Server Settings dialog Section 8. Object waitForObject objectOrName ;.

Waits until the objectOrName object is accessible i. It returns a reference to the object if successful or raises a catchable LookupError exception on failure, i. The function waits for the time defined by the testSettings. This function is useful if you want to synchronize your script execution. This function is only suitable for objects that are or become visible; for non-visible objects consider using the waitForObjectExists function instead.

And if you only want to know if an object exists, use the object. Additional processing can be done on waited-for objects in a user-defined callback function. See waitUntilObjectReady for more details.

Waits until the objectOrName object exists. The given name can be a native script dictionary resp. This function is typically used to access items inside containers such as lists, tables, and trees.

In a tree, it can be a period. Java, Qt and Windows: The return value is a reference to the item. The reference can be used with other Squish functions.

Web and other Squish editions: The return value is a reference to the object identified by objectOrName not the item. The function raises a catchable LookupError exception on failure, i. Additional processing can be done on the object items before this function returns, by providing a user-defined callback function. See waitUntilObjectItemReady for details. This function waits for an image as specified by imageFile to appear on the screen, by repeatedly calling findImage until a timeout is reached.

In case of success, the location of the image as found on the screen will be returned as a ScreenRectangle. Interaction functions like mouseClick , doubleClick or tapObject can be used to click or tap on the detected location.

The behavior of the search can be customized through additional parameters passed to the optional parameterMap of key-value pairs, where a key can be one of these:. The default is 1 second. The default is 20 seconds. By default this function will repeatedly grab the screen content until successful or until 20 seconds have passed. Longer or shorter waiting periods can be set in milliseconds via a timeout value passed through the parameterMap.

In order to perform a single image search, use the findImage function. Since the Image object specified as the search region cannot possibly change overtime, this function will not perform the image search repetitively and will return the results immediately. The actual interval between separate OCR attempts is dependent on OCR engine performance, and may be significantly longer.

Since the Image object specified as the search region cannot possibly change overtime, this function will not perform the OCR repetitively and will return the results immediately. This function performs a mouse double click at the position specified by screenPoint or at the center of the rectangle specified by screenRectangle. Both positions are in screen global coordinates.

The optional modifierState and button arguments specify keyboard modifiers and the mouse button that are held down during the click. This function performs a key press of the specified key keyboard key.

This function performs a key release of the specified key keyboard key. This function performs a mouse click at the position specified by screenPoint or at the center of the rectangle specified by screenRectangle. This function moves the mouse to position x and y relative to the top-left of the objectOrName widget if one is specified, or relative to the current screen otherwise. If no coordinates are specified, the mouse is moved to the middle of the objectOrName widget.

This function is useful if you want to trigger events that need the mouse to be at a particular position. For example, tooltips normally only appear when the mouse is over a certain area. This function performs a mouse press.

All the parameters are optional excepting that either both or neither of the coordinates must be present. If x and y coordinates are given, the press takes place at those coordinates, either relative to the objectOrName object if one is specified, or relative to the current screen otherwise. If no coordinates are given the press takes place on the middle of the objectOrName object if one is specified, or wherever the mouse happens to be otherwise. By default MouseButton. LeftButton is used, but this can be changed by specifying the optional mouseButton argument.

Similarly a default modifier state of no modifiers is used, but this can be changed by specifying the modifierState argument. When executing tests on Windows systems, MouseButton. PrimaryButton is used by default instead of MouseButton. This means that Squish will perform a click with the right mouse button in case Windows was configured to have swapped mouse buttons.

There is a toolkit-specific version of this function that may have different arguments: mousePress Windows. This function performs a mouse release. If x and y coordinates are given, the release takes place at those coordinates, either relative to the objectOrName object if one is specified, or relative to the current screen otherwise.

If no coordinates are given the release takes place on the middle of the objectOrName object if one is specified, or wherever the mouse happens to be otherwise. There is a toolkit-specific version of this function that may have different arguments: mouseRelease Windows. This function performs a touch tap at the position specified by screenPoint or at the center of the rectangle specified by screenRectangle.

This function returns the object 's class name as a string. This function is only available to Python test scripts; for other script languages use the typeName function.

This function highlights the screen position of the object specified by objectOrName through a red rectangle. Such a visual confirmation can be useful if there is doubt about whether an object found via waitForObject , waitForImage and related functions is the correct object. The red overlay will remain on the screen for 3 seconds unless overridden by the optional timeout parameter. Boolean isNull object ;.

This function returns a true value if the object is null e. String typeName object ;. For objects that are created in test scripts, this is their actual type name. For widgets and other application objects, Squish tries to return the correct type name, and if that isn't possible, returns "Object", the name of Squish 's generic object type, instead.

JavaScript, Perl, Ruby, and Tcl scripts should always return the correct type name. Python scripts usually return "Object" for application objects, but Squish 's API for Python includes the className function, which returns the correct class name of the object it is given, whether that object is created in a test script or is an application object. This function will copy the file referenced by pathToFile into the test report directory specified when starting Squish and create an entry in the test report pointing to the file copy if the report generator supports this.

The optional message allows to specify a short description of the attachment and will be included in the report as well.

The pathToFile can specify the file to attach using an absolute or a relative path. In the case that a relative is being used it'll be appended to the current working directory of the script interpreter running the test.

Other generators can be used with test. The copied file will appear in an attachments subdirectory that is going to be inside a directory named after the testcase. In turn the testcase directory will be inside a directory named after the suite, which is placed in the test report directory. The name of the copied file will match the file name of the originally specified file. If a file of that name already exists in the report directory a number will be added to make the file name unique.

For report generators that do not require specifying a test report directory but rather take a file like xml2, xml or xmljunit you can either specify --resultdir when invoking squishrunner to specify the test report directory or Squish will fall back to generate the attachments directory inside the testcase that is currently being executed when test.

This function will create a screenshot of the desktop from the system where the currently active AUT is running and store that in the test report directory. In addition an entry is being logged in the test report indicating the path of the screenshot file as well as including the specified message.

The screenshot will be stored in the lossless PNG format under the same attachments subdirectory as files attached using the test. This API is a shorthand for test. This function will store the specified image in the test report directory. In addition an entry is being logged in the test report indicating the path of the image file as well as including the specified message. The image will be stored in the lossless PNG format under the same attachments subdirectory as files attached using the test.

Object cast object , type ;. Casts the object to the given type and returns a reference to that object, or to a new copy of the object if the object is of an immutable type. The desired type can be specified either by name as a string or by using a type object.

This is necessary because Squish implements its own int object in Python. This function makes it possible to downcast e. See also the object.

The compare, verify, and exception functions are used to record the results of tests applied to a running AUT in Squish 's test log as passes or fails. The other functions can be used to programmatically record any kind of test results in the test log.

See also, the Verification Point Creator view Section 8. This function grabs an image of the screen the AUT is running on and stores it on the computer where the Squish IDE or squishrunner is executing.

If no path is specified the file gets stored in the working directory of the squishrunner process. The default working directory of squishrunner is the path of the test case that it is currently executing. If a relative path is specified it is relative to the working directory of the squishrunner process. The filename should have a suffix denoting the image format to be used.

This function grabs a snapshot of an object and saves it to the specified file in the xml format. The object snapshot is a state of an object, including all of its properties and its children with children's properties. If a relative path of the snapshot is specified, it is relative to the working directory of the squishrunner process. What is actually saved in the snapshot can be customized by making changes to another.

With this, you can exclude certain classes or properties of classes, and decide if the real name or the symbolic name should be included in the output. Boolean test. This function compares value1 and value2 , and if they are equal, a test result of type PASS is added to the test log and this function returns a true value.

Otherwise a test result of type FAIL is added to the test log and a false value is returned. If the optional message parameter of type string—e. The testSettings. This function executes the code passed as a string in code , expecting it to raise an exception.

If an exception is raised a test result of type PASS is added to the test log and this function returns a true value. This function unconditionally adds a FAIL entry to Squish 's test log with the given message string, and with the detail string, if one is given.

This function unconditionally adds a FATAL entry to Squish 's test log with the given message string, and with the detail string, if one is given. This function unconditionally adds a LOG entry to Squish 's test log with the given message string, and with the detail string, if one is given. This function unconditionally adds a PASS entry to Squish 's test log with the given message string, and with the detail string, if one is given.

Since pass is a reserved word in Python, the Python version of this function is called test. This function returns the number of results of the given resultCategory of the current test case.

The resultCategory must be one of the strings: "errors" , "fails" , "fatals" , "passes" , "testcases" , "tests" , "warnings" , "xfails" , or "xpasses". This function evaluates the condition and if it evaluates to a true value e.

Otherwise a result of type FAIL is added to the test log. In either case the function returns the result of evaluating the condition , i. This function executes the verification point called name.

If the verification point's comparison succeeds, a test result of type PASS is added to the test log and this function returns a true value. Otherwise a result of type FAIL is added to the test log and a false value is returned. If the verification point refers to an object that is not found, the function will return a false value, and possibly pop up an object not found dialog, if Squish is configured that way.

In the event of a FAIL , the testcase proceeds to the next test statement unless squishrunner is configured to --abortOnFail. This function executes the verification point called name where comparison will be performed with the objectNameOrReference instead of an object present in the VP file.

If the test case logged verification failures before the skip, it is still considered failed. This function is used to handle expected failures in test scripts. To test for bugs that should be fixed one day. The 'expected fail' result is intended for cases where you know a comparison or verification will go wrong right now due to a bug in the AUT.

In test cases where you want to ensure that a property never has a certain value, we suggest using test. The Python version of this function is called test. This function is used to test for expected failures in test scripts. For handling of bugs that should be fixed one day. The function evaluates the condition and if it evaluates to a false value e. This function is used to test expected verification point failures. StackTrace test.

This function returns a list of stack frames representing the currently active function calls. The first element in the list contains information about the location of the test.

The last element in the list is usually the main function call. If the optional startFrameIndex parameter a number is given, the given number of most recent frames will be skipped. This is useful for retrieving stack traces from framework functions, in which case the stack trace should possibly not include the code internal to the framework itself.

If this parameter is not given it defaults to zero, i. If both startFrameIndex as well as maxFrameCount are given, the stack trace will be limited to maxFrameCount frames, i. This can improve performance for deeply nested script frameworks. These functions temporarily enforce that test results created by other Squish functions such as test.

The test. The same effect can be achieved by passing an optional argument 1. You can pass other values to reference other ancestor stack frames, e. Use the test. Note that the calls can be nested, i. Here are some examples; note how the test result entry triggered by the call to test. This is the default - test results are associated with the location of the respective test statement. Due to the fixateResultContext call, the test result generated by the test.

Omitting a call to test. On success a test result of type PASS is added to the test log and the function returns true. Otherwise a test result of type FAIL is added to the test log and the function returns false. The imageNotPresent variant of the function works exactly the same as imagePresent , except it waits for the image NOT to be found.

It can be used to verify the image absence. The first successful match is selected. By default the first match with index 1 will be selected.

Index values 2 and higher will select consecutive matches. By default this function will repeatedly grab the screen content until an image is found or until 20 seconds have passed.

Since the Image object specified as the search region cannot possibly change overtime, this function will not perform the image search repetitively and will return the result immediately.

If the specified text is present, a test result of type PASS is added to the test log and the function returns true. It can be used to verify the text absence. By default this function will repeatedly grab the screen content until the specified text is found or until 20 seconds have passed.

Some functions need to be called in pairs to work correctly. In order to ensure that this is the case even when script exceptions are raised or the control flow could bypass one of the statements by other means, e. Here are some examples for how to ensure that fixateResultContext and restoreResultContext always go together. These functions can be used to group test results into logical units. The Squish IDE will display result sections as a nested set of test results. Executing tests on the commandline will, except when the XML3 report generator is used, get log messages added to the test report whenever a section starts or ends.

Please see Ensuring that functions are always called pairwise Section 6. This function compares the expected file specified by expectedFilePath and compares it to the actual file specified by actualFilePath.

If they are equal a test result of type PASS is added to the test log and the function returns a true value. If the files are different a diff that shows which lines have changed is created which can be found in the test result message details.

The optional parameter options can be specified as a map or dictionary. So far the following options can be set:. The default is false. If they are equal, a test result of type PASS is added to the test log and this function returns a true value.

If the files are different the result message details will show in which line and for what reason the comparison failed. The default is true. If it is set to false all comments are compared.

This can be set to either preserve , normalize or trim. If this is set to preserve all whitespaces are kept, if this is set to normalize all whitespaces will be normalized and if this is set to trim whitespaces at the start and end of the text elements are removed. The default is normalize. If this is set to preserve all whitespaces are kept, if this is set to normalize all whitespaces will be normalized and if this is set to trim whitespaces at the start and end of the attribute values are removed.

The default is preserve. So if your windows change dramatically it just means that the Perspective changed; you can always use the Window menu to change back to the Perspective you want. Keep in mind that the Squish IDE is being continually developed: this means that some menus, menu items, and toolbar buttons may move or have different icons from those shown here, and also that more menu items and toolbar buttons may be added before this document is updated to cover them.

For the same reason some of the screenshots may not match those you see in your version of the Squish IDE. For example, the menubar, menus, and toolbars had several changes in Squish 4.