17.5. How to Use the Windows API

17.5.1. How to Use the Microsoft Active Accessibility (MSAA) API for Automating Tests
17.5.2. How to Use the nativeObject Property

One of Squish's most useful features is the ability to access the toolkit's API from test scripts. This gives test engineers sufficient flexibility to allow them to test just about any aspect of the AUT.

With Squish's Windows Object API it is possible to find and query objects, call methods, and access properties. In addition, Squish provides a convenience API (Windows Object API (Section 18.12)) to execute common GUI actions such as clicking a button or typing text into a control. Windows objects are made available in a wrapper and the underlying objects' properties and methods are accessible through the Squish-added nativeObject property.

17.5.1. How to Use the Microsoft Active Accessibility (MSAA) API for Automating Tests

Squish features dedicated recognition for popular Windows toolkits such as MFC, Windows Forms (.NET) or the Windows Presentation Foundation (WPF). If the application under test uses a legacy toolkit or controls which are not based on one of the popular toolkits, it is possible to enable a special plugin which allows Squish to access the application controls using the Microsoft® Active Accessibility (MSAA) API. Depending on the toolkit, this may improve the amoung of information exposed by the controls.

This plugin (also called an “extension”) is disabled by default, but can be enabled and configured by editing the file <SQUIH_DIR>\lib\extensions\win\msaa.ext (<SQUISH_DIR> stands for the directory in which Squish was installed). To enable the MSAA extension, perform these steps:

  1. Open the file <SQUIH_DIR>\lib\extensions\win\msaa.ext in a text editor and modify the priority of the plugin from

    <priority>-10</priority>
    

    to

    <priority>10</priority>
    
  2. Save the file and close the text editor.

  3. Create a new test suite to make sure that no object names of previous records will be used.

When you record new tests, the Squish MSAA extension should now be used for identifying GUI objects. Plus note that this means that this installation/copy of Squish will always prefer recording objects from the MSAA extension. If this is not desirable please have a second installation/copy of Squish which you use for other purpose.

The MSAA extension also features a basic configuration facility for defining which specific controls to access using the accessibility API. This configuration is done by changing the values of the BlacklistedClassNames and WhitelistedClassNames settings in the msaa.ext file.

Each of the two settings takes a list of window class names (these names may include the wildcard characters *, which matches zero or more arbitrary characters, and ? which matches exactly one arbitrary character). The blacklist defines the set of windows which should not be handled by the MSAA extension. The whitelist can be used to overrule the blacklist in selected cases.

This allows enabling the recognition of controls via the MSAA extension by blacklisting everything (i.e. *) and then just whitelisting individual class names.

17.5.2. How to Use the nativeObject Property

The nativeObject property provides access to a Windows object's underlying methods and properties. For example, to access the items in a windowsforms list view, we would first obtain a reference to the list view, and then access the items:

Python
listview = waitForObject(":_ListView")
items = listview.nativeObject.Items
item1 = items.at(0)
JavaScript
var listview = waitForObject(":_ListView");
var items = listview.nativeObject.Items;
var item1 = items.at(0);
Perl
my $listview = waitForObject(":_ListView");
my $items = $listview->nativeObject->Items;
my $item1 = $items->at(0);
Ruby
listview = waitForObject(":_ListView")
items = listview.nativeObject.Items
item1 = items.at(0)
Tcl
set listview [waitForObject ":_ListView"]
set items [property get [property get $listview nativeObject] Items]
set item1 [invoke $items at 0]

Here is another example that writes the names of a windows object's methods (in this case a list view) to the Squish log.

Python
listViewType = listview.nativeObject.GetType()
methods = listViewType.GetMethods()
for method in methods:
    test.log("ListView method: " + method.Name)
JavaScript
var listViewType = listview.nativeObject.GetType();
var methods = listViewType.GetMethods();
for (i = 0; i < methods.length; ++i)
    test.log("ListView method: " + methods.at(i).Name);
Perl
my $listViewType = $listview->nativeObject->GetType();
my @methods = $listViewType->GetMethods();
foreach $method (@methods) {
    test.log("ListView method: " . $method->Name);
}
Ruby
listViewType = listview.nativeObject.GetType()
methods = listViewType.GetMethods()
for method in methods
    Test.log("ListView method: " + method.Name)
end
Tcl
set listViewType [invoke [property get $listview nativeObject] GetType]
set methods [invoke $listViewType GetMethods]
foreach method $methods {
    set name [property get $method Name]
    test.log("ListView method: $name")
}

[Under Construction  .]