testSettings Object

Squish provides a global testSettings object whose properties and methods can be set to control certain aspects of test execution.

SequenceOfStrings testSettings.getWrappersForApplication(application)

This function returns the list of wrappers associated with the specified application. (See also testSettings.setWrappersForApplication(application, wrapperList).)

bool testSettings.logScreenshotOnFail

If this property is true every test failure will cause Squish to take a screenshot of the desktop when the failure occurred; by default this property is false and screenshots of failures are not automatically taken

For example, let's assume that we occasionally experience test failures when verifying the state of a specific widget in our nightly tests. We cannot explain the cause of the problem but suspect that the overall state of our application's GUI is broken due to as yet unknown external factors. To provide the developers with useful information via a visual inspection we enable automatic screenshot capturing—but for only for the test that is causing concern:

testSettings.logScreenshotOnFail = True
# ... perform test ...
testSettings.logScreenshotOnFail = False

testSettings.logScreenshotOnFail = true;
// ... perform test ...
testSettings.logScreenshotOnFail = false;

testSettings->logScreenshotOnFail(1);
# ... perform test ...
testSettings->logScreenshotOnFail(0);

TestSettings.logScreenshotOnFail = true
# ... perform test ...
TestSettings.logScreenshotOnFail = false

testSettings set logScreenshotOnFail 1
# ... perform test ...
testSettings set logScreenshotOnFail 0

bool testSettings.logScreenshotOnError

If this property is true every test error will cause Squish to take a screenshot of the desktop when the error occurred; by default this property is false and screenshots of errors are not automatically taken.

bool testSettings.logScreenshotOnWarning

If this property is true every test warning will cause Squish to take a screenshot of the desktop when the warning occurred; by default this property is false and screenshots of warnings are not automatically taken.

bool testSettings.logScreenshotOnPass

If this property is true every test pass will cause Squish to take a screenshot of the desktop. By default this property is false and this screenshots are not automatically taken for test passes.

bool testSettings.logStacktraceOnLog

If this property is true every test log will have a stacktrace attached in test reports that support stacktrace information. By default this property is false.

bool testSettings.logStacktraceOnPass

If this property is true every test pass will have a stacktrace attached in test reports that support stacktrace information. By default this property is false.

bool testSettings.objectNotFoundDebugging

If this property is false the object not found debug dialog will not open if an object can not be located or is not ready. By default this property is true and the object not found dialog will open, whenever an object can not be located or is not ready in time.

Some algorithms require to determine if an object is ready or not, without triggering the object not found dialog. In script sections that would normally trigger unwanted object not found dialogs, you can use the objectNotFoundDebugging property to temporarily deactivate the dialog:

testSettings.objectNotFoundDebugging = False
# ... wait for object that might not exist or get ready in time ...
testSettings.objectNotFoundDebugging = True

testSettings.objectNotFoundDebugging = false;
// ... wait for object that might not exist or get ready in time ...
testSettings.objectNotFoundDebugging = true;

testSettings->objectNotFoundDebugging(0);
# ... wait for object that might not exist or get ready in time ...
testSettings->objectNotFoundDebugging(1);

TestSettings.objectNotFoundDebugging = false
# ... wait for object that might not exist or get ready in time ...
TestSettings.objectNotFoundDebugging = true

testSettings set objectNotFoundDebugging 0
# ... wait for object that might not exist or get ready in time ...
testSettings set objectNotFoundDebugging 1

bool testSettings.imageNotFoundDebugging

If this property is false the image not found debug dialog will not open if an template image can not be located. By default this property is true and the image not found dialog will open, whenever a template image can not be located in time.

Some algorithms require image search without triggering the image not found dialog. In script sections that would normally trigger unwanted image not found dialogs, you can use the imageNotFoundDebugging property to temporarily deactivate the dialog:

testSettings.imageNotFoundDebugging = False
# ... wait for image that might not exist in time ...
testSettings.imageNotFoundDebugging = True

testSettings.imageNotFoundDebugging = false;
// ... wait for image that might not exist in time ...
testSettings.imageNotFoundDebugging = true;

testSettings->imageNotFoundDebugging(0);
# ... wait for image that might not exist in time ...
testSettings->imageNotFoundDebugging(1);

TestSettings.imageNotFoundDebugging = false
# ... wait for image that might not exist in time ...
TestSettings.imageNotFoundDebugging = true

