Installing Squish for Web

This section covers the necessary installation steps for different browsers and automation methods when using Squish for Web. Each subsection targets one browser or browser type and may be further divided in multiple parts.

Supported browsers

Squish for Web supports a wide range of different browsers and browser versions. The following table attempts to provide an overview of the browsers and browser versions being supported. More detailed information for each browser can be found in the following sections

Mozilla Firefox

You can execute, record and inspect web applications running in Firefox by selecting it in the Server Settings dialog in the squishide. Open the dialog using Edit > Server Settings and then select the Browser page. In the dropdown on the right select Firefox. The Executable field allows you to specify the firefox executable if it is not found automatically by Squish.

Squish for Web needs to install an extension for Firefox to be able to automate the browser. The installation of the extension is automatically started from the IDE but it needs to be completed manually by accepting the extension and closing the browser. The extension installation process can be started at any time from the Server Settings dialog, but it is being started as well when the squishide detects a missing or too old extension version. You can start the extension installation process manually from a terminal by issuing the following command after changing to the Squish installation directory:

lib/exec/browserextensionhelper installBrowserExtension firefox

Squish for Web uses a separate profile folder to separate passwords and other browser data between the automation session and your normal usage of the browser. The profile is being stored in a folder named squish_firefox_profile_dir in the directory $HOME/.squish on Linux and macOS and %APPDATA%\froglogic\Squish\ on Windows. The folder will be created by Firefox the first time Squish starts the browser.

Setup for attaching to an already running Firefox instances

To automate Firefox you need to make sure the Squish Firefox Extension is installed in the user profile used by Firefox when it is started outside of Squish. The easiest way to install the extension is to open a file browser and navigate to your Squish for Web package. From there go into the lib subfolder in the package. Drag and drop the file squishWebExt@froglogic.com.xpi into the Firefox browser window and acknowledge the installation.

The Squish Firefox Extension by default uses the port 9932 for communication with the rest of Squish for Web. If this port is already used by some other program on your system, you can configure the extension to use a different port. To do this, open the Firefox menu, click on the Tools entry and in the submenu click on the Addons item. This opens a new tab with the extensions loaded by Firefox. Make sure the Addons entry on the left of the page is selected. You should see the Squish Firefox Extension there and below it a button labeled Options or Preferences depending on your system. If you click that button, a new popup window appears where you can change the port number. This port number should then be passed to the attachToBrowser(portOrWindowTitle) function to attach to this instance of Firefox.

Usually Firefox will delay WebSocket connection attempts to a given WebSocket server for some time if the last attempt failed. This is a problem when wanting to attach to the browser from Squish as the Extension will repeatedly try to connect to Squish, but this connection will fail as long as there is no Squish test script executed with the attachToBrowser(portOrWindowTitle) function. Hence after a while these connection attempts will be delayed by Firefox and eventually the delay will be longer than the AUT timeout configured in Squish which will cause the connection to fail to be established.

This behavior of Firefox can be disabled by opening the special about:config URL in a new browser tab. Acknowledge the warning by clicking the I'll be careful, I promise button. The setting to change is network.websocket.delay-failed-reconnects and it should be set to false. You can search for the setting by typing the name into the search field and change it by double-clicking.

Google Chrome/Chromium

You can execute, record and inspect web applications running in Google Chrome/Chromium by selecting it in the Server Settings dialog in the squishide. Open the dialog using Edit > Server Settings and then select the Browser page. In the dropdown on the right select Google Chrome. The Executable field allows you to specify the executable if it is not found automatically by Squish.

Squish for Web needs to install an extension for Google Chrome/Chromium to be able to automate the browser. The installation of the extension is automatically started from the IDE but it needs to be completed manually by accepting the extension and closing the browser. The extension installation process can be started at any time from the Server Settings dialog, but it is being started as well when the squishide detects a missing or too old extension version. You can start the extension installation process manually from a terminal by issuing the following command after changing to the Squish installation directory:

lib/exec/browserextensionhelper installBrowserExtension google-chrome

