8.3. Dialogs

8.3.1. Customize Perspective dialog
8.3.2. Find/Replace dialog
8.3.3. Import Squish Resource dialog
8.3.4. Manage AUTs dialog
8.3.5. New dialog
8.3.6. New Squish Test Case wizard
8.3.7. New Squish Test Data dialog
8.3.8. New Squish Test Script dialog
8.3.9. New Squish Test Suite wizard
8.3.10. Object Not Found dialog
8.3.11. Open Perspective dialog
8.3.12. Pref­er­ences dialog
8.3.13. Screenshot Verification Point dialog
8.3.14. Search dialog
8.3.15. Show View dialog
8.3.16. Squish Server Settings dialog
8.3.17. Switch to Editor dialog
8.3.18. Visual Verification Point editor

8.3.1. Customize Perspective 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.

8.3.2. Find/Replace dialog

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 Eclipse's regular expression syntax.

8.3.3. Import Squish Resource dialog

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), or .xls (Microsoft® Excel™ spreadsheet format—but not .xlsx 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 use 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.7) and the New Squish Test Script dialog (Section 8.3.8).

8.3.4. Manage AUTs dialog

This dialog 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 dialog can be invoked by clicking Edit|Server Settings|Manage AUTs.

The Manage AUTs dialog

Any child item shown in this dialog 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).

(From Squish 4.2 this dialog is replaced by the Manage AUTs pane in the Squish Server Settings dialog (Section 8.3.16).)

8.3.5. New dialog

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.8) 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.6) 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.16)'s Test Cases list's context menu.)

If you click “Squish Test Data File” the New Squish Test Data dialog (Section 8.3.7) 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.9) will replace the "New" dialog. This dialog is used to create a new test suite.

8.3.6. New Squish Test Case wizard

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.16)'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.5). (See also the New Test Case action (Section 8.1.1.28).)

The New Squish Test Case wizard

Once the wizard has appeared, 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.

8.3.7. New Squish Test Data dialog

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.5).

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.3) 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.8).

8.3.8. New Squish Test Script dialog

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.5).

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.3) 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.7).

8.3.9. New Squish Test Suite wizard

This dialog is used to creat a new test suite. It is invoked by clicking the Test Suites view (Section 8.2.16)'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.5). (See also, the New Test Suite action (Section 8.1.1.29).)

The New Squish Suite wizard

The use of this wizard is described in the tutorials:

8.3.10. Object Not Found dialog

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 allows to pick an object from the AUT to compare that objects properties against the ones used for the name so far. This allows to verify wether the objects properties have changed and hence 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 apropriate 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]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.

8.3.11. Open Perspective dialog

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

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 necesary 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.1).)

8.3.12. Pref­er­ences dialog

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

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.12.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.12.2. General pane

The General pane is used to set some miscellaneous 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.12.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.13).

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.12.3. JavaScript pane

The JavaScript pane and its child panes are used to set various JavaScript-specific options.

The main pane is empty and neither the Console nor the Debug panes (or the Debug pane's child panes) are used by Squish. The other panes are used however. The Editor pane is used to control how the caret is positioned during navigation and whether to use spaces or tabs and the what and how much indentation to use. This pane also has some child panes. These are used to control such things as folding and syntax highlighting, code templates, and whether the editor closes strings and opening brackets of various kinds. The Error/Warnings child pane is used to control how strict the editor is about JavaScript syntax. The Formatter child pane is used to control how JavaScript is formatted by the editor. The Interpreters pane is used to specify which JavaScript interpreter to use. Squish uses its own built-in JavaScript interpreter but this option could be used to influence how the JavaScript editor does its syntax highlighting and error reporting. The Task Tags child pane is used to manage a list of special words that the Squish IDE must recognize and highlight inside JavaScript comments—for example, FIXME or TODO.

8.3.12.4. Perl EPIC pane

The Perl EPIC pane and its child panes are used to set various Perl-specific options.

The Perl executable setting is from Eclipse—it has no effect on test script execution. The Perl EPIC pane has a number of child panes including an Editor pane that itself has child panes (which are not documented here). The Editor pane can be used to set what and how much to indent, syntax highlighting colors, and whether the editor closes open quotes and various kinds of brackets. Those who use the Squish IDE to create Perl modules or who are deeply into Perl programming may wish to enable the Squish IDE's Module::Starter and Perl::Critic functionality—but these features are too specialized to be documented here. The Source Formatter pane is used to control how the editor formats Perl source code. The Task Tags child pane is used to manage a list of special words that the Squish IDE must recognize and highlight inside Perl comments—for example, FIXME or TODO.

8.3.12.5. Python pane

The Python pane and its child panes are used to set various Python-specific options.

The Python pane has no options of its own but it does have various child panes. The Debug child pane is not used by the Squish IDE. The Editor pane is used to control how the caret is positioned during navigation and whether to use spaces or tabs and the what and how much indentation to use. This pane also has some child panes. These are used to control such things as folding and syntax highlighting, code templates, and whether the editor closes strings and opening brackets of various kinds. The Interpreters pane is not used by the Squish IDESquish uses the Python interpreter it is shipped with. The Task Tags child pane is used to manage a list of special words that the Squish IDE must recognize and highlight inside Python comments—for example, FIXME or TODO.

8.3.12.6. Run/Debug pane

The Run/Debug pane and its child panes are used to set some general options concerning the running and debugging of test scripts.

The Run/Debug pane itself can be used to set some basic behaviors, for example what to do when a breakpoint is hit, and various color settings. It is best to at least keep the Activate the ... checkboxes checked. The Console child pane is not used by the Squish IDE. The Launching child pane can be used to control the Squish IDE's behavior when running a test, although options relating to “building” are ignored. It is best to have the Save required dirty editors before launching set to Always (the default), or at least to Prompt; setting it to Never introduces a risk that test edits could be lost in the unlikely event that the Squish IDE crashes. The Launch pane's Default Launchers sub-pane is ignored by the Squish IDE. The Launch pane's Launch Configurations pane should not be used. The Run/Debug pane's Perspectives child pane is ignored by the Squish IDESquish will always use the Squish Test Debugging Perspective (Section 8.1.2.3) when debugging is required. The String Substitution child pane is rarely needed and not documented here. The View Management child pane is used to control some aspects of how perpectives behave regarding their views.

8.3.12.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.12.7.1. Squish pane's child panes

The Squish pane has several child panes: 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.7) 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.16), 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.16), 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 pane is primarily used to set the snooze factor. This is only relevant to calls to the snooze function—and this function has been almost completely replaced by calls to Squish's wait functions such as the waitForObject function. (From Squish 4.2, the Playback pane's mouse cursor animation setting is in the Squish Server Settings dialog (Section 8.3.16)'s Playback pane, not the Preferences dialog.) In addition the behavior upon lookup errors can be selected in this pane. The test execution can be halted when Squish fails to wait for an object to be ready which will show the Object Not Found dialog (Section 8.3.10).