testSettings set imageNotFoundDebugging 0
# ... wait for image that might not exist in time ...
testSettings set imageNotFoundDebugging 1

bool testSettings.textNotFoundDebugging

If this property is false the text not found debug dialog will not open if a search text can not be located. By default this property is true and the text not found dialog will open, whenever a search text can not be located in time.

Some algorithms require text search without triggering the text not found dialog. In script sections that would normally trigger unwanted text not found dialogs, you can use the textNotFoundDebugging property to temporarily deactivate the dialog:

testSettings.textNotFoundDebugging = False
# ... wait for text that might not exist in time ...
testSettings.textNotFoundDebugging = True

testSettings.textNotFoundDebugging = false;
// ... wait for text that might not exist in time ...
testSettings.textNotFoundDebugging = true;

testSettings->textNotFoundDebugging(0);
# ... wait for text that might not exist in time ...
testSettings->textNotFoundDebugging(1);

TestSettings.textNotFoundDebugging = false
# ... wait for text that might not exist in time ...
TestSettings.textNotFoundDebugging = true

testSettings set textNotFoundDebugging 0
# ... wait for text that might not exist in time ...
testSettings set textNotFoundDebugging 1

testSettings.setWrappersForApplication(application, wrapperList)

This function associates a list of wrappers with the specified application. The list must include at least one of the main toolkit wrappers. Optionally, it may include application-specific wrappers (for those Squish editions that support them). The main toolkit wrappers are:

These main toolkit wrapper names correspond directly to the Toolkit field in the Test Suite Configuration view of the squishide.

Note that Squish 4's dynamic wrapper support greatly reduces the need to create and maintain application-specific wrappers.

Here is an example that sets the Qt toolkit wrapper as well as a custom application wrapper, and then starts the AUT:

testSettings.setWrappersForApplication("MyApp", ["Qt", "CanvasWrapper"])
startApplication("MyApp")

testSettings.setWrappersForApplication("MyApp", ["Qt", "CanvasWrapper"]);
startApplication("MyApp");

testSettings->setWrappersForApplication("MyApp", ("Qt", "CanvasWrapper"));
startApplication("MyApp");

TestSettings.setWrappersForApplication("MyApp", ["Qt", "CanvasWrapper"])
startApplication("MyApp")

testSettings setWrappersForApplication MyApp { Qt CanvasWrapper }
startApplication "MyApp"

(See also SequenceOfStrings testSettings.getWrappersForApplication(application).)

bool testSettings.silentVerifications

If this property is true Squish will not produce Test Result entries for passing or failing Boolean test.vp(name), Boolean test.xvp(name), Boolean test.vpWithObject(name, objectNameOrReference) and Boolean test.vpWithImage(name, imageOrFilePath) calls. In combination with using the (boolean) return value of test.vp() and test.vpWithObject(), this can come in handy for custom defined verifications on top of a series of Verification Points.

Here is an example that checks that one of three Screenshot Verification Points passes.

testSettings.silentVerifications = True
for current in ['VP-winxp', 'VP-win2k', 'VP-win7']:
    if test.vp(current):
        test.passes("%s matched" % (current, ))
        break
else:
    test.fail("none of the provided VPs matched")

bool testSettings.breakOnFailure

If this property is true, the debugger stops on every failed verification performed by Boolean test.compare(value1, value2), Boolean test.xcompare(value1, value2), Boolean test.verify(condition), Boolean test.xverify(condition), Boolean test.vp(name), Boolean test.xvp(name), Boolean test.vpWithObject(name, objectNameOrReference), Boolean test.vpWithImage(name, imageOrFilePath) and Boolean test.exception(code) as well as every invocation of test.fail(message) and test.fatal(message). By default, this property is false.

bool testSettings.throwOnFailure

If this property is true every failing verification performed by Boolean test.compare(value1, value2), Boolean test.xcompare(value1, value2), Boolean test.verify(condition), Boolean test.xverify(condition), Boolean test.vp(name), Boolean test.xvp(name), Boolean test.vpWithObject(name, objectNameOrReference), Boolean test.vpWithImage(name, imageOrFilePath) and Boolean test.exception(code) as well as every invocation of test.fail(message) and test.fatal(message) will raise a script error. By default, this property is false and the aforementioned functions do not raise script errors.

Integer testSettings.retryDuration