To automate Google Chrome/Chromium, Squish for Web needs to install an extension for Google Chrome/Chromium. The installation of the extension is automatically started from the IDE when you try to run a test against Google Chrome/Chromium or start the browser using the Launch AUT button. The distribution of the two currently supported Chrome extensions for Squish is done through the Chrome Web Store. The 'Qt QA Squish Integration' Chrome extension is using the Manifest V3 API and can be used with Chrome 120 and newer. The 'froglogic Squish Integration' Chrome extension is using Manifest V2 API, which can be used up to at least Chrome 130 but is deprecated.

Squish for Web uses a separate profile folder to separate passwords and other browser data between the automation session and your normal usage of the browser. The profile is being stored in a folder named squish_chrome_data_dir in the directory $HOME/.squish on Linux and macOS and %APPDATA%\froglogic\Squish\ on Windows. The folder will be created by Google Chrome/Chromium the first time Squish starts the browser.

Setup for attaching to an already running Chrome instances

To automate Google Chrome you need to make sure the Squish Integration is loaded in the user profile used by Google Chrome when it is started outside of Squish. The easiest way to make Chrome use the extension is to start the browser and navigate to the Chrome store page for the Squish Integration: Squish Integration. Once the page has loaded click the Add To Chrome button and on the popup that is being opened up acknowledge the installation. You can verify that loading the extension succeeded by opening the Chrome menu and then selecting Tools and then Extensions entry. This opens up a new tab with the list of extensions, you should see an entry for the Squish Integration in that list.

The Squish Integration by default uses the port 9935 for communication with the rest of Squish for Web. If this port is already used by some other program on your system, you can configure the extension to use a different port. To do this, open the Chrome menu and then click on Tools and in the opened submenu click on Extensions. This opens a new tab with the Extensions loaded in Chrome. Below the entry for the Squish Integration you see a link labeled Options. If you click that link, a new popup window appears where you can change the port number and save the change. This port number should then be passed to the attachToBrowser(portOrWindowTitle) function to attach to this instance of Google Chrome.

Microsoft Edge on Windows

Microsoft Edge support on Windows is realized through the Edge Driver. The Edge Driver is not distributed with Squish so you have to download it from Microsoft: Download Microsoft Edge Driver. It is considered a developer tool, and is sometimes disabled as part of admin policy. It requires the registry value DeveloperToolsAvailability to be 0 or 1. Otherwise, Squish will not be able to automate the Edge Browser.

When using the Edge Driver, Squish does not start the browser directly, but instead, it starts the Edge Driver. Since the Edge Driver executable can be located anywhere on the system, you need to provide Squish with the path to the Edge Driver. If you're using the IDE you can use the Browser-Executable field in the Server Settings Dialog under Edit > Server Settings > Browser and Microsoft Edge. If you are not using the IDE, you can set the environment variable SQUISH_BROWSERPATH to point to the Edge Driver-Executable.

Known issues when using Squish with Microsoft Edge

Microsoft Edge support is still in an early stage so there are some known issues.

• Switching to Fullscreen mode is not supported.
• Tab support is limited to playback. While recording only a single tab is supported. If you try to open multiple tabs or try to switch between tabs during recording the focus will always go back to the initial tab.
• automateLogin(username, password) is not supported. In general websites with native login dialogs are not supported.
• When you start recording the browser window is sometimes opened before the initialization is complete, which might lead to events not being recorded. Make sure the Squish recording Control Bar is opened.
• When a new page is loaded there might be up to a 100ms gap in which no events are recorded by Squish.
• When a new page is loaded that has a different origin or domain it's possible that events recorded directly before the page change happens are lost.
• Drag and Drop on HTML input fields does not work reliably. As a workaround you can either drop the item with the relative x drop location set to 1. Or call mouseMove(x, y) between the drag and drop calls (the mouseMove coordinates should be the target coordinates offset by 1). This could be a general problem with how Microsoft Edge processes drag and drop events and might therefore be applicable to other scenarios as well.
• If you experience crashes of Edge Driver after test script execution you might need to increase the SoftExitTimeout: Configuring squishrunner.

Chromium-based applications

