The Squish GUI Tester excels at verifying an application’s user interface. But comprehensive verifications can come at a cost: the resulting test reports become huge and daunting to analyze. Take advantage of additional screenshots in Squish reports to get a better understanding of what happened.

A picture is worth a thousand words

Squish is a professional tool for creating, running and maintaining GUI tests. The resulting test reports can be stored in a wide range of formats or post-processed by other tools. However, sometimes it can be hard to tell why a verification failed. Tests make it very clear that e.g. a button was disabled even though it should have been enabled. Why that is, is often not clear at all.

Watching Squish as it replays tests to determine what’s happening is often not viable:

  1. Tests execute steps at high speed. It can be hard to follow the sequence of steps visually.
  2. Most tests are often executed outside of working hours. Nightly test runs are very common.
  3. Last but not least, tests typically take a couple of minutes, minimum. Watching tests can be boring, and there may be better things to do!

Screenshots in Squish reports can help with this. By storing screenshots along with the test report data you get to see the state of the screen as it was at various moments during test execution. For example, the screen as it was when a verification failed.

Adding Screenshots to Test Reports

The simplest way to log a screenshot is by invoking the test.attachDesktopScreenshot function:

def main():
    test.attachDesktopScreenshot("Desktop after launching AUT")

The documentation explains:

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

This means that you can take screenshots at arbitrary points during the execution of a test case. This is especially useful if the application under test has some visible side effect on the desktop, such as

  • An external PDF viewer is opened to display an invoice
  • A new icon appears in the system tray
  • A message box (possibly an error) is shown by the operating system

Automatically Logging Screenshots

In addition to the test.attachDesktopScreenshot function, Squish also features three APIs to create screenshots for you automatically in different situations:

  1. testSettings.logScreenshotOnFail for logging a screenshot every time a verification fails. Imagine a sporadic test failure which cannot be explained. Maybe the overall state of the application under test is broken due to external factors? Additional information can be provided to the developers via visual inspection of the desktop. This can be extremely useful for diagnosing test failures. In many cases, a quick look at a screenshot can give a useful hint as to what caused a verification to fail.
  2. testSettings.logScreenshotOnError for logging a screenshot every time a script error occurs. This is invaluable for diagnosing inexplicable test errors. For example, the test execution may abort because the application under test vanished. A screenshot may show that the application restarted itself due to an update. Or clicking a button may fail – the screenshot might show that the button is obscured by a Windows message box asking to reboot the machine.
  3. testSettings.logScreenshotOnPass for logging a screenshot every time a verification passes. This can be useful for creating a ‘photo story’ of the test execution. Verifications are typically spread all over a test script – and most of them are passes. By logging screenshots on passes, the resulting test reports become larger but much more expressive.

Especially the first two settings, testSettings.logScreenshotOnFail and testSettings.logScreenshotOnError, are extremely useful for diagnosing test failures. Enabling these settings is typically a major improvement to the generated test reports.

These three are not functions like test.attachDesktopScreenshot(), however. Instead, they are properties assuming the values ‘true’ and ‘false’. By default, they are all ‘false’ but can be enabled in a test script using a script statement such as

testSettings.logScreenshotOnFail = True

Make sure to execute this script statement early on in your test script. That way, they are created automatically for all subsequent verifications.

Accessing Screenshots

All screenshots are stored on disk in the compact PNG format, along with the other test report data. There are two main ways to view the screenshots: from the Squish IDE, or by inspecting (resp. processing) the test report files.

Accessing Screenshots in the Squish IDE

Accessing screenshots in the Squish IDE is useful if you just finished executing a test. It’s also handy when loading a previously generated test report into the Squish IDE.

In the Squish IDE, screenshots generated by test.attachDesktopScreenshot() show up like this:

Results generated by test.attachDesktopScreenshot()
Results generated by test.attachDesktopScreenshot()

Double-click the line saying ‘Attachment’ (the last line in the above image) to open the generated screenshot.

When using any of the testSettings flags described above, the results look slightly different:

Results generated by 'testSettings.logScreenshotOnFail = True'
Results generated by ‘testSettings.logScreenshotOnFail = True’

In this case, double-click the line starting with ‘Desktop Screenshot’ to open the screenshot.

Accessing Screenshots In Squish Reports

Squish supports generating test reports in various formats. See the documentation of the squishrunner for a full list of supported formats. The appearance of screenshots in Squish reports depends on the format used by the report.

The most powerful solution for inspecting test results is Test Center; Squish reports can be automatically sent to Test Center for analysis by all stakeholders. This allows viewing the screenshots conveniently in a web browser. To avoid the report becoming too large, screenshots are only shown when requesting them. To do so, click the little icon next to the ‘Comparison’ message in the string:

Squish Test Center showing a Squish report with a screenshot
Squish Test Center showing a Squish report failure

Other report formats which are meant for post-processing by other tools reference screenshots via the path on the file system. For example, Squish XML3 reports use this:

    <scriptedVerificationResult type="FAIL" time="2019-09-02T14:23:29+02:00">
        <text><![CDATA[Comparison (Screenshot in "/tmp/reportsml3/suite_screenshots/tst_case1/failedImages/failed_1.png")]]></text>
        <detail><![CDATA['Address Book - Untitled' and 'Apple' are not equal]]></detail>

That way, screenshots generated as part of Squish test executions are always easily available.


I am using Squish 6.3 and not finding this function test.attachDesktopScreenshot().
I would like to add screenshot at any step as required in the Test Script and expecting the screenshot or its link shown in html report generated at the end of execution.


    The ‘test.attachDesktopScreenshot()’ function sounds like a perfect match for your use case! This function is available in Squish 6.5.0 and later – maybe it would be worthwhile to consider an upgrade to the latest stable Squish release, Squish 6.5.2?


I see that test.attachDesktopScreenshot() perfectly works fine when we execute the script from Squish IDE. However, I noticed that when we run command line squishrunner with Report format HTML, I don’t see any entry being logged in the test report.

Does the test.attachDesktopScreenshot() only works with IDE?

    Hello Kumar,

    the test.attachDesktopScreenshot() function should work equally well when executing tests on the command line by calling the squishrunner program. I suspect there is just a small hiccup. It would be best to bring this up with the Squish tech support, please don’t hesitate to do so by sending a mail to – thanks!

Yes. I am using Squish 6.5.2 version and I could see that the function test.attachDesktopScreenshot does not input any screenshot when I run the squishrunner from command line.

    I am facing same problem, did you get any solution ?

    We use the same version, a folder “attachments” in data/suite_xxx/tst_yyy which contains the screenshots, but no references are there in the html report, when run on the test server.
    Locally, in the IDE, they are visible and clickable in the Test Results.

I use 6.5.2 with python
testSettings.logScreenshotOnError = True
testSettings.logScreenshotOnFail = True

And the screenshots are stored

I’m using Squish in my company. I wonder if it is possible to create an animated GIF from constant screenshots of my test. Sometimes we perform our tests and nobody is watching (like using Jenkins) and we want to see how was the execution, because it can has external interference. An animated GIF from screenshots would help us to do this.

    That’s a great idea! Indeed, we are already discussing different solutions for the situation you describe. A complete video recording would be imaginable. A more lightweight approach might be to just record the last couple of moments (say: 15 seconds) before a test failure occurs and then attach that to the test report. After all, it’s usually the last activity *before* a problem occurs which is useful, right? What do you think?

Leave a Reply

Your email address will not be published. Required fields are marked *

Copy link
Powered by Social Snap