This property affects the Boolean test.vp(name), Boolean test.xvp(name) Boolean test.vpWithObject(name, objectNameOrReference) and the Boolean test.vpWithImage(name, imageOrFilePath) functions. It can be used to specify for how long a verification should be retried after it fails. The default value is 0, which means the verification is only tried once. If you set it to 5000 the verification will be retried for at least 5000ms if it keeps on failing (i.e., it will be retried until it passes or 5 seconds have passed). This can be useful if the AUT needs to reach a certain stage before a property or screenshot verification can pass. This can help to reduce timing issues.

The following example shows how you can set this property for each verification individually, but you could also set it once for every verification that follows.

testSettings.retryDuration = 5000
test.vp("VP1")
testSettings.retryDuration = 0

testSettings.retryDuration = 5000;
test.vp("VP1")
testSettings.retryDuration = 0;

testSettings->retryDuration(5000);
test::vp("VP1")
testSettings->retryDuration(0);

TestSettings.retryDuration = 5000
Test.vp("VP1")
TestSettings.retryDuration = 0

testSettings set retryDuration 5000
test vp "VP1"
testSettings set retryDuration 0

bool testSettings.imageSearchTolerant

This property affects the ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]), ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion]) and Boolean test.imagePresent(imageFile, [parameterMap], [searchRegion]) functions. In case the option map passed to the above functions does not contain the tolerant key, the value of this property is used in its place. The default value is false. If true, the Correlation comparison mode is used.

Number testSettings.imageSearchThreshold

This property affects the ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]), ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion]) and Boolean test.imagePresent(imageFile, [parameterMap], [searchRegion]) functions. In case the option map passed to the above functions does not contain the threshold key, the value of this property is used in its place. The default value is 99.5.

bool testSettings.imageSearchMultiscale

This property affects the ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]), ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion]) and Boolean test.imagePresent(imageFile, [parameterMap], [searchRegion]) functions. In case the option map passed to the above functions does not contain the multiscale key, the value of this property is used in its place. The default value is false.

Number testSettings.imageSearchMinScale

This property affects the ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]), ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion]) and Boolean test.imagePresent(imageFile, [parameterMap], [searchRegion]) functions. In case the option map passed to the above functions does not contain the minScale key, the value of this property is used in its place. The default value is 50.0.

Number testSettings.imageSearchMaxScale

This property affects the ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]), ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion]) and Boolean test.imagePresent(imageFile, [parameterMap], [searchRegion]) functions. In case the option map passed to the above functions does not contain the maxScale key, the value of this property is used in its place. The default value is 200.0.

bool testSettings.defaultOcrLanguage

This property affects the OCR functions like String getOcrText([parameterMap], [searchRegion]), ScreenRectangle findOcrText(text, [parameterMap], [searchRegion]), ScreenRectangle waitForOcrText(text, [parameterMap], [searchRegion]) and Boolean test.ocrTextPresent(text, [parameterMap], [searchRegion]). In case the option map passed to the above functions does not contain the language key, the value of this property is used in its place. The default value is empty which means the engine's default language.

Integer testSettings.waitForObjectTimeout

This property defines the default timeout in milliseconds Object waitForObject(objectOrName), Object waitForObjectItem(objectOrName, itemOrIndex) and Object waitForObjectExists(name) will wait for an object lookup to succeed. This timeout also applies to Boolean test.vp(name), Boolean test.xvp(name), Boolean test.vpWithObject(name, objectNameOrReference), Boolean test.vpWithImage(name, imageOrFilePath) and highlightObject(objectOrName, [msec]).

The timeout value of 0 means Squish will try to find the object exactly once. Negative timeout values are not supported.

String testSettings.getPassword(key)

This method retrieves the password associated with the specified key. The passwords are stored with the test suite and can be edited using the Password Information.

Set initial testSettings Object values in the config.xml

The initial values of the testSettings Object properties can be set by editing the config.xml in the test suite folder. This way you can easily set the same values for multiple test cases. The test settings in the config.xml can be edited using the Test Settings and Image Search pages of the test suite settings editor in the squishide.

The following example shows how to extend the config.xml manually. Every property can be set in the same way.

<testconfig version="1.0">
...
<testsettings>
    <objectNotFoundDebugging>false</objectNotFoundDebugging>
    <testCaseName>some name</testCaseName>
</testsettings>
...
</testconfig>

The test suite's config.xml file is not always created automatically. You can either create it manually with a text editor, or in the squishide by opening the Test Suite Settings view editor and editing either the test suite summary and description or the default test settings.