The Recording pane is used to control how Squish records tests. The default settings are to synchronize based on object existence (i.e., using Squish's wait functions such as the waitForObject function), and to compress events (i.e., to record a mouse move from one position to another as a single mouse move rather than as lots of smaller moves). These defaults are highly recommended since they produce the most robust and shortest test scripts possible. If you choose to use time based synchronization, Squish will record calls to the snooze function rather than to the wait functions; but be aware that this is almost always less reliable than using wait functions. (And if you hit a real problem using a wait function you can always set the timeout for the wait function's call manually to a longer duration; or insert a snooze manually if necessary.) Switching off event compression won't affect recording and playback reliability, but 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.16)'s Test Cases list's context menu; see also Testcase Templates (Section 7.14).

8.3.12.8. Tcl pane

The Tcl pane's child panes are used to set various Tcl-specific options.

The main pane is empty and none of the Console, Core, Debug, Interpreters, Libraries, or Man pages panes (or any of their child panes) are used by Squish. Many of the other panes are used however. The Code Templates pane can be used to create Tcl template files (separately from Squish's own file template mechanism). Some very basic predefined templates are provided and these can easily be edited or custom ones added. The Editor pane is used to control how the caret is positioned during navigation and whether to use spaces or tabs and the what and how much indentation to use. This pane also has some child panes. These are used to control such things as folding and syntax highlighting, code templates, and whether the editor closes strings and opening brackets of various kinds. The Task Tags child pane is used to manage a list of special words that the Squish IDE must recognize and highlight inside Tcl comments—for example, FIXME or TODO.

8.3.12.9. Team pane

Neither the Team pane nor any of its child panes has any effect in the Squish IDE, so none of these panes are documented here.

8.3.13. Screenshot Verification Point dialog

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.15) to pop up the context menu and then choosing the context menu's View Differences menu item. (See also, Setting Masks and Modes (Section 8.3.13.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 difference 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 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 tools (in the form of buttons at the right hand side of the dialog) for adding positive and negative masks, for masking a highlighted region, and for removing masks. (Most of these buttons are only enabled if the global Show/Hide Mask toggle button is pressed down, i.e., is set to show the mask—the highlighted region button is only enabled if the global Show/Hide Highlighting button is pressed down.)

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.13.1. Screenshot Comparison Modes

8.3.13.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.13.1.2. Fuzzy Pixel Comparison Mode

This 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.13.1.3. Histogram Comparison Mode

This 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 allows to 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.13.1.4. Correlation Comparison Mode

This 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 labelled 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 a system with different screen resolution.

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.13.2. Setting Masks and Modes

It is possible to set the Mask and Comparison Mode 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.15) (so no View Differences context menu item). This is done by clicking the VPs tab in the Test Suites view (Section 8.2.16)'s Test Case Resources list and then clicking (or double-clicking depending on your settings) the image verification point whose Mask or Comparison Mode 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 and Comparison Mode tabs can be interacted with as described above, and if you save the settings they will be used next time the test that uses the verification point is run.

8.3.14. Search dialog

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.13) 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).

8.3.15. Show View dialog

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.

8.3.16. Squish Server Settings dialog

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 that replaces the Manage AUTs dialog (Section 8.3.4) used in Squish 4.0 and 4.1.

The Manage AUTs 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).)

Any child item shown in this dialog 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).

(Added with Squish 4.2.)

8.3.17. Switch to Editor dialog

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 for Squish 4.0.x since it 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.

8.3.18. Visual Verification Point editor

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.18.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.18.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 posesses 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.18.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 Indentity Check as they can often provide a good way to tell from element from another.

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

8.3.18.1.3. Geometry Properties

An element's geometry is specified by it's 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.18.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.18.2. View visual differences

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

Test Results with Visual Verification Point failure

When right-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.18.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.18.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.18.3.2. Handling of Content check failures

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

Content check with wildcards
8.3.18.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.18.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 occurr. 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.18.3.5. Failures due to transient state

A Verification Point executed during an application state transition maybe 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.