Development/UITests

From The Document Foundation Wiki
Jump to: navigation, search

This is the preliminary documentation for the UI testing framework with a special focus on the python side.

Architecture

The UI testing consists of two parts, a C++ piece that wraps the LibreOffice UI in an introspection library and a Python framework with the actual test code. The connection between the two parts is done through a simple mostly untyped UNO interface.

C++ introspection library

The C++ introspection library consists of an UNO API that us used for the communication with the python part of the framework and wrappers for many UI objects. The UNO interface only has a few method and most of the communcation happens through string parameters.

The wrapper around the UI objects provides about the same methods as the UNO interface plus some helper methods.

Python framework

Writing tests

Makefile part

A simple makefile for the UI testing looks like the calc demo makefile. The important part is to use the UITest gbuild class and let the gb_UITest_add_module point to the directories with test files.

Normally nothing more is required and most is handled in the gbuild UITest class.

$(eval $(call gb_UITest_UITest,range_name))

$(eval $(call gb_UITest_add_modules,range_name,$(SRCDIR)/sc/qa/uitest,\
    test_dir1/ \
    test_dir2/ \
))

The range_name parameter is the name of the test target. The $(SRCDIR/sc/qa/uitest is the base directory and the parameters in that part lists the directories to search for tests.

Optionally the test can be run with a specific registrymodifications.xcu file to support running with specific configuration settings. Each test has an own user profile in workdir/UITest/test_name/user/. With the following makefile snippet a file can be copied into that directory.

$(eval $(call gb_UITest_use_configuration,range_name,$(SRCDIR)/sc/qa/uitest/range_name/registrymodifications.xcu))

This would copy the file sc/qa/uitest/range_name/registrymodifications.xcu to the user profile and the test would run with these settings.

Writing the Python code

Infrastructure

Commands available on UI elements

Generic

Handling the State of UI objects

The method to get the state of the UI object is provided by all UI elements. The method returns the state as a sequence of PropertyValue.

ui_element.getState()

The UI testing framework provides a method to convert the returned sequence of PropertyValue to a python dictionary.

from uitest.uihelper.common import get_state_as_dict

get_state_as_dict(ui_element)

Sending keyboard input to an element

How to extend the introspection library

UI elements extending vcl::Window

Other UI elements

Tools for writing a test

The difficult part about writing a test is to figure out which UNO commands to send and which action to call on an UI object. Currently there is some work going on to support logging what you do in a log file that will contain these information. The logging of UNO commands is already available in master.

To enable the logging you need to set LO_COLLECT_UIINFO to a file name that will be used to write the log. The file will be placed into the uitest directory inside of the user profile.