Python Notes

Default File Encoding (UTF-8)

Squish assumes that all test.py files are UTF-8 encoded.

If you expect to edit such files outside of the Squish IDE, we recommend putting the following line at the start of each test.py file:

# -*- coding: utf-8 -*-

This is purely a comment, but a Python-aware editor will notice it, and will correctly load and save using the UTF-8 encoding that Squish expects, as a result.

Other text editors (which do not recognize the above notation) typically must be configured to save the Squish test scripts using UTF-8 encoding explicitly.

Default type of string return values (Unicode)

For Python 2.x, Squish API functions that return strings always return strings of type unicode instead of str. So, to check the type, use isinstance(string, unicode) or isinstance(string, basestring).

Squish's Python Modules

Squish's Python-specific extension modules are loaded automatically by internally executing the equivalent of the following statements after attaching to or starting an AUT:

import test
import testData
import object
import objectMap
import squishinfo
from squish import *

The objects (functions, classes, etc.) exposed by the squish module depend on the currently hooked up application. If no application is hooked up (via ApplicationContext startApplication(autName) or ApplicationContext attachToApplication(autName)) most objects will be missing from this module until an application is hooked up.

This means that it is not necessary to import them yourself unless you are developing your own standalone Python module. See Using Squish Functions in Python Modules/Packages for information on using the above modules in your own Python modules or packages.

Python Symbols Hidden by Squish

The wildcard import (from squish import *) of the squish module means that some of Python's built-in objects are hidden by Squish objects that have the same names but completely different behavior.

The objects hidden by Squish are object, bool, int, long and type.

However, this hiding only takes place for the test script itself (and only when executing test cases, not when using the squishtest module). This means that it is not being done for standard or custom Python modules and packages.

Some of the original symbols can be restored after calling startApplication() or attachToApplication(). For example:

import sys
# Check if Python 3:
if sys.version_info[0] == 3:
  import builtins
else:
  # Make Python 2 look like Python 3:
  import __builtin__ as builtins

def main():
    startApplication("aut")
    restore_python_builtins()

def restore_python_builtins():
    global bool
    global int
    global long
    global pytype

    del bool
    del int
    del long

    pytype = builtins.type

Restoring object and type is advised against, because they are used in snippets recorded by Squish.

Squish's bool vs. Python's bool

Squish's bool represents the Squish type for a bool in the wrapper's C and C++ code.

Like the other hidden symbols, to access Python's bool type, one can use it from the module __builtin__ (Python 2) or builtins (Python 3).

Squish's int vs. Python's int

Squish's int represents the Squish type for an integer in the wrapper's C and C++ code.

Like the other hidden symbols, to access Python's int type one can use it from the module __builtin__ (Python 2) or builtins (Python 3).

Squish's long vs. Python's long

Squish's long represents the Squish type for a long in the wrapper's C and C++ code.

Like the other hidden symbols, to access Python's long type one can use it from the module __builtin__ (Python 2). Note that the built-in long was removed in Python 3.

Squish's object vs. Python's object

Squish's object module has the same name as the base class of all Python 2 new-style classes, thus hiding Python's object symbol.

If you need to use Python 2's object symbol, you can access it from the module __builtin__.

In Python 3 there is no need to do anything since we don't explicitly inherit object, and it is inherited by default if no other class is specified.

Squish's type() vs. Python's type()

The Squish type() functions are used to simulate keyboard input by the user.

While Python's built-in type() function is available from module __builtin__ in Python 2, or builtins in Python 3, it is better Python practice to use the isinstance() function.

Importing Custom Python Modules

If you need to import custom modules that are not in sys.path you can make them available either by setting (or extending if already set) the PYTHONPATH environment variable with the path or paths to the module or modules you want to import, or you can extend sys.path at the start of your test scripts like this:

import sys
sys.path.append("my/path")

You can then import any module from my/path as normal, e.g., import mymodule.

Using Squish Functions in Python Modules/Packages

If you create a Python module or package that uses the functionality in the squish module, we recommend importing the squish module like this:

import squish

Not like this (wildcard import variant):

from squish import *

This is because the objects (functions, members, classes) provided by the squish module depend on the currently hooked up application. So if no application is hooked up by the time from squish import * is being executed, many objects will not be available directly, but one needs to access them through the squish module.

Consequentially, the objects (functions, members, classes) of the squish module must then be accessed through the squish module:

import squish

def do_something():
    squish.activateItem(squish.waitForObject(":Some_Menu"), "File")

squishtest: Module for embedding Squish in Python Applications

Squish tests in Python can be executed in 3 ways:

1. From the Squish IDE
2. From squishrunner command line
3. From a Python main program that uses squishtest module.

The squishtest Python module attempts to duplicate the functionality of squishrunner by offering the complete Squish API. Members are injected into this module, just as they are normally injected into the global namespace of Squish test suites. Similarly, after the call to startApplication or attachToApplication, the appropriate edition-specific APIs (e.g. Qt, Mac, Windows, Web, Java) are injected into the module dynamically.

Detailed setup steps, as well as an example Python script, can be found in this knowledgebase article.

Python Language Documentation

In addition to the Squish extension API, the full set of Python language features and modules is available for scripting. The Python Documentation page has links to the Python documentation for the current and older versions. If you prefer books, a good Python 3 book is Programming in Python 3 by Mark Summerfield.