This dialog is shown when the user selects Help - Collect Support Information....

Generally, when you run into an unexpected problem with Squish and need help from support, you will be asked to send a support information zip file that can be created from here.

The Collect Support Information dialog

After clicking Ok, you will be shown a dialog that explains what is in the zip file. From here, you can click Ok to dismiss the dialog, or Open Support Request... which will open the Squish Support Request Wizard (Section 8.3.23) and guide you through the process of opening a support ticket.

Collecting Finished dialog

This dialog is used to customize a predefined or custom perspective—for example, customizing some of the toolbars, menus, and submenus that are visible when the perspective is shown. The dialog is invoked by clicking Window|Customize Perspective. (To change the views shown in a perspective simply close any you don't want and add new ones using the Show View action (Section 8.1.1.62).)

The Customize Perspective dialog

Use the Tool Bar Visibility tab to hide or show toolbars and individual toolbar buttons within toolbars. Similarly, use the Menu Visibility tab to hide or show menus and individual menu options within menus. The Command Groups Availability tab is for advanced users and is not documented in this manual. The Shortcuts tab can be used to add keyboard shortcut actions to submenus.

This modeless dialog is used to find and optionally replace text in the active editable window. The dialog is invoked by clicking Edit|Find and Replace or by pressing Ctrl+F.

The Find/Replace dialog

Be aware that even if you set Scope to be All the search will only be made from the current cursor position Forward (or Backward depending on the Direction setting) to the end (or start) of the file—unless you check the Wrap search checkbox. Searching is case insensitive by default but this can be changed by checking the Case sensitive checkbox. If the Regular expressions checkbox is checked the Find text can be a regex using Java's regular expression syntax.

This dialog automatically shows up during the execution of tests in the Squish IDE if a findImage function fails to find a specific occurrence of the template image, or waitForImage command runs into the specified (or default) timeout.

Image Not Found dialog

The dialog shows the template image(s) that were not found on the desktop screenshot, and the latest desktop screenshot used for image search. The dialog then allows the user to pick from a variety of options to try to solve the error.

The Update Image... button opens the Image Selection Editor view (Section 8.2.14), where a new image can be selected. New image will replace the failed image selected in the Image Not Found dialog.

The Add New Image... button opens the Image Selection Editor view (Section 8.2.14), where a new image can be selected. Selected image will added to the image group that was not found on the desktop. In case a single image was used in the image search, it will be converted to a group.

The Adjust Search Parameters button opens the Image Search Preview dialog (Section 8.3.6) that allows adjusting image search parameters like the tolerance and observing the results.

The Throw Error button will let the test execution continue and generate the appropriate error. Letting the execution continue at this point may end the test unless the test script catches the lookup error to recover from this itself.

The Retry button will re-execute the image search. It can be useful to determine if the image search error is triggered because the image takes longer to appear on the screen than the timeout. If the user introduced changes to the search image(s), the new template images will be used.

The Do not show this dialog again checkbox can be used together with the Throw Error button to indicate that the dialog should not be shown on any future lookup errors. This means the dialog will not be shown anymore until the user re-enables it through the Playback preferences of the Squish IDE.

The Attempt to fix image search errors automatically used together with the Retry button will cause the IDE to attempt to fix any subsequent image search errors by adjusting the default tolerance and image resize range.

This dialog automatically shows up during the execution of tests in the Squish IDE if a findOcrText function fails to find a specific occurrence of the search text, or waitForOcrText command runs into the specified (or default) timeout.

Text Not Found dialog

The dialog shows the search text that were not found on the desktop screenshot, and the latest desktop screenshot used for text search. The dialog then allows the user to pick from a variety of options to try to solve the error.

The Adjust Search Parameters button opens the OCR Selection dialog (Section 8.3.15) that allows adjusting text search parameters like the language hint and observing the results.

The Throw Error button will let the test execution continue and generate the appropriate error. Letting the execution continue at this point may end the test unless the test script catches the lookup error to recover from this itself.

The Retry button will re-execute the text search. It can be useful to determine if the text search error is triggered because the image takes longer to appear on the screen than the timeout.

The Do not show this dialog again checkbox can be used together with the Throw Error button to indicate that the dialog should not be shown on any future lookup errors. This means the dialog will not be shown anymore until the user re-enables it through the Playback preferences of the Squish IDE.

The Image Search Preview dialog can be used to adjust the image search parameters and observe the search results in realtime. It is useful when an "exact" match of every pixel is not to be expected, and we wish to perform a fuzzy match in order to find the image.

Image Search Preview dialog

The Refresh can be used to update the desktop screenshot displayed in the preview pane. The dialog and any other Squish IDE windows will be temporarily hidden for the purpose of the screenshot.

The image search options correspond to the parameters passed to the findImage and waitForImage functions. Adjustments to the values of the parameters triggers re-computation of the image search results visible in the preview pane.

If the search option values are adjusted to a sensible default for other image searches, you can Apply the settings as the Default values for new test suites, or Statements in the current test script.

This dialog can be popped up by invoking the Import Test Resource action (Section 8.1.1.19). It is used to import scripts, test data, and verification points into a test case or a test suite.

The Import Squish Resource dialog

The File to Import should be chosen by clicking the Browse button and navigating to it using the Open File dialog that pops up. The file should either be a test data file in .tsv (tab-separated values format), .csv (comma-separated values format), .xls or .xlsx (Microsoft® Excel™ spreadsheet format), or a test script file (e.g., a file containing functions you want all the test suite's test cases to be able to share using the source function). If you import a test script, it must be in the same scripting language as that used by the test suite's test cases.

Once the file has been chosen you must tell the Squish IDE whether it is test data or a test script by setting the Import As combobox's value appropriately.

With any resource you have two choices as to its location: it can either be stored within a particular test case or it can be stored in a place that is accessible to all the test suite's test scripts. Unless the test data or test script resource really is specific to one particular test case it is almost always more convenient to store it so that it can be shared by the entire test suite. If you just want to store the data or script in the current test case check the Copy to Test Case radio button. And if you want the data or script to be shared by all the test cases check the Copy to Test Suite for sharing radio button. Then, in either case, click the Finish button.

See also the New Squish Test Data dialog (Section 8.3.11) and the New Squish Test Script dialog (Section 8.3.12).

The dialog is used to select an image file (or create a new one) for insertion of an image-based script function. The dialog is shown when choosing the Insert > mouseClick(<Image>) action (Section 8.1.3.8), Insert > doubleClick(<Image>) action (Section 8.1.3.9) or Insert > tapObject(<Image>) action (Section 8.1.3.10) from the Control Bar. However, if no images have been stored in the test suite we are taken to the Image Selection Editor view (Section 8.2.14) directly.

The Search Image Selection view

The dialog displays the list of available images and image groups stored in the test suite's shared/searchImages or the current test case's searchImages/ directory. The image groups are distinguished by a folder icon overlay. Double clicking on an image group displays its contents. The path to the currently displayed group is displayed in the top frame. Clicking on the group buttons returns the view to the respective image group or to the root of the hierarchy.

Upon selection of one of the existing images the Insert <action> will first attempt to execute the selection action and (upon sucess) insert the respective script statement into the test script.

In case none of the existing images fits the need clicking New Image... will perform a screen grab and take us to the Image Selection Editor view (Section 8.2.14).

When deciding against the insertion of an image-based script statement the Cancel button will take us back into the main recording mode.

This dialog is used to import a new shared Squish test script or test data file, or to create a new test case within the current test suite, or to create a new test suite. The dialog can be invoked by clicking the main window's New toolbar button or by pressing Ctrl+N. (Note that there are more convenient direct menu options for all of these—apart from creating a new test case from a template.)

The New dialog

Once the wizard is visible click the type of the thing you want to create, then click the Next button.

If you click “Squish Script File” the New Squish Test Script dialog (Section 8.3.12) will replace the "New" dialog. This dialog is used to add a shared test script file (e.g., a script that contains functions you want to share amongst your test cases).

If you click “Squish Test Case” the New Squish Test Case wizard (Section 8.3.10) will replace the "New" dialog. This dialog is used to create a new empty test case.

If you click “Squish Test Case from Template” the Create Test Case from Template dialog will replace the "New" dialog. This dialog is used to create a new test case based on the specified template. (Note that there are no default templates, so you will need to create at least one template to be able to use this option. A Test Case Template can be created using the Test Suites view (Section 8.2.19)'s Test Cases list's context menu.)

If you click “Squish Test Data File” the New Squish Test Data dialog (Section 8.3.11) will replace the "New" dialog. This dialog is used to import shared test data that can be used by the test suite's test cases.

If you click “Squish Test Suite” the New Squish Test Suite wizard (Section 8.3.13) will replace the "New" dialog. This dialog is used to create a new test suite.

This dialog is used to create a new test case within the current test suite. It can be invoked by clicking the Test Suites view (Section 8.2.19)'s New Test Case toolbar button or by clicking File|New Test Case or File|New|New Test Case, or via the New dialog (Section 8.3.9). (See also the New Test Case action (Section 8.1.1.27).)

The New Squish Test Case wizard

Once the wizard has appeared, you can choose between a Script Test Case or a BDD Test Case (.feature) file.

Enter the name of the new test case and click the Finish button to finish. At this point an empty test case with the given name will be created (prefixed with tst_ if it isn't already), ready for a new test script to be entered or recorded.

This dialog is used to add test data for a particular test case or to be shared by an entire test suite. It can be invoked by clicking File|New|Squish Test Data, or via the New dialog (Section 8.3.9).

The New Squish Test Data dialog

The Test Data Filename should be entered first. The filename should be in .tsv (tab-separated values format) or .csv (comma-separated values format). If entering the filename directly isn't convenient because you want to pick the file using a file chooser dialog, close this dialog and open the Import Squish Resource dialog (Section 8.3.7) instead.

With any resource you have two choices as to its location: it can either be stored within a particular test case or it can be stored in a place that is accessible to all the test suite's test scripts. Unless the test data really is specific to one particular test case it is almost always more convenient to store it so that it can be shared by the entire test suite. If you just want to copy the data into the current test case check the Create file in Test Case radio button. And if you want to copy the data so that it can be shared by all the test cases check the Create shared File in Test Suite radio button. Then, in either case, click the Finish button.

See also the New Squish Test Script dialog (Section 8.3.12).

This dialog is used to add a test script (e.g., containing supporting functions) for a particular test case or to be shared by an entire test suite. It can be invoked by clicking File|New|Squish Script File, or via the New dialog (Section 8.3.9).

The New Squish Test Script dialog

The Test Script Filename should be entered first. The filename should be for the same scripting language as that used for the test suite's test cases. If entering the filename directly isn't convenient because you want to pick the file using a file chooser dialog, close this dialog and open the Import Squish Resource dialog (Section 8.3.7) instead.

With any resource you have two choices as to its location: it can either be stored within a particular test case or it can be stored in a place that is accessible to all the test suite's test scripts. Unless the test script really is specific to one particular test case it is almost always more convenient to store it so that it can be shared by the entire test suite. If you just want to copy the test script into the current test case check the Create file in Test Case radio button. And if you want to copy the test script so that it can be shared by all the test cases check the Create shared File in Test Suite radio button. Then, in either case, click the Finish button.

See also the New Squish Test Data dialog (Section 8.3.11).

This dialog is used to creat a new test suite. It is invoked by clicking the Test Suites view (Section 8.2.19)'s New Test Suite toolbar button or by clicking File|New Test Suite or File|New|New Test Suite, or via the New dialog (Section 8.3.9). (See also, the New Test Suite action (Section 8.1.1.28).)

The New Squish Suite wizard

The use of this wizard is described in the tutorials:

This dialog automatically shows up during the execution of tests in the Squish IDE if a waitForObject command runs into the specified (or default) timeout.

The Object Not Found dialog

The dialog shows the error message generated for the lookup error and the object name for which the lookup was executed. The dialog then allows the user to pick from a variety of options to try to solve the lookup error

The Pick New Object button lets you to pick an object from the AUT to compare that object's properties against the ones used for the name so far. This lets you investigate how the properties have changed, and whether they caused the lookup error.

The Object Not Found dialog after picking the object

The Throw Error button will let the test execution continue and generate the appropriate error. Letting the execution continue at this point may end the test unless the test script catches the lookup error to recover from this itself.

The Debug button will close the dialog and open the corresponding name in the object map editor. The Squish IDE is now in the Squish Test Debugging Perspective (Section 8.1.2.3) so all the usual debugging tools can be used to further examine the problem.

The Retry button will re-execute the object lookup. It will use the old name if the user did not pick a new object, which can be useful to determine if the lookup error is triggered because the object takes longer to become ready than the default timeout. If the user picked a new object the new object name will be stored under the symbolic name in the object map and the lookup will be performed with that new name.

The checkbox Do not show this dialog again can used together with the Throw Error button to indicate that the dialog should not be shown on any future lookup errors. This means the dialog will not be shown anymore until the user re-enables it through the Playback preferences of the Squish IDE.

	Note
	The Pick New Object button is only available if the object lookup error happened for a symbolic name found in the object map. If the symbolic or real name is assembled inside the test script this option is disabled as the Squish IDE cannot properly update the object map.

The OCR selection dialog shows a desktop screenshot captured for optical character recognition (OCR) and the recognition results. It allows the user to free-draw a slection rectangle on the screenshot. If any of the words in the OCR result are completely within the selection, it will appear in the Matches in selection: list. Any of the matches on the list can be selected - the related text will be displayed in the Search text: field. The search text can be freely adjusted. The matches corresponding to the current search text will be highlighted on the desktop screenshot. If any of such matches is entirely within the selection, the Insert will become active, allowing the OCR instruction to be performed.

The OCR Selection dialog during instruction recording

The Refresh button allows to update the current screenshot with the current desktop contents. The Squish IDE will be hidden for the duration of the screenshot.

The Language combo box allows selection of a language hint for the OCR engine.

This dialog is used to open a particular perspective. It is invoked by the Open Perspective action (Section 8.1.1.35).

The Open Perspective dialog

By default the Squish IDE has three perspectives (see Perspectives (Section 8.1.2)) each of which can be opened directly using the appropriate action—Squish Test Management Perspective action (Section 8.1.1.69), Squish Spy Perspective action (Section 8.1.1.67), and Squish Test De­bug­ging Per­spec­tive action (Section 8.1.1.68). Note that in practice is not necessary to open any of these perspectives manually since the Squish IDE automatically opens the right one depending on context. So this dialog is only really useful if you have created your own custom perspectives and want to choose one of them. (See the Customize Perspective dialog (Section 8.3.2).)

This dialog is used to set the Squish IDE's global preferences. It is invoked by the Preferences action (Section 8.1.1.37).

The Preferences dialog

The screenshot above shows the dialog's first section's first pane. The dialog has a lot of sections (“Dynamic Languages”, “General”, etc.), and most of thes have several panes. For example, the Dynamic Languages section has its own pane plus “Debug” and “Validators” child panes. Some child panes have their own child panes and so on. Most of the dialog's panes are inherited from Eclipse and most of them are rarely used. Here we will only document the most important panes, and within them the most important options.

In general, all the panes have a Restore Defaults button which restore's the panes's settings to their defaults and an Apply button which applies any changes you have made. If you make a mistake and don't want to restore the defaults (because your previous non-default settings are what you want), simply click the dialog's Cancel button—but note that this will not revert your changes if you clicked the Apply button. To accept your changes click the OK button.

8.3.17.1. Dynamic Languages pane

The Dynamic Languages pane is used to set various “DLTK” (Dynamic Language ToolKit) settings.

The Preferences dialog Dynamic Languages pane

Probably the only interesting setting is the Report problems as you type checkbox. If this is checked syntax errors are highlighted as you edit (and also indicated in the line numbers margin).

The Dynamic Languages pane has two child panes, Debug and Validators. These are very rarely needed and are not documented here. (Note that the Dynamic Languages Debug pane is not concerned with debugging test scripts.)

8.3.17.2. General pane

The General pane is used to set Eclipse settings. This pane has many child panes (some of which have their own child panes and so on).

The Preferences dialog General pane

Probably the most interesting setting is the Open mode. Squish defaults to Double click mode which means that you have to double-click test cases to get their code to appear in a code editor and so on. Setting the mode to Single click can save a lot of needless mouse clicking.

8.3.17.2.1. General pane's child panes

The General pane has many child panes. Here will will merely mention those that have settings that are likely to be of interest.

The Appearance pane has a Colors and Fonts child pane in which it is possible to customize the colors and fonts used by the Squish IDE and in particular by the Editor view (Section 8.2.6)s. To change the fonts, expand the Colors and Fonts pane's tree view's Basic item; the last two items concern text fonts: click one of these and then click the Edit button to set the font. Usually it is best to set both fonts to be the same. The same tree view can be used to set various colors—simply click the color of interest and then click the Edit button to choose a new color. There are other top-level items in the tree such as Debug, Dynamic Languages, and so on, so you can customize fonts and colors in very fine detail if you wish. The Appearance pane also has a Label Decorations child pane, but this is not currently used by the Squish IDE.

The Content Types pane can be used to set up file type associations. For example, Squish's non-scriptified verification points (such as screenshot verifications) are recorded in an XML-format file. If you wanted to use a custom file extention for such files you could add a file association in this pane. To do this, navigate in the Content types tree to the Text item then inside that tem to the XML item and then inside that item to the Verification Point item. (It is also possible to specify a default encoding but we recommend always using UTF-8 which is the default.)

The Editors pane and its child panes can be used to set up some general and some language-specific editing preferences. The Editors pane itself can be used to set the number of recently opened files that are available from the File menu, and to restore (or not) editor state when the Squish IDE is started up. The File Associations child pane can be used to associate file types with particular editors. For example, to make the Squish IDE open .pyw files using its Python editor, click the File types Add button (the top-most Add button) and enter a file type of *.pyw. Then click the new *.pyw File types entry if it isn't already selected and click the Associated editors Add button and choose the Python Source Editor.

The Editors pane's Text Editors child pane itself has a number of options, plus its own child panes. Use the Text Editors pane to customize general editing features such as the undo history size, the displayed tab width, whether to show line numbers, and so on. It is also possible to customize a limited range of colors here too. The child panes provide means of customizing the cursor (in the Accessibility pane) and the code annotations (in the Annotations pane). There are also some other rarely used child panes.

The Editors pane has one other direct child pane, Keys. This can be used to change the Squish IDE's keyboard shortcuts. Of course, if the shortcuts are changed this will invalidate some or all of those shown in this manual's Keyboard Shortcuts (Section 8.4) section.

The Perspectives pane is used to control some of the high level behavior of perspectives, such as whether a newly opened perspective replaces the current perspective (the default) or appears in a new window.

The Search pane is used to control some general features that apply to the Search view (Section 8.2.15).

The Workspace pane and its child panes control some aspects of the Squish IDE's behavior such as the automatic save interval and the default text encoding. Squish always and only uses the UTF-8 encoding so this setting should never be changed. Of the Workspace pane's child panes, the Build Order pane isn't used by Squish, and the Linked Resources pane's Enable linked resources checkbox must be checked—or the Squish IDE simply won't work properly. The Local History pane can be used to control a certain amount of undo history—even between sessions.

8.3.17.7. Squish pane

The Squish pane and its child panes are used to control various Squish-specific settings.

The Preferences dialog Squish pane

The Squish pane itself shows the Squish tools folder being used by the Squish IDE. This folder can easily be changed by navigating to another folder in the tree. This is useful when you have AUTs that use different GUI toolkits and want to switch between toolkits while using the Squish IDE.

8.3.17.7.1. Squish Preferences Child Panes

The Squish pane has several children: Application Behavior, Browser, Logging, Playback, Recording, Remote Testing, and Test Creation, all of which we will briefly describe here.

The Application Behavior pane is used to set how long Squish should wait for an AUT to start up before giving up and how long Squish should wait for any given response from the AUT. (The response time can also be set using the squishrunner's or squishserver's setResponseTimeout option (see Configuring squishrunner (Section 7.4.3.27) or Configuring squishserver (Section 7.4.4.3)). (From Squish 4.2, the Application Behavior pane is in the Squish Server Settings dialog (Section 8.3.22), not the Preferences dialog.)

The Browser pane is only relevant to those testing web applications since it is used to set the browser to use for web testing. (From Squish 4.2, the Browser pane is in the Squish Server Settings dialog (Section 8.3.22), not the Preferences dialog.)

The Logging pane provides some settings to achieve finer control over logging. (Note that the IDE Internal Logging Level affects only the Squish IDE's internal log. Occassionally froglogic's support staff may ask you to set its level to Verbose when trying to help solve a problem that you have encountered.)

The Playback Preferences pane

The OCR pane allows to set the preferences for the supported OCR engines. It includes the OCR engine used by default and authentication keys for online engines. The OCR settings can be edited without help of the Squish IDE in the ocr.ini (Section 7.6.1.2) file.

The OCR Preferences pane

The Playback pane has the following options:

• Snooze Factor: With this, you can uniformly speed up or slow down recordings that contain calls to snooze by a factor of your choice.

• The response to lookup errors can also be configured from this pane. Test execution can be halted when Squish fails to find an object, or it can show the Object Not Found dialog (Section 8.3.14).

	Object Not Found debugging
	The Object Not Found dialog (Section 8.3.14) will not be shown if the testSettings.objectNotFoundDebugging is set to false in the test script or on the Test Settings (Section 8.2.16.4) page.

The Recording Preferences pane

The Recording pane is used to control how Squish records tests. You can configure the following things from here:

• For Object Synchronization, we have 2 options: Based on Object Existence, or Based on Time During Recording. The default, Object Existance, means Squish uses waitFor functions such as the waitForObject function for synchronization. If you choose to use Based on Time During Recording, Squish will record calls to snooze rather than to the waitFor functions, and playback speed will be roughly the same as the recording.

• Compress Events is an option that is on by default, and the checkbox has no effect except on Qt Widgets. Disabling it means that Squish will record test cases with intermediate mouse hover and mouse move events. This could lead to recorded test scripts having many more lines than with event compression on.

The Remote Testing pane is used to control which computer tests should be executed on. The default settings tell the Squish IDE to start a local squishserver whenever necessary (i.e., to record or play back a test), on Squish's default port. If you want to run the squishserver on a remote machine you can enter the remote machine's hostname and the port to use. See Distributed Tests (Section 7.1.2) for more about this topic.

The Test Creation pane is used to specify the Test Case Template directory and the Default scripting language to use for new test suites (which can be overridden when a new test suite is created of course). A Test Case Template can be created using the Test Suites view (Section 8.2.19)'s Test Cases list's context menu; see also Testcase Templates (Section 7.14).

This dialog is used to operate on the test system remotely. The central widget on the dialog displays the current content of the desktop on the remote system. All input actions performed on the central widget are forwarded to and replayed on the remote test system.

The Remote Control dialog

The dialog features a toolbar with a number of controls which can be used to adjust the dialogs behavior. The function of each of them is described below.

The Pause button can be used to freeze-frame the video stream. Paused remote control window does not update the screen contents captured on the remote system and does not replay the user inputs. Clicking the Pause once again restores the normal operation of the Remote Control dialog.

	Note
	In case the video transmission is interrupted due to eg. networking problems, the Pause becomes automatically selected. You can un-select the Pause button to establish a new connection.

The Disable Inputs button can be used to disable the user inputs forwarding. When enabled the Remote Control dialog functions in view-only mode. It can be useful to avoid interference with the execution of a remote test case which is sensitive to the position of the cursor.

The Remote Keymap button can be toggled to switch the key-press handling mode. In the remote-keymap mode the keys are forwarded as key codes and interpreted on the target operating system using its current keyboard map. In the local-keymap mode the keys are interpreted as symbols by the IDE using local keyboard map and forwarded as symbols.

Since the Squish IDE is designed to run on desktop systems which rarely use a touchscreen, sending touch inputs to the remote system is not normally possible. The Convert Mouse Inputs to Touch button can be toggled to enforce conversion of all the pointer inputs to touch on the remote system.

Some embedded and mobile devices offer additional controls which do not map to a regular PC keyboard - eg. volume buttons on a side of a smartphone. In case Squish is able to detect such keys, it will be listed in the menu under the Extra Keys button. The menu can be used to activate the buttons on the remote device.

The FPS Limit combo box can be used to limit the video transmission framerate. It can be used to avoid saturation of the network connection.

This dialog is used to compare expected and actual screenshots and to configure how screenshot comparisons work on a per-screenshot basis. It is invoked by right-clicking a failed screenshot verification in the Test Results view (Section 8.2.18) to pop up the context menu and then choosing the context menu's View Differences menu item. (See also, Setting Masks (Section 8.3.19.2) for another way to invoke the dialog.)

The Screenshot Verification Point dialog

The dialog has some controls that apply generally: these are shown along the bottom and consist of zoom in and zoom out buttons, a restore to original size button, a button to show or hide the mask, a button to show or hide highlighting (i.e., show or hide a red outline around differences), and a button to pop up a color chooser dialog to choose the highlighting line color. Then there is a Save button to save the settings for the current screenshot, and a Cancel button for closing the dialog without saving any changes.

The dialog's first tab (Differences) shows the difference between the expected and actual image. This tab offers four different ways to view the differences, with the default being Flicker view where the expected and actual images are shown alternately (and with differences outlined in red). The flicker speed can be set using the control on the right.

The Differences tab's Subtract view shows the differences by removing all the common pixels and just leaving those that differ between the two images. The way the subtraction works can be influenced by changing the HSV (Hue, Saturation, Value) color settings, and by checking or unchecking the Invert checkbox.

The Differences tab's Gray Diff view shows the differences by removing all the common pixels and just leaving those that differ between the two images. The way the differencing works can be influenced by changing the Contrast setting, and by checking or unchecking the Invert checkbox.

The Differences tab's Split View shows the left half of the expected image and the right half of the actual image with a vertical slider inbetween which can be used to vary the proportions to show more of one and less of the other.

The dialog's Mask tab shows the expected and actual images. It also provides Mask Tools (in the form of buttons at the right hand side of the dialog) for Add Positive Mask, Add Negative Mask, Mask Highlighted Differences, and Remove Mask. Most of these buttons are only enabled if the global Show/Hide Mask toggle toolbutton is pressed.

Add Positive Mask and Add Negative Mask allow you to mark a rectangular region of the expected image, marking it to be either an interesting area, or an uninteresting one (for the purposes of verification).

Mask Highlighted Differences makes sense only if there is an actual image to compare with the expected one, and they differ somehow. Then, clicking this button will will highlight and create a mask based on those differences.

The dialog's Comparison Mode tab is used to set the comparison mode. By default Strict mode is used which does a straight pixel-by-pixel comparison. If Strict mode is too strict there more tolerant modes available as documented below.

8.3.19.1. Screenshot Comparison Modes

8.3.19.1.1. Strict Comparison Mode

The Strict mode is a pixel by pixel comparison which offers no additional configuration options:

The Strict Comparison Mode

Note that pixel differences can occur which are not noticeable by the human eye due to various factors (graphics card drivers and hardware, operating system, anti-aliasing, etc.) which makes the "Strict" mode unsuitable at times.

8.3.19.1.2. Fuzzy Pixel Comparison Mode

The Pixel comparison mode compares the color of corresponding pixels of two images having the same dimensions.

It presents the images differences in percentage. For example, a difference of 10% means that 10% of the pixels are different.

The algorithm has a Allowed failure threshold parameter that defines the criterion by which images are considered to be equal. Therefore, for the example of 10% different pixels, a threshold of 11% would consider both images to be equal:

The fuzzy Pixel Comparison Mode

The Max. Color Difference parameter is useful when you compare images that have different shades (not detectable by eye). This can happen to screenshots that are taken on machines that have different video adapters. The screenshots look very similar and you want to ignore tiny color differences they have.

Technically speaking, Max. Color Difference is the distance between two colors in 3D (RGB) color space (also see Euclidean distance).

For example you have two pixels with the following colors: (0, 0, 0) and (1, 1, 1) - one is absolutely black and another is almost black (you cannot distinguish their colors by eye). The difference between these two colors can be calculated with the following formula:

diff = sqrt((r2 - r1)^2 + (g2 - g1)^2 + (b2 - b1)^2)

Here r, g and b are red, green and blue color component values. So for our example the calculation would be:

diff = sqrt(1 + 1 + 1) = ~1.73

Also, the color difference between black and white colors is ~441.67. So, if you want to compare solid black image with white one and set the Max Color Difference to be 441.67, result will be positive, i.e. images match.

In the Test Results view you may find this additional information in failed screenshots:

...(difference: 0.7976%, max. color difference: 80.6040)

The “difference: 0.7976%” part denotes the number of pixels that are different in percent. In this example it is 0.7976% and not 79.76%, i.e. the relative number is very small, less than one percent. For example, if you compare images of 10x10px, and only one pixel is different, you will get 1% difference.

The “max. color difference: 80.6040” part denotes the largest pixel color difference - in this case 80.6040. So if you set Max Color Difference to be 81, your test will pass, because all the pixels that failed previously will be considered equal then.

8.3.19.1.3. Histogram Comparison Mode

Histogram mode is based on comparing image color histograms. It is useful for cases when images are resized/scaled or rotated, so that their color profile remains the same or is not changed much:

The Histogram Comparison Mode

How it works:

• Divide the color range (0-255) of each color component (RGB) of every pixel by the number of Bins (or baskets) and calculate the number of pixels that fall into each bin based on their color characteristics.

• Divide the total number of pixels in the image by the number of pixels in each bin to get "normalized values" (which allows comparison even if they have different sizes). These respective values are put back into the corresponding bins.

• The values of all corresponding bins are subtracted from another and the resulting values summed up. This value represents the difference of the images.

This mode lets you configure the number of Bins and Allowed failures (threshold in percent), which represents the maximum difference between two images for which they are still considered to be "equal".

8.3.19.1.4. Correlation Comparison Mode

The Correlation mode measures the similarity between two images as a statistical "correlation" coefficient based on functions originally stemming from the signal processing domain. The degree of similarity will be given in a percentage whereas 0% could roughly be labeled as "no similarity" and 100% as "perfect similarity".

The comparison is done based on gray values after mapping images of different sizes to the same scale. Unlike the Strict Comparison mode, this mode is therefore potentially able to cope with screenshots of applications running on systems with different screen resolutions.

The Correlation Comparison Mode

Use the Threshold configuration parameter to set the minimum correlation coefficient expected to consider the images to be equal. Two sets of sample images are given below to convey an assessment of calculated correlation values:

1. The correlation between and is 99.4614%. Note the different size and missing keyboard accelerator of the right button.

2. The correlation between and is 13.8309%. The screenshots have not much in common besides a few bright pixels in the center.

8.3.19.2. Setting Masks

When comparing screenshots, it is possible that the expected image contains more information than we need in our verification. We can mask parts of this image by either creating a Positive Mask, where the region outside the mask is ignored, or a Negative Mask, where the region inside the mask is ignored. The masking is done before the images are compared.

It is possible to set the Mask for a screenshot verification point before running a test (or between test runs), or when there is no failed screenshot test in the Test Results view (Section 8.2.18) (so no View Differences context menu item). This is done by clicking the VPs tab in the Test Suites view (Section 8.2.19)'s Test Case Resources list and then clicking (or double-clicking depending on your settings) the image verification point whose Mask you want to modify. This will result in the Verification Point being shown, along with a tiny Edit Verification Point button. Click this button to invoke the Screenshot Verification Point dialog. The dialog will pop up with only two tabs, Mask and Comparison Mode—the Differences tab does not appear because the only image available is the expected image. The Mask tab can be selected, to see a GUI like the following screenshot.

Editing Masks in Screenshot VPs

From here, we can insert, modify and remove positive and negative masks. A Positive Mask appears transparent, but the region outside the rectangle is marked red. A Negative Mask appears as a blue rectangle. It does not make sense to have both kinds of masks in the same verification point, unless they overlap somehow.

This dialog is used to perform sophisticated searches across files. It is invoked by using the Search action (Section 8.1.1.59). (If you just want to do a simple find or find and replace in an Editor view (Section 8.2.6) use the Find and Replace action (Section 8.1.1.16) instead.)

The Search dialog

This dialog has several tabs but we will only very briefly describe the File Search tab (which is the one shown by default). The first combobox is used to specify the text to search for. The combobox keeps a record of texts used this session so it is easy to drop down and pick a previous search text. By default the search uses very simple glob-style wildcards, but you can use full regular expressions and control case sensitivity using the appropriate checkboxes if you wish. The File name patterns combobox can be used to restrict the names of the files that are searched in. For example, if your scripting language is Python, you could set the pattern to be “*.py” so that only Python files are searched. The dialog has some other more advanced settings, and can even be used to replace the matching text across files, but these features are not covered here. After performing a search a Search view (Section 8.2.15) appears in the current perspective showing a tree view of the files searched and the line numbers within them where the search text matched.

The other tabs are all scripting-language-specific. They allow you to search for text in all the files containing source code in the tab's scripting language (e.g., all the JavaScript files or all Python files), and where the search text matches the name of a type (class), method (or function), or field (attribute).

This dialog is used to open a view that isn't already open. It can be invoked using the Show View action (Section 8.1.1.62). (See also, the Show View Menu action (Section 8.1.1.63).)

The Show View dialog

The Squish IDE provides so many views that the dialog shows them in a tree view grouped by category. Views that are already visible are shown grayed out. One view that isn't shown by default but which can be useful when you need technical support is in the Squish Tests group—the Runner/Server Log view. The Squish IDE remembers which views are showing in which perspectives between sessions, so you only have to add a view once for it to always be shown. Correspondingly, you only have to click a view's close button to get rid of it.

This dialog is used to control various aspects of the squishserver that the Squish IDE uses when recording and playing back tests.

The Squish Server Settings dialog

This dialog is used to set Squish's timeouts for AUT startup time and response time, to specify the web browser to use with Squish for Web, and whether to animate the mouse cursor on playback. The dialog also contains a Manage AUTs panel.

8.3.22.1. Manage AUTs panel

This panel is used to manage the Mapped AUTs, AUT Paths, and Attachable AUTs that are registered with the squishserver. (See AUT Paths and Mapped AUTs (Section 7.3.2).) This panel can be reached by clicking Edit|Server Settings|Manage AUTs.

The Manage AUTs panel

Any child item shown in this panel can be removed by clicking the Remove button. To add a new Mapped AUT, AUT Path, or Attachable AUT, first click the appropriate parent item (e.g., “Mapped AUTs” if you want to add a Mapped AUT), and then click the Add button. Once you have finished with the dialog click the Close button.

It is also possible to register and unregister AUTs using Squish's command line tools; see AUT Paths and Mapped AUTs (Section 7.3.2).

This 3-step wizard can be invoked from Help - Contact Support... and guides the user through the process of creating a customer support ticket. The first step asks the user for contact information. The E-mail address must be valid, and the Customer ID is retrieved from the license info.

Support Request Wizard step 1

In Step 2, the user can click a link to search known Squish issues, or describe the issue, and steps to reproduce it here. Summary and Description must not be empty.

Support Request Wizard step 2

In Step 3, we can add file attachments to the support request. Most of the time, we will have at least one attachment, and that will be the support information zip file. We can Collect and Attach Support Information with the click of a button, which brings us to the Collect Information for Squish Support dialog (Section 8.3.1). We can also take any arbitrary file and Add Attachment... to this support request.

There's a 50 MB limit on total size of attachments. When crossed, a warning will appear. Entries can be removed by clicking the red X button on the right edge of the table entry.

Support Request Wizard step 3

After the correct attachments are set, click Submit Support Request to send it to froglogic. Subsequent communication is over email from this point on.

This dialog is used to make one of the editor views' tabs the active one (i.e., the one shown and with the keyboard focus). It can be invoked using the Switch to Editor action (Section 8.1.1.74).

The Switch to Editor dialog

One convenience of using this dialog is that it shows the path as well as the filename of the files being edited. This is particularly useful since Squish IDE only shows the filenames on the Editor view (Section 8.2.6) tabs (e.g., test.py, test.py, test.py). (Note that if you hover the mouse over an Editor view (Section 8.2.6) tab the full path is shown.)

To switch to an particular tab simply click the name of the file in the list and then click the Close button. There are also buttons for selecting multiple tabs and for closing and saving.

Visual Verification Points are typically created through the IDE (Visual Verification Point (Section 5.22.4)) or the createVisualVP function. A dedicated dialog can later be used to view comparison failures and edit the expected visual state stored within the Verification Point.

8.3.25.1. Plain editing mode

The expectation of the visual state of an object hierarchy checked via a test.vp call can be configured prior to the first test execution. To open the editor select the Verification Point file and click the edit icon () or double-click on the file.

The dialog centers around an image of the GUI structure to be checked. On the left a tree view shows the hierarchy (Structure) of discovered sub-controls. When selecting a control through a click on the tree item or image the control's properties and activated checks will be displayed in the Properties panel on the right hand side.

The Visual Verification Point Editor

The object properties are grouped into four categories: Identification, Content, Geometry and Screenshot. This is also the order later followed during test execution after a matching object hierarchy was found.

8.3.25.1.1. Identifying Properties

Some object properties are not relevant to the visual appearance. But if the structures of two object snapshots are not identical they can help with mapping objects from one tree to the other.

In case an object possesses identifying properties that turn out to be unstable (like the HTML element 'id' attribute that is often assigned dynamically calculated values) they can be excluded from the list of object characteristics to be considered.

8.3.25.1.2. Content Properties

Content properties influence the way a UI element is rendered on the screen. Be it through textual content, a numerical value or current state of a button.

Content properties are part of the Identity Check as they can often provide a good way to tell one element from another.

In case a property's value can be permuted a fuzzy check using wildcard characters can be configured.

8.3.25.1.3. Geometry Properties

An element's geometry is specified by its x and y position (relative to the topmost element being checked) as well as its width and height.

In case the exact geometry can vary between test execution platforms an acceptable tolerance can be specified.

8.3.25.1.4. Screenshot

A screenshot check can be performed for a window as a whole, individual controls or groups of controls.

By default, the whole surface is checked (pixel by pixel) but in case of unstable content the check can be disabled.

8.3.25.2. View visual differences

A failed test.vp test will show up in the Test Results view (Section 8.2.18) view with a short summary of the failed check(s).

Test Results with Visual Verification Point failure

When clicking the View Differences toolbar button the editor will open in an extended mode for analysis of the difference details:

Editor showing failed Visual Verification

In extended mode the editor will show both the expected and actual images, a list of Failures and differences marked in red.

The Properties includes an additional Hierarchy section. This section will display possible disagreements between the two object structures.

A click on the Structure button will make the panel on the display the whole object structure. Including both identical and different objects:

Visual Verification Structure View

While the green checkmark denotes positive results of all active checks, the red circle is shown if at least one check failed. The yellow icons signals that an object had successful checks but a failure was found within one of its child or children's children objects.

8.3.25.3. Tuning of Visual Verifications

Ideally, executions of Verification Points with all checks enabled produce a positive result. Due to a multitude of factors verifications may fail. At least on the first run. Many types of failures can be dealt with automatically by pressing the Relax Check button. The Accept All button, on the other hand, will simply overwrite the expected state with the now seen actual state.

Here are more specific suggested ways of "tuning" a Verification Point in case of persistent failures:

8.3.25.3.1. Handling of Screenshot check failures

Turn off screenshot checks for elements known to contain dynamic content. In case content and geometry checks alone can be considered sufficient to verify the UI layout.

8.3.25.3.2. Handling of Content check failures

In case property values are unstable consider the usage of wildcards. If unavoidable drop the check completely by deselecting Include in verification.

Content check with wildcards

8.3.25.3.3. Handling of Geometry check failures

In case of varying geometries the checks can be relaxed through usage of allowable ranges for x, y, width and height. Or a complete check removal through deselection of Include in verification.

Range Check

8.3.25.3.4. Creation vs. execution state

During test execution the application's state may slightly differ from the state seen during the interactive creation of the Verification Point. As a result an immediate failure of the layout check may occur. First, inspect the changes to validate whether they are maybe acceptable. Then use the Accept All button to accept the changes. This can make the checks work for the following runs.

8.3.25.3.5. Failures due to transient state

A Verification Point executed during an application state transition may be very sensitive to exact timing. Parts of the UI may still be in the setup phase. A snooze() statement inserted before test.vp() can make the check fall into a stable state of the UI.