autopilot.testcase
- Base class for all Autopilot Test Cases¶
Quick Start¶
The AutopilotTestCase
is the main class test authors will be
interacting with. Every autopilot test case should derive from this class.
AutopilotTestCase
derives from testtools.TestCase
, so test
authors can use all the methods defined in that class as well.
Writing tests
Tests must be named: test_<testname>
, where <testname> is the name of the
test. Test runners (including autopilot itself) look for methods with this
naming convention. It is recommended that you make your test names descriptive
of what each test is testing. For example, possible test names include:
test_ctrl_p_opens_print_dialog
test_dash_remembers_maximized_state
Launching the Application Under Test
If you are writing a test for an application, you need to use the
launch_test_application
method. This will launch the
application, enable introspection, and return a proxy object representing the
root of the application introspection tree.
-
class
autopilot.testcase.
AutopilotTestCase
(*args, **kwargs)[source]¶ Wrapper around testtools.TestCase that adds significant functionality.
This class should be the base class for all autopilot test case classes. Not using this class as the base class disables several important convenience methods, and also prevents the use of the failed-test recording tools.
-
launch_test_application
(application, *arguments, **kwargs)[source]¶ Launch
application
and return a proxy object for the application.Use this method to launch an application and start testing it. The positional arguments are used as arguments to the application to lanch. Keyword arguments are used to control the manner in which the application is launched.
This method is designed to be flexible enough to launch all supported types of applications. Autopilot can automatically determine how to enable introspection support for dynamically linked binary applications. For example, to launch a binary Gtk application, a test might start with:
app_proxy = self.launch_test_application('gedit')
Applications can be given command line arguments by supplying positional arguments to this method. For example, if we want to launch
gedit
with a certain document loaded, we might do this:app_proxy = self.launch_test_application( 'gedit', '/tmp/test-document.txt')
... a Qt5 Qml application is launched in a similar fashion:
app_proxy = self.launch_test_application( 'qmlscene', 'my_scene.qml')
If you wish to launch an application that is not a dynamically linked binary, you must specify the application type. For example, a Qt4 python application might be launched like this:
app_proxy = self.launch_test_application( 'my_qt_app.py', app_type='qt')
Similarly, a python/Gtk application is launched like so:
app_proxy = self.launch_test_application( 'my_gtk_app.py', app_type='gtk')
Parameters: - application –
The application to launch. The application can be specified as:
- A full, absolute path to an executable file.
(
/usr/bin/gedit
) - A relative path to an executable file.
(
./build/my_app
) - An app name, which will be searched for in $PATH (
my_app
)
- A full, absolute path to an executable file.
(
- app_type – If set, provides a hint to autopilot as to which kind of introspection to enable. This is needed when the application you wish to launch is not a dynamically linked binary. Valid values are ‘gtk’ or ‘qt’. These strings are case insensitive.
- launch_dir – If set to a directory that exists the process will be launched from that directory.
- capture_output – If set to True (the default), the process output will be captured and attached to the test as test detail.
- emulator_base – If set, specifies the base class to be used for all emulators for this loaded application.
Raises: ValueError – if unknown keyword arguments are passed.
Returns: A proxy object that represents the application. Introspection data is retrievable via this object.
- application –
-
launch_click_package
(package_id, app_name=None, app_uris=[], **kwargs)[source]¶ Launch a click package application with introspection enabled.
This method takes care of launching a click package with introspection exabled. You probably want to use this method if your application is packaged in a click application, or is started via upstart.
Usage is similar to the
AutopilotTestCase.launch_test_application
:app_proxy = self.launch_click_package( "com.ubuntu.dropping-letters" )
Parameters: - package_id – The Click package name you want to launch. For
example:
com.ubuntu.dropping-letters
- app_name – Currently, only one application can be packaged in a click package, and this parameter can be left at None. If specified, it should be the application name you wish to launch.
- app_uris – Parameters used to launch the click package. This parameter will be left empty if not used.
- emulator_base – If set, specifies the base class to be used for all emulators for this loaded application.
Raises: - RuntimeError – If the specified package_id cannot be found in the click package manifest.
- RuntimeError – If the specified app_name cannot be found within the specified click package.
Returns: proxy object for the launched package application
- package_id – The Click package name you want to launch. For
example:
-
launch_upstart_application
(application_name, uris=[], **kwargs)[source]¶ Launch an application with upstart.
This method launched an application via the
ubuntu-app-launch
library, on platforms that support it.Usage is similar to the
AutopilotTestCase.launch_test_application
:app_proxy = self.launch_upstart_application("gallery-app")
Parameters: - application_name – The name of the application to launch.
- emulator_base – If set, specifies the base class to be used for all emulators for this loaded application.
Raises: - RuntimeError – If the specified application cannot be launched.
- ValueError – If unknown keyword arguments are specified.
-
patch_environment
(key, value)[source]¶ Patch the process environment, setting key with value value.
This patches os.environ for the duration of the test only. After calling this method, the following should be True:
os.environ[key] == value
After the test, the patch will be undone (including deleting the key if if didn’t exist before this method was called).
Note
Be aware that patching the environment in this way only affects the current autopilot process, and any processes spawned by autopilot. If you are planing on starting an application from within autopilot and you want this new application to read the patched environment variable, you must patch the environment before launching the new process.
Parameters: - key (string) – The name of the key you wish to set. If the key does not already exist in the process environment it will be created (and then deleted when the test ends).
- value (string) – The value you wish to set.
-
assertVisibleWindowStack
(stack_start)[source]¶ Check that the visible window stack starts with the windows passed in.
Note
Minimised windows are skipped.
Parameters: stack_start – An iterable of Window
instances.Raises: AssertionError – if the top of the window stack does not match the contents of the stack_start parameter.
-
assertProperty
(obj, **kwargs)[source]¶ Assert that obj has properties equal to the key/value pairs in kwargs.
This method is intended to be used on objects whose attributes do not have the
wait_for
method (i.e.- objects that do not come from the autopilot DBus interface).For example, from within a test, to assert certain properties on a ~autopilot.process.Window instance:
self.assertProperty(my_window, is_maximized=True)
Note
assertProperties is a synonym for this method.
Parameters: - obj – The object to test.
- kwargs – One or more keyword arguments to match against the attributes of the obj parameter.
Raises: - ValueError – if no keyword arguments were given.
- ValueError – if a named attribute is a callable object.
- AssertionError – if any of the attribute/value pairs in kwargs do not match the attributes on the object passed in.
-
assertProperties
(obj, **kwargs)¶ Assert that obj has properties equal to the key/value pairs in kwargs.
This method is intended to be used on objects whose attributes do not have the
wait_for
method (i.e.- objects that do not come from the autopilot DBus interface).For example, from within a test, to assert certain properties on a ~autopilot.process.Window instance:
self.assertProperty(my_window, is_maximized=True)
Note
assertProperties is a synonym for this method.
Parameters: - obj – The object to test.
- kwargs – One or more keyword arguments to match against the attributes of the obj parameter.
Raises: - ValueError – if no keyword arguments were given.
- ValueError – if a named attribute is a callable object.
- AssertionError – if any of the attribute/value pairs in kwargs do not match the attributes on the object passed in.
-
pick_app_launcher
(*args, **kwargs)[source]¶ Given an application path, return an object suitable for launching the application.
This function attempts to guess what kind of application you are launching. If, for some reason the default implementation returns the wrong launcher, test authors may override this method to provide their own implemetnation.
The default implementation calls
autopilot.application.get_application_launcher_wrapper
-