Support for automating the web content in Chromium-based applications is provided through the Webdriver for Chromium. The Webdriver is not redistributed with Squish so you have to download it from Google. Download Chromium Webdriver

In order for Squish to find the downloaded Chromium webdriver executable, place it in a directory that is in your PATH. As an alternative, you can configure the location in the file webwrapper.ini that you can find in the etc directory of your Squish installation. Open the file in a text editor and replace the value 'chromedriver' in the line starting with 'ChromeDriverForChromiumBasedApps' with the absolute path of the downloaded chromedriver executable. On Windows it is necessary to duplicate the backslashes in the path to fulfill the formatting requirements of the file.

To tell Squish about your Chromium-based application please select it as the browser executable in the Server Settings Dialog of the IDE. You can access the dialog by opening the Edit menu and below that the Server Settings submenu. In this submenu select the entry labeled Browser. In the dialog fill in the field below Chromium-based Applications (using CEF, Electron, nw.js etc.) and make sure that entry is selected.

In case you do not use the IDE you can set the environment variable SQUISH_BROWSERPATH to point to your application.

Setup for attaching to an already running Chromium-based application

To attach to a Chromium-based application, its necessary to prepare Squish for automating Chromium-based applications as explained in Chromium-based applications. After the basic setup has been finished, enable remote debugging features in the Chromium-part of the application. This is sometimes exposed as a commandline flag named --remote-debugging-port but it can also be set through code in your application. The port number used for the remote debugging port number needs to be passed to the attachToBrowser(portOrWindowTitle) function in the test script to connect to the Chromium web content in the application.

Known issues when using Squish with Chromium-based Applications

• Window interaction methods (maximizing, minimizing, setting to fullscreen, changing the size) are not supported as Squish only controls the web contents but not the whole application.
• Interaction with multiple web views in an application is possible, but limited to the web content inside them. Squish cannot make them visible/invisible or bring one view to the foreground as a human user may do.
• Screenshot verifications and Visual verifications will be using a desktop screenshot method which requires that the webview to be verified in is visible on screen fully. Web views that are not visible, for example because they are part of another tab inside the application cannot be grabbed. In addition the Chromium-based application must not be overlapped by other applications at the time of grabbing the screenshot as the screenshot will include such overlapped applications if they're covering the web view.
• The Boolean isBrowserDialogOpen() function always yields false for Chromium-based applications.

Safari

You can execute, record and inspect web applications running in Safari by selecting it in the Server Settings dialog in the squishide. Open the dialog using Edit > Server Settings and then select the Browser page. In the dropdown on the right select Safari.

Safari 12 or newer on macOS 10.13 or later

Manual Setup Steps for Enabling Automation

Safari 12 stopped supporting the use of Plug-In's which Squish relied on so far, so Squish adopted a different mechanism for automation, based on Safari's support for WebDriver. In order to allow automation via Safari's WebDriver you must enable this through the Develop menu. This menu option is usually hidden, but can be shown by opening the Preferences of Safari and selecting the Advanced tab. On the tab ensure the Show Develop menu in menu bar option is checked.

Once the Develop menu is shown open it and make sure the Allow Remote Automation option is checked.

Semi-Automatic Setup Steps for Enabling Automation

It is possible to enable the automation of Safari without starting the browser and going through the Develop menu. Safari's webdriver utility safaridriver allows to enable the Remote Automation through its commandline arguments. You can invoke safaridriver as shown below and provide the administrator password to enable automation, please make sure that Safari is not running on the system while doing this.

safaridriver --enable

Limitations

The automation of Safari through the WebDriver protocol, and Safari's behavior when being automated through this protocol, impose certain restrictions on what can be done in the test scripts.

In particular Safari is being executed in a separate dedicated session, which does not share any data with the normal browsing session, so cookies and other data is not being taken over from the normal browsing session.

In addition to that the following limitations apply as well:

• No support for recording or picking objects. Since Safari ends the automation as soon as a native click appears on the window there is no way for Squish to receive such click events (or text input) and hence neither recording interactions nor picking elements is possible. Only script execution and navigation of the object structure via the Application Objects view's tree are possible.
• No support for native native text input (nativeType) or native mouse input via the mousePress/mouseRelease functions. Safari disallows native events in the special automation session, causing abortion of the automation if attempted.
• Limited support for the nativeMouseClick function. The overload taking a HTML object can be used, but the relative coordinates will be ignored and only left button clicks can be performed. The WebDriver protocol only allows to click on the center of html elements with the left mouse button.
• Squish's automateLogin function, used for the Basic HTTP Authentication dialogs used on some websites, cannot be used. The function uses native events which would break the automation session and the WebDriver protocol does not provide a way to interact with these dialogs. The login on such a website must be achieved through different means.
• Automation of file uploads requires that the input element used for the actual file upload is visible and interactable. Websites hiding this html element and showing customized upload buttons require some manual scripting that makes the hidden input field visible and then automates that field via setText, similar to the following snippet.

  hiddenInput = waitForObjectExists({"tagName":"INPUT", "id":"userfile"})
  hiddenInput.setProperty("style", "display:block;visibility:visible")
  snooze(1)
  setText(hiddenInput, "/Users/andreas/dummyfile.txt")

• The active browser tab will be changing regularly. In order to use the WebDriver protocol the active tab needs to be activated for certain operations. In Safari such a change of the active also visually changes the active tab in the UI. Since Squish does such operations behind the scenes during the normal operation some 'flickering' of tabs may occur

Safari on macOS 10.11.5 or later

macOS 10.11.5 updated the version of Safari shipped with the system which now defaults to disallow the execution of JavaScript code in the web page through AppleScript. Squish relies on this method of executing JavaScript and thus it is necessary to enable this support again when using Safari on macOS 10.11.5 or later.

To enable this option its necessary to make Safari show the "Develop" menu. This can be done by opening the Preferences of Safari, then selecting the Advanced tab and ensure the option "Show Develop menu in menu bar" is checked.

Once the "Develop" menu is available in the menu bar, open the menu and make sure the option "Allow JavaScript from Apple Events" is checked. This enables Squish for Web to automate Safari on macOS 10.11.5 and later.

Opera up to version 12

You can execute, record and inspect web applications running in Opera by selecting it in the Server Settings dialog in the squishide. Open the dialog using Edit > Server Settings and then select the Browser page. In the dropdown on the right select Opera.

The Opera browser in versions up to 12 uses its own configuration settings for proxy servers. This makes it necessary to configure it to use the Squish for Web proxy manually, so Squish is able to automate Websites running in Opera.

Configuring the proxy can be done in the settings of Opera, they can be opened from the Menu by selecting the "Settings" entry and then in the submenu again selecting "Settings". In the dialog that appears the tab labeled "Advanced" needs to be selected to allow accessing the network configuration. The list on the left side of the tabs content has a corresponding entry called "Network" which needs to be selected. Click the button "Proxy servers" in the dialog to configure the proxy servers that Opera uses. In the newly opened dialog make sure the radio button "Use manual proxyserver configuration" is selected and check the checkbox next the "HTTP" entry. The fields "proxyserver" and "port" need to be filled with the values "localhost" and "8000" respectively. In addition the checkbox "Use the proxy for local servers" further down should be activated to make it possible to test the addressbook application that ships with Squish.

In addition to configuring the proxy, the Crash Recovery dialog in Opera should be disabled. Since the dialog cannot be automated with Squish for Web it would otherwise cause test execution abortion as it appears on each start of Opera after Squish has exited the browser. This setting needs to be changed in Operas configuration editor, which can be opened by putting "about:config" into the location bar. The page that is being opened allows searching for specific settings. Use "Problem" as keyword for the search so it will reveal the configuration entry for enabling and disabling the dialog. The title of the setting is "Show Problem Dialog" and the configuration entry needs to be disabled by unchecking the checkbox next to the text.

This completes the steps needed to setup Opera for testing with Squish. You can now select the Opera executable as a browser in the IDE and record and replay tests with it.

Microsoft Internet Explorer

You can execute, record and inspect web applications running in Internet Explorer by selecting it in the Server Settings dialog in the squishide. Open the dialog using Edit > Server Settings and then select the Browser page. In the dropdown on the right, select Internet Explorer.

Squish does not require any special setup steps to be able to automate Internet Explorer, all necessary setup is being done automatically when you start the browser the first time.

Setup for attaching to an already running Internet Explorer instances

To automate Internet Explorer using Squish for Web it is necessary to instruct it to use just a single process for all its tabs. Internet Explorer 10 and newer will usually use multiple processes for rendering websites as can be seen in the task manager.

Internet Explorer can be instructed to use only one process by changing a registry setting using the registry editor. The editor can be started by opening the Windows menu and then start typing regedit and select the entry running the regedit command.

The registry editor shows a tree on the left, locate the entry HKEY_CURRENT_USER and expand it. Following the tree structure expand the Software entry, below that Microsoft and finally inside Microsoft expand Internet Explorer. In this section there's an entry called Main and once it is selected you see a couple of keys on the right side of the editor. There should be a DWORD entry called TabProcGrowth there. The TabProcGrowth entry has to be set to 0 in order for Squish for Web to be able to automate Internet Explorer after attaching to it. Once this is done make sure to restart any running instances of the browser.

Browsers on mobile devices

This section assumes that Squish for Web 6.1 or later is installed on a desktop operating system, as instructed in Installing from Binary Packages.

Start the HTTP proxy

Start the HTTP-Proxy server by executing the following command in the console (this uses the default HTTP-proxy server port 8000):

$ ./bin/webproxy/proxy

See Web Proxy for details about the options that the webproxy supports.

Configure Device Proxy Connection

Connect your mobile device or tablet to the same network as your computer, and configure the device to use the computer's proxy server as follows:

• Android Device
  1. From Settings, tap Wi-Fi
  2. Tap and hold the currently active wireless network connection, and select Modify network
  3. Tap the Show advanced options check box
  4. Click the Proxy box and select Manual
  5. Enter the computer's IP address or name in the Proxy hostname box
  6. Enter 8000 in the Proxy port box, this is the standard port used by the HTTP-proxy
  7. Tap Save
• iOS Device
  1. From Settings, tap Wi-Fi
  2. Tap the Information button (i) for the currently active wireless network connection
  3. Tap Manual in the HTTP PROXY section
  4. Enter the computer's IP address or name in the Server box
  5. Enter 8000 in the Port box, this is the standard port used by the HTTP-proxy
  6. Tap <Wi-Fi
• Test Device Connection To test the connection, open a browser on the device and navigate to "http://<anyURL>/startsquish/". The browser page loads: "Squish/Web Automated GuiTesting Waiting for start of next testcase..."

Configure Squish for Web IDE

From the computer, open the Squish (for Web) IDE, select Edit > Server Settings > Browser, and choose the Browser on Mobile Device option.

This completes the device-specific setup for Squish for Web! You can now record and playback tests using the squishide on the computer just as you can with standard web testing; only now when recording, the actions all take place on the device—and, of course, the playback also takes place on the device.

Limitations

At the time of publication, testing Browsers on devices had some limitations compared with web testing on desktops. The most significant known limitations are:

• No support for testing native dialogs; this includes file upload fields.
• Cannot use one proxy for multiple parallel test executions/recordings.
• Does not work with popup blockers when using a manually-started browser/proxy; popup blockers need to be disabled in the browser prior to testing.
• Cannot use Screenshot Verification points with remote browsers (iphone/ipad browser testing), this is due to the screenshot code being purely C++ code in the webhook.
• Complex Touch/Gesture events are currently not recognized/recorded/replayable with Safari on iOS. Simple tap interactions do work.
• The HTTPS protocol is not supported.
• Windows: Sometimes picking only works on the complete browser window and buttons. This can be fixed by renaming <SQUISHDIR>\bin\winhook.dll.
• Browser shows a "session not correctly ended" dialog. This is due to the way we exit the browser; usually the browser has a setting to avoid the dialog.
• Browser shows a progress indicator all the time. This is due to the way the internal communication with Squish/Web and the proxy works.