QSystemTest Namespace Reference
[QtUiTestModule]

Detailed Description

The QSystemTest namespace provides script based system test functionality for Qt.

This documentation describes the API reference for the QtUiTest scripting language. Please read the QtUiTest Manual for a full description of the system test tool.

Type Documentation

typedef Array

The Array type as documented in ECMA-262, section 15.4.

The following extensions are provided in QtUiTest.

typedef Boolean

The Boolean type as documented in ECMA-262, section 15.6.

enum QSystemTest::EnterMode

This enum specifies whether enter() should commit the entered value (eg, by simulating a Select keypress) or not.

typedef Function

The Function type as documented in ECMA-262, section 15.3.

enum QSystemTest::LearnMode

This enum specifies the learn mode setting.

The learn mode affects the behavior of certain functions in QSystemTest, such as verifyImage(). Additionally, a test may choose to use the current learn mode to determine how to handle a test failure.

See also learnMode(), setLearnMode(), and verifyImage().

typedef Number

The Number type as documented in ECMA-262, section 15.7.

typedef QVariantArray

An Array object in which every element is a QVariant.

enum QSystemTest::SkipMode

This enum describes the modes for skipping tests during execution of the test data.

See also skip() and QTest::SkipMode.

enum QSystemTest::StartApplicationFlag
flags QSystemTest::StartApplicationFlags

This enum describes additional behaviour to use when starting applications by startApplication().

The StartApplicationFlags type is a typedef for QFlags<StartApplicationFlag>. It stores an OR combination of StartApplicationFlag values.

typedef String

The String type as documented in ECMA-262, section 15.5.

The following extensions are provided in QtUiTest.

typedef StringArray

An Array object in which every element is a String.

enum QSystemTest::TimeSynchronizationMode

This enum defines the mode that is used to synchronize the device system time.

Function Documentation

void QSystemTest::addExpectedMessageBox ( String title, String text, String option = null )

Informs the test that a message box is expected to pop up (soon) with the given title and text. When option is specified QtUiTest will try to activate a menu item from the softmenu that has the text specified by option. If a message box appears while executing a test which hasn't been marked as expected, the current test fails.

When the message box appears, the user-visible option will be selected.

Use this function when expectMessageBox() is unsuitable, e.g. when several different types of message boxes might occur.

Example:

    addExpectedMessageBox("Calendar", "Are you sure you want to delete:");
    addExpectedMessageBox("Delete Event", "This appointment is part of");
    select( "Delete event", optionsMenu() );
    waitExpectedMessageBox(4000,false);
    if (currentTitle() == "Delete Event") select( "Back", softMenu() )
    else if (currentTitle() == "Calendar") select( "Yes", softMenu() );
    clearExpectedMessageBoxes();

See also expectMessageBox(), clearExpectedMessageBox(), clearExpectedMessageBoxes(), and waitExpectedMessageBox().

String QSystemTest::baseDataPath () const

Returns the path which functions as the root directory to all the test data.

This path defaults to the "testdata" subdirectory of the directory in which the source file of the current test is located; if the source file no longer exists, the path defaults to $HOME/.qtest/ . In either case, it can be overridden by the user with the -data command line switch.

The base data path contains the test data for functions such as verifyImage(). It can also be used within a test to use testdata stored in files.

See also setBaseDataPath(), currentDataPath(), and learnMode().

void QSystemTest::clearExpectedMessageBox ( String title, String text )

Removes the message box with the given title and text from the list of expected message boxes.

See also addExpectedMessageBox() and waitExpectedMessageBox().

void QSystemTest::clearExpectedMessageBoxes ()

Clears the list of expected message boxes.

See also addExpectedMessageBox(), waitExpectedMessageBox(), and clearExpectedMessageBox().

void QSystemTest::compare ( Variant actual, Variant expected )

Verifies that actual is equal to expected. If this is not the case, the current test fails.

Note that the order of actual and expected is significant, as it affects the test failure message.

Boolean QSystemTest::compareImage ( String expectedName, String queryPath, StringArray maskedWidgets = [] )

Compares the widget specified by queryPath against the reference snapshot expectedName.

maskedWidgets is a list of query paths specifying widgets to be excluded from the snapshot. This allows constantly changing widgets to be hidden from view while the snapshot is taken.

Returns true if the images match, or false otherwise.

The reference snapshot can be one previously learned using verifyImage(), or an image saved using saveScreen(), in which case the .png filename extension must be specified.

See also verifyImage() and saveScreen().

String QSystemTest::currentApplication ()

Returns the name of the application which currently has keyboard focus. The name will be the name returned by QCoreApplication::applicationName(), which is typically the name of the executable file.

Example:

    startApplication("Contacts");

    ...

    // Make sure we are still in contacts
    compare( currentApplication(), "addressbook" );

String QSystemTest::currentDataPath () const

Returns the path in which data for the current test function will be saved to/retrieved from.

The path follows the format baseDataPath/testCaseName/testFunctionName/dataTag, where baseDataPath is the path returned by baseDataPath().

Internally, the current data path does not affect the behaviour of QSystemTest. However, subclasses may use the value returned by this function to decide where to store learned data.

See also baseDataPath() and learnMode().

String QSystemTest::currentDataTag () const

Returns the current data tag, or an empty string if the test function has no test data associated with it. The data tag is the string used to identify each row in the test data table.

Example:

    walkTheDog: function(street) {
        // At the moment, Qt Extended crashes if we walk on concrete; this is
        // a known failure
        if (currentDataTag().startsWith("concrete sidewalk"))
            expectFail("concrete is known to break");

        enter( street, "Destination" );
        select( "Walk the Dog" );
        compare( getText("Status"), "Walked" );
    }
    walkTheDog_data: {
        "concrete sidewalk 1": [ "East St." ],
        "concrete sidewalk 2": [ "West St." ],
        grassy:                [ "North St." ],
        muddy:                 [ "South St." ]
    }

String QSystemTest::currentTestFunction ( Boolean fullName = false ) const

Returns the name of the testfunction that is currently being executed. If fullName is true, the fully qualified name (including the test case name) will be returned.

Example, in a file named sys_mytest:

    testYoyo: function() {
        currentTestFunction(); // returns "testYoyo"
        currentTestFunction(true);  // returns "sys_mytest::testYoyo"
    }

See also testCaseName().

String QSystemTest::currentTitle ( String queryPath = null )

Returns the current window title for the application specified by queryPath. If queryPath contains a widget component, it will be ignored.

Example:

    startApplication("Contacts") );

    ...

    // Make sure we are still in contacts
    compare( currentTitle(), "Contacts" );

See also Query Paths.

String QSystemTest::dateFormat ()

Returns the date format that is currently used on the device.

See also setDateFormat().

void QSystemTest::deletePath ( String path )

Delete path from the test system. Can be a file, or can be a directory tree, in which case the entire tree is recursively deleted. If path contains environment variables, they will be expanded on the test system.

Example:

    // Force test system to start with clean settings
    deletePath("$HOME/Settings");
    restartQtopia();

See also File Management.

void QSystemTest::enter ( String text, String queryPath = null, EnterMode mode = Commit )

Simulates text being entered from a key input device into the widget specified by queryPath. First navigates to the specified widget, then sets the input method hint to null and generates a series of key or mouse clicks.

Most widgets go into an editing mode when entering text and need to be taken out of the editing mode by e.g. a Qt::Key_Select or by navigating to another field in the dialog. By default, enter() will automatically take whatever action is necessary to commit the text and leave edit mode. Set mode to NoCommit to override this.

Example:

    // Enter my job in "Occupation" field.
    enter( "Dog Walker", "Occupation" );
    // Enter my phone number in "Home phone" field.
    enter( "+61 12345", "Home phone" );

See also Query Paths and Keypad Simulation.

void QSystemTest::enter ( QDate date, String queryPath = null, EnterMode mode = Commit )

This is an overloaded member function, provided for convenience.

Simulates date being entered into the widget specified by queryPath.

queryPath must refer to a widget that accepts dates as input (for example, QDateEdit or QCalendarWidget).

Example:

    // Enter my birth date in "Birthday" field.
    var birthday = new QDate(1985, 11, 10);
    enter( birthday, "Birthday" );

See also Query Paths and Keypad Simulation.

void QSystemTest::enter ( QTime time, String queryPath = null, EnterMode mode = Commit )

This is an overloaded member function, provided for convenience.

Simulates time being entered into the widget specified by queryPath.

queryPath must refer to a widget that accepts times as input (for example, QTimeEdit).

Example:

    enter( new QTime(11, 30), "Start" );

See also Query Paths and Keypad Simulation.

void QSystemTest::expectApplicationClose ( Boolean value )

Indicate to the test framework if the application under test is expected to close.

If value is true, the test framework will not report a failure when it loses its connection to the application. If value is false, unexpected application terminations will result in a test failure.

Example:

    expectApplicationClose( true );
    select( "Close" );                // Selecting this causes the current application to close
    expectApplicationClose( false );  // Resume normal checking

void QSystemTest::expectFail ( String reason )

Uses the reason to mark the current testfunction as expected to fail.

void QSystemTest::expectMessageBox ( String title, String text, String option, Number timeout )

Denotes the start of a block of code which, immediately after or during execution, should cause a message box to pop up with the given title and text. When the message box appears, the given menu option will be chosen from the message box softmenu bar (if one exists).

If the message box hasn't appeared by the end of the block of code, the test will wait until the timeout expires. If it still doesn't appear, the current test fails.

If a message box appears which hasn't been marked as expected, the current test fails.

Example:

    // Delete a contact - select "Yes" on the popped-up message box
    // If the message box doesn't pop up, the test fails.
    expectMessageBox("Contacts", "Are you sure you want to delete: " + contact_name + "?", "Yes") {
        select("Delete contact", optionsMenu());
    }

void QSystemTest::fail ( String message )

Immediately fail the current test with the specified message.

String QSystemTest::focusWidget ( String queryPath = null )

Returns the name of the specific widget with input focus specified by queryPath. If queryPath refers to a widget, then the name of the child widget with focus will be returned, otherwise all widgets in the specified application will be queried.

Example:

    // Get the currently focused widget in the current app
    print( focusWidget() );

    // Get the currently active widget in textedit
    var foo = focusWidget("qpe/textedit:");

    // Get the currently active widget on the home screen
    print( focusWidget("qpe:PhoneLauncher[abcde]/HomeScreen[12bd7f8]") );

See also Query Paths.

String QSystemTest::getClipboardText ()

Returns text stored in the clipboard, or an empty string if the clipboard does not contain any text.

See also setClipboardText().

String QSystemTest::getData ( String srcFile )

Reads srcFile from the test system and returns its contents. if srcFile contains environment variables, they will be expanded on the test system.

See also File Management, getFile(), putData(), and putFile().

QDateTime QSystemTest::getDateTime ()

Returns the current date and time of the test system.

See also setDateTime() and setTimeSynchronization().

StringArray QSystemTest::getDirectoryEntries ( String dir, QDir::Filters filters = QDir::NoFilter )

List the contents of directory dir on the test system, applying filters to the listing. If dir contains environment variables, they will be expanded on the test system.

The returned listing will be relative to dir.

Example:

    // Delete entire contents of Documents directory on the test system
    var list = getDirectoryEntries( documentsPath(), QDir.AllEntries);
    for (var i = 0; i < list.length; ++i) {
        deletePath( documentsPath() + list[i]);
    }

See also QDir::entryList() and File Management.

void QSystemTest::getFile ( String srcFile, String destFile )

Retrieves srcFile from the test system and copies it to destFile on the local machine. if srcFile contains environment variables, they will be expanded on the test system.

Example:

    // Copy a settings file to the local machine
    getFile("$HOME/Settings/foo.conf", "/tmp/foo.conf" );

See also File Management, getData(), putData(), and putFile().

QRect QSystemTest::getGeometry ( String queryPath = null )

Returns geometry of the widget specified in queryPath, with position (x,y) co-ordinates being global. Note: QRect does not have toString() method, refer to QRect docs for methods returning common types.

Example:

    // pass the test if widgets do not overlap
    var first_widget = getGeometry("Button1");
    var second_widget = getGeometry("Button2");
    // intersects returns true on overlap, false when not; verify causes test to fail on false
    verify( !first_widget.intersects(second_widget), "Specified widgets overlap.");

Example two - a non-mainstream situation:

select() may work in an undefined manner with custom widgets/items, implementing custom select() methods isn't ideal - each would require writing and testing. On a device with a primary input method of mouse/touchscreen there may not be key code mapping for keys which don't exist - therefore mouse events should be used. However devices may have different geometry, and widget geometry can change between invocations. The example below uses mouseClick() without prior geometry knowledge, though a way is needed to determine where to click, the example shows mouseClick() in the middle of an area defined by the 4th col and 4th row in a uniform grid of the area of the active widget.

    // mouseClick() a widget or item with a fixed position inside its parent widget
    var geo = getGeometry();
    var select_x = geo.x() + (( geo.width() / 8) * 7);
    var select_y = geo.y() + (( geo.height() / 8) * 7);
    mouseClick(select_x, select_y);

See also select(), mouseClick(), and QRect.

StringArray QSystemTest::getLabels ( String queryPath = null )

Returns a list of all the labels that are visible in the current active window or the widget specified by queryPath. A label is usually a non-editable widget (such as a QLabel) that is associated with an editable field. The label is used to give the user a visual clue of the meaning of the editable field. Labels are used by the user, and by QtUitest, to navigate to fields.

The items will be returned in the order they are stored in the widget, i.e. from top to bottom.

Example:

    // Verify that the current dialogs contains Labels named 'Name' and 'Email'
    var g = getLabels();
    QVERIFY( g.length == 2 );
    QVERIFY( g.contains("Name") );
    QVERIFY( g.contains("Email") );

See also Query Paths and Querying Objects.

StringArray QSystemTest::getList ( String queryPath = null )

Returns a list of all items from the list-type widget specified by queryPath.

The items will be returned in the order they are stored in the widget (for example, for a simple list view the items will be returned from top to bottom).

Example:

    // Verify that "gender" combobox contains male and female only
    var g = getList("Gender");
    compare( g.length == 2 );
    verify( g.contains("Male") );
    verify( g.contains("Female") );

getList() can also be used to query for lists from widgets such as the options Menu. Example:

    var L = getList(optionsMenu());

This function will temporarily open the options menu, take a snapshot of the list contents, close the menu again and finally return the list. If the options menu was open already it will be left open.

See also Query Paths and Querying Objects.

QVariant QSystemTest::getProperty ( String queryPath, String name )

Get the value of the Qt property named name on object queryPath on the test system.

Example:

    // Get the text of this field without using getText()
    var t = getProperty("Name", "text").toString();

See also Query Paths and Querying Objects.

String QSystemTest::getSelectedText ( String queryPath = null )

Returns the currently selected text from the widget specified by queryPath. If no text is selected, returns all text. For list-type widgets, returns the text for the currently selected item.

Example:

    // Enter text in two fields, then go back to the first
    // and make sure it still has the right text
    enter("Australia", "Home");
    enter("dog walker", "Occupation");
    compare( getSelectedText("Home"), "Australia" );

See also Query Paths and Querying Objects.

QVariant QSystemTest::getSetting ( String file, String group, String key )

Retrieves a QSettings settings value from the test system located in file, settings group group, key key. If file contains environment variables, they will be expanded on the test system.

Example:

    // What's our primary input mode?
    var primaryInput = getSetting("$QPEDIR/etc/defaultbuttons.conf", "Device", "PrimaryInput");

See also setSetting() and QSettings.

QVariant QSystemTest::getSetting ( String organization, String application, String group, String key )

This is an overloaded member function, provided for convenience.

Retrieves a QSettings settings value from the test system located in the settings file for organization organization and application application, as passed to the QSettings constructor. The settings value retrieved will be group group, key key.

See also setSetting() and QSettings.

String QSystemTest::getText ( String queryPath = null )

Returns all text from the widget specified by queryPath. For list-type widgets, returns the text for all items separated by newlines.

Example:

    // Get current content of "name" field
    select("Name");
    print( getText() );

    // Get current content of "address" field, without navigating to it
    print( getText("Address") );

See also Query Paths and Querying Objects.

void QSystemTest::ignoreMessageBoxes ( Boolean ignore )

If ignore is true, message boxes will be ignored by the test framework. Under normal circumstances during automated testing, message boxes need to be processed. However, short-lived, self dismissing message boxes may disappear before the test framework can handle them. Set ignore to false to resume normal processing of message boxes.

See also addExpectedMessageBox(), expectMessageBox(), clearExpectedMessageBox(), clearExpectedMessageBoxes(), and waitExpectedMessageBox().

Boolean QSystemTest::invokeMethod ( String queryPath, String method, Qt::ConnectionType type, QVariant arg0 = null, QVariant arg1 = null, QVariant arg2 = null, QVariant arg3 = null, QVariant arg4 = null, QVariant arg5 = null, QVariant arg6 = null, QVariant arg7 = null, QVariant arg8 = null, QVariant arg9 = null )

Invoke method method on object queryPath on the test system. Invokable methods include only Qt signals and slots.

The method will be invoked using the Qt connection type type. This can almost always be Qt::AutoConnection, but in a few cases Qt.QueuedConnection may be necessary (for example, if executing a method that will cause Qt Extended to shutdown, Qt.QueuedConnection should be used to ensure Qt Extended sends a response to the system test before shutting down).

The optional arguments arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8 and arg9 will be passed to the method if given.

Returns true if the method could be invoked, false otherwise.

Example:

    // Hide this field because it keeps changing and we want a snapshot
    QVERIFY( invokeMethod("Time", "setVisible(bool)", Qt.AutoConnection, false) );
    verifyImage("good_snapshot");
    // Put the field back
    QVERIFY( invokeMethod("Time", "setVisible(bool)", Qt.AutoConnection, true) );

See also Query Paths and Querying Objects.

Boolean QSystemTest::invokeMethod ( String queryPath, String method, QVariant arg0 = null, QVariant arg1 = null, QVariant arg2 = null, QVariant arg3 = null, QVariant arg4 = null, QVariant arg5 = null, QVariant arg6 = null, QVariant arg7 = null, QVariant arg8 = null, QVariant arg9 = null )

This is an overloaded member function, provided for convenience.

Invokes the given method using connection type Qt.AutoConnection.

Boolean QSystemTest::isBuildOption ( String option )

Returns whether the compile time option is defined.

Boolean QSystemTest::isChecked ( String queryPath )

Returns the checked state of the checkbox-like widget specified by queryPath. Checkbox-like widgets include QCheckBox and anything inheriting QAbstractButton.

See also Query Paths, Querying Objects, and setChecked().

Boolean QSystemTest::isEnabled ( String queryPath )

The function returns whether the widget specified by queryPath is enabled.

Example:

    // Verify the AM/PM field is disabled when using 24 hour format
    select("24 hour", "Time format");
    QVERIFY2( !isEnabled("AM-PM"), "AM-PM field still enabled." );

See also Query Paths and Querying Objects.

Boolean QSystemTest::isVisible ( String queryPath )

Returns true if the widget specified by queryPath exists and is currently visible to the user.

The widget is considered to be visible to the user if QWidget::visibleRegion() returns a non-empty region. Thus, isVisible() will return true if even a single pixel of the widget is unobscured.

See also Query Paths and Querying Objects.

void QSystemTest::keyClick ( Qt::Key key, String queryPath = null )

Simulates a key click (press and release) for the application specified by queryPath. key is a string describing the key to be released.

Example:

    // Go right 5 times, then select
    for (int i = 0; i < 5; ++i) keyClick( Qt.Key_Right );
    keyClick( Qt.Key_Select );

See also Query Paths and Keypad Simulation.

void QSystemTest::keyClickHold ( Qt::Key key, Number duration, String queryPath = null )

Simulates a key click and hold (press + wait + release) for queryPath. The interval between press and release is set in milliseconds by duration.

Example:

    // Hold hangup key to bring up shutdown app
    keyClickHold(Qt.Key_Hangup, 3000);

See also Query Paths and Keypad Simulation.

void QSystemTest::keyPress ( Qt::Key key, String queryPath = null )

Simulates a key press for the application specified by queryPath. key is a Qt::Key describing the key to be pressed.

Example:

    // Press (do not release) F23 key in current app
    keyPress( Qt.Key_F23 );

See also Query Paths and Keypad Simulation.

void QSystemTest::keyRelease ( Qt::Key key, String queryPath = null )

Simulates a key release for the application specified by queryPath. key is a Qt::Key describing the key to be released.

Example:

    // Release Up key in current app
    keyRelease( Qt.Key_Up );

See also Query Paths and Keypad Simulation.

LearnMode QSystemTest::learnMode () const

Returns the current learn mode.

See also setLearnMode().

void QSystemTest::mouseClick ( Number x, Number y )

Simulates a mouse click / touchscreen tap at co-ordinates ( x, y ).

Example:

    mouseClick(200, 300);

See also Query Paths and Mouse / Touchscreen Simulation.

void QSystemTest::mouseClick ( String queryPath )

This is an overloaded member function, provided for convenience.

Simulates a mouse click / touchscreen tap at the center of the widget specified by queryPath.

Example:

    // Click on Accept button
    mouseClick("Accept");

See also Query Paths and Mouse / Touchscreen Simulation.

void QSystemTest::mouseClickHold ( Number x, Number y, Number duration )

Simulates a mouse click / touchscreen tap at co-ordinates ( x, y ), with a custom duration in milliseconds between press and release.

Example:

    // Hold at (200, 300) for three seconds
    mouseClickHold(200, 300, 3000);

See also Query Paths and Mouse / Touchscreen Simulation.

void QSystemTest::mouseClickHold ( String queryPath, Number duration )

This is an overloaded member function, provided for convenience.

Simulates a mouse click / touchscreen tap at the center of the widget specified by queryPath, with a custom duration in milliseconds between press and release.

Example:

    // Hold on the "Shutdown" button for three seconds
    mouseClickHold("Shutdown", 3000);

See also Query Paths and Mouse / Touchscreen Simulation.

Boolean QSystemTest::mousePreferred ()

Returns true if the primary input method is mouse/touchscreen.

See also Qtopia::mousePreferred().

void QSystemTest::mousePress ( Number x, Number y )

Simulates a mouse / touchscreen press at co-ordinates ( x, y ).

Example:

    mousePress(200, 300);

See also Query Paths and Mouse / Touchscreen Simulation.

void QSystemTest::mousePress ( String queryPath )

This is an overloaded member function, provided for convenience.

Simulates a mouse / touchscreen press at the center of the widget specified by queryPath.

Example:

    // Press "Edit" button
    mousePress("Edit");

See also Query Paths and Mouse / Touchscreen Simulation.

void QSystemTest::mouseRelease ( Number x, Number y )

Simulates a mouse / touchscreen release at co-ordinates ( x, y ).

Example:

    mouseRelease(200, 300);

See also Query Paths and Mouse / Touchscreen Simulation.

void QSystemTest::mouseRelease ( String queryPath )

This is an overloaded member function, provided for convenience.

Simulates a mouse / touchscreen release at the center of the widget specified by queryPath.

Example:

    // Release mouse over "Edit" button
    mouseRelease("Edit");

See also Query Paths and Mouse / Touchscreen Simulation.

String QSystemTest::optionsMenu ()

Returns an alias that will be resolved by Qt Extended to find the Options Menu. Example:

    select( "New", optionsMenu() ); // select the item with text 'New' from the options menu
    print( signature(optionsMenu()) ); // to print the name of the resolved widget.

Note that 'signature(optionsMenu())' incurs an extra roundtrip and should only be used in exceptional cases.

The test will fail if no options menu can be activated, or if multiple option menus are found.

See also tabBar() and progressBar().

String QSystemTest::progressBar ()

Returns an alias that will be resolved by Qt Extended to find the currently visible progress bar. Example:

    print( getText(progressBar()) ); // prints the text currently shown by the progress bar.
    print( signature(progressBar()) ); // to print the name of the current progress bar.

Note that 'signature(progressBar())' incurs an extra roundtrip and should only be used in exceptional cases.

The test will fail if no visible progress bar is found, or if multiple progress bars are found.

See also optionsMenu() and tabBar().

void QSystemTest::prompt ( String promptText = null )

Displays a dialog with the promptText and Pass/Fail/Record buttons, then waits for a response from the user. If Pass is clicked, the test will continue. If Fail is clicked, a failure will be generated and the current testcase will abort. If Record is clicked, event recording will start and recorded events can be appended to the testcase once recording is finished.

This function is intended to be used for verification of testcases that cannot be fully automated. Testcases containing this function will be skipped if the test is run with the -auto option.

Example:

    prompt( "Did something totally amazing just happen?" );

By using a prompt() the process of automating testcases can be an iterative process. In the first iteration the whole testcase can be a manual test and the systemtest merely is used as a complex mechanism to show a dialog. For example:

    void sys_mytest::test1()
    {
        prompt(
            "step 1: Start application foo\n"
            "step 2: Select 'Properties' from Options Menu\n"
            "step 3: Enter several fields in the properties dialog\n"
            "step 4: Close dialog\n"
            "step 5: Do something to verify that the properties are set correctly"
        );
    }

In the above example the user/tester has to perform all the steps manually and then click on Pass or Fail to indicate the success of the testcase.

A reason for writing a fully manual test might be that it is extremely difficult to write an automated test, or it's simply not clear yet how to write an automated test. As time progresses however usually an understanding is build up of how to automate the test, or parts of the test. Even if part of the test is automated there is already an advantage. In the previous example for instance it would already be advantageous if the application was started by the test framework and then the rest was a few manual steps.

For example:

    void sys_mytest::test1()
    {
        select( "foo", launcherMenu() ); // use test framework to start application using the launcher.
        select( "Properties", optionsMenu() ); // and select an option from the options menu

        prompt(
            "step 3: Enter several fields in the properties dialog\n"
            "step 4: Close dialog\n"
            "step 5: Do something to verify that the properties are set correctly"
        );
    }

The first two steps are now automated, the rest is still manual.

Next we realize that entering the data in the properties can also be automated:

    void sys_mytest::test1()
    {
        startApp( "foo" ); // use test framework to start application
        select( "Properties", optionsMenu() ); // and select an option from the options menu

        // enter the properties
        enter( "dungeon&dragons", "Name" );
        enter( "example.org", "Server" );

        // close dialog
        select( "Back", softMenu() );

        prompt( "step 5: Do something to verify that the properties are set correctly" );
    }

The testcase now has only one manual (verification) step left. But the biggest advantage is that the 'entering data' part of the test is now automated. If the testcase was extended with a few sets of testdata the same routine could be used many times, and for instance could be testing multiple languages without any effort from the tester.

void QSystemTest::putData ( QByteArray data, String destFile, QFile::Permissions permissions = 0 )

Transfers data from the local machine and copies it to destFile on the test system. if destFile contains environment variables, they will be expanded on the test system. The file permissions of the destination file can be specified using permissions.

See also File Management and putFile().

void QSystemTest::putFile ( String srcFile, String destFile, QFile::Permissions permissions = 0 )

Transfers srcFile from the local machine and copies it to destFile on the test system. if destFile contains environment variables, they will be expanded on the test system.

By default, the file permissions of the destination file will be set to those of the source file. This can be overridden by specifying permissions.

Example:

    // Force test system to use certain settings
    putFile("testdata/my_settings.conf", "$HOME/Settings/foo.conf");

    // Specify file permissions
    putFile("testdata/my_file", "$HOME/my_file", QFile.WriteOwner | QFile.ReadOwner | QFile.ReadOther);

See also File Management and putData().

String QSystemTest::runProcess ( String application, StringArray args, String input )

Runs application with arguments args on the local machine, with input given as standard input. The combined stderr and stdout text will be returned.

If the process fails to run or returns a non-zero exit code, the current test fails.

Boolean QSystemTest::runsOnDevice ()

Returns true if the test is running on an actual device, and false if it is running in a virtual framebuffer (on the desktop machine).

void QSystemTest::saveScreen ( String name, String queryPath = "qpe:" )

Take a full screenshot of Qt Extended and save it as name. The screenshot will be placed in the test data directory in PNG format, and will automatically have .png appended to the name.

This function is intended to be used as a simple way to automate the gathering of screenshots, i.e. to be used in documentation and such.

If a queryPath is specified the snapshot will be limited to the Widget that is identified by the queryPath.

Example:

    // Take snapshots of home screen and launcher grid
    gotoHome();
    saveScreen("homescreen");
    keyClick( Qt::Key_Select );
    saveScreen("launcher");

See also verifyImage().

void QSystemTest::select ( String item, String queryPath = null )

Selects the item from the application/widget specified by queryPath. This can be used to, e.g., select a certain item from a list widget or combo box. select() works with widgets which are conceptually a list, including list views, combo boxes and menus.

When used with a list widget, the specified item is navigated to and no further action is taken.

When used with a combo box, the drop-down list is opened, the item is selected, and the drop-down list is closed again.

Items in submenus are denoted using '/' delimiters (e.g., "View/All" means navigate to the "View" submenu, then the "All" item). Menu items which have a '/' in their name can be escaped using '' (e.g. "Add\/Remove Words").

Example:

    // Select "Female" from "Gender" field
    select("Female", "Gender");

If the queryPath is set to optionsMenu(), select will attempt to select the item from the Options Menu of the current application.

Items in submenus can be specified by separating items with a '/'. If an item contains a '/', escape it with a backslash.

Example:

    // Select the "All Added" option from the "Show Only" submenu in the options menu.
    select( "Show only.../All Added", optionsMenu() );

    // Select the 'Word Lookup/Add' option from the options menu.
    select( "Word Lookup\\/Add", optionsMenu() );

See also Query Paths and Keypad Simulation.

void QSystemTest::set12HourTimeFormat ( Boolean ampm = true )

Sets the time format on the device to ampm. Accepted values for ampm:

• true: Time format is set to 12 hour mode,
• false: Time format is set to 24 hour mode.

See also setDateFormat().

void QSystemTest::setBaseDataPath ( String path )

Set the path which functions as the root directory to all of the test data.

The base data path contains the test data for functions such as verifyImage(). It can also be used within a test to use testdata stored in files.

See also baseDataPath().

void QSystemTest::setChecked ( Boolean doCheck, String queryPath )

Based on the value of doCheck checks or un-checks a checkbox-like widget specified by queryPath. Checkbox-like widgets include QCheckBox and anything inheriting QAbstractButton.

See also Query Paths, Querying Objects, and isChecked().

void QSystemTest::setClipboardText ( String text )

Copies text into the clipboard.

See also getClipboardText().

void QSystemTest::setDateFormat ( String dateFormat = "D/M/Y" )

Sets the date format on the device to dateFormat. Accepted values for dateFormat:

• "English (U.S.)" : sets date format to "M/D/Y".
• "D/M/Y" : sets date format to "D/M/Y"
• "D.M.Y" : sets date format to "D.M.Y"
• "M/D/Y" : sets date format to "M/D/Y"
• "Y-M-D" : sets date format to "Y-M-D"

See also dateFormat() and set12HourTimeFormat().

void QSystemTest::setDateTime ( QDateTime dateTime, String timeZone = null )

Sets date and time to dateTime on the test system.

If specified the timeZone will also be set.

Setting the time generally requires root access on the test system. However, this will also work for a test build of Qt Extended on the desktop, if Qt Extended is launched by the system test using the runqtopia script.

Example:

    setDateTime( QDateTime( 2007, 5, 27, 23, 59, 59 ), "Australia/Brisbane" );

The entered date is entered in the sequence: year, month, day, hour, minute, second

If the time synchronization is set to AutoTimeSynchronizationMode any attempt to set the date and time will result in a fail.

See also getDateTime() and setTimeSynchronization().

void QSystemTest::setLearnMode ( LearnMode mode )

Sets the current learn mode.

See also learnMode().

void QSystemTest::setProperty ( String queryPath, String name, QVariant value )

Set the Qt property named name on object queryPath to value value on the test system.

Errors can occur in this function.

Example:

    // Set the text of this field without simulating key presses
    setProperty("Name", "text", "Billy Jones");

See also Query Paths and Querying Objects.

void QSystemTest::setSetting ( String file, String group, String key, QVariant value )

Set a QSettings settings value on the test system located in file, settings group group, key key.

Example:

    // Turn on english and deutsch input languages
    setSetting("$HOME/Settings/Trolltech/locale.conf", "Language", "InputLanguages", "en_US de" );

See also getSetting() and QSettings.

void QSystemTest::setSetting ( String organization, String application, String group, String key, QVariant value )

This is an overloaded member function, provided for convenience.

Set a QSettings settings value on the test system located in the settings file for the given organization and application, as passed to a QSettings constructor. The value set will be in settings group group, key key.

See also getSetting() and QSettings.

Number QSystemTest::setTimeSynchronization ( TimeSynchronizationMode mode )

Sets the time synchronization mode on the device to mode. This action should be equivalent to 'opening the Date/Time application and then setting the time mode to 'Auto vs Manual'.

When mode is HostTimeSynchronization the mode is set to 'Manual' on the device and then the time is synchronized with the time on the host machine, i.e. the machine on which the system test is running. The returned value is the approximate amount of time the device was adjusted (in seconds).

Note: Host time synching has an accuracy of +- 1 second.

See also getDateTime() and setDateTime().

void QSystemTest::setTimeZone ( String timeZone )

Sets the timeZone on the device.

See also timeZone().

void QSystemTest::setVisibleResponseTime ( Number time )

Sets the Visual Response Time to time.

See also visibleResponseTime() and waitForTitle().

String QSystemTest::signature ( String labelText, Number offset = 0 )

Returns the signature of the buddy widget that is associated with labelText. A buddy relationship usually exists between a QLabel (or QIconSelector) class and an editable field such as a QLineEdit. The label tells the user what data should be entered into the editable field.

The buddy relationship in QtUitest is determined by:

the 'buddy' value is set in the Label, or the Label/IconSelector and the editable field are displayed next to each other, or the 'buddy' is a child of a GroupBox

If offset is a number != 0 the query will return the n'th next or previous buddy field. This can be used for exceptional situations where a field doesn't have a label associated with it.

The signature() function only needs to be used in exceptional cases: the preferred mechanism is to identify fields by their Label text.

See also Query Paths, Querying Objects, and QObject::inherits().

void QSystemTest::skip ( String message, SkipMode mode )

Cause a test to skip with the given message and mode.

void QSystemTest::startApplication ( String application, Number timeout = 5000, QSystemTest::StartApplicationFlags flags = QSystemTest::WaitForFocus )

Start the specified application.

application is the combined path and arguments of a program to launch. The application must connect to the test framework within timeout ms or the test fails.

flags specifies additional behaviour.

See also Application Management.

void QSystemTest::strict ( Boolean on = true )

Switches the 'strict syntax' checking mode for the System test to on.

In strict mode the following commands are no longer allowed and will cause an immediate failure:

keyClick() keyPress() keyRelease() keyClickHold()

Strict mode also verifies that every 'Title' change is covered by a call to waitForTitle(): any action that results in a Dialog to be shown (with a different title) will cause a test failure unless a waitForTitle() is called on the next line of the test script.

void QSystemTest::synchronizeDateTime ()

Synchronizes the date and time on the device to the current date/time of the host computer, i.e. the machine on which the system test is running.

This generally requires root access on the test system. However, this will also work for a test build of Qt Extended on the desktop, if Qt Extended is launched by the system test using the runqtopia script.

Example:

    synchronizeDateTime();

If the time synchronization is set to AutoTimeSynchronizationMode any attempt to set the date and time will result in a fail.

See also getDateTime() and setTimeSynchronization().

String QSystemTest::tabBar ()

Returns an alias that will be resolved by Qt Extended to find the currently active TabBar. Example:

    select( "Personal", tabBar() ); // select the tab with text 'Personal' from the tab bar.
    print( signature(tabBar()) ); // to print the name of the resolved widget.

Note that 'signature(tabBar())' incurs an extra roundtrip and should only be used in exceptional cases.

The test will fail if no visible tabbar is found, or if multiple tabbars are found.

See also optionsMenu() and progressBar().

String QSystemTest::testCaseName () const

Returns the name of the currently executing test case.

See also currentTestFunction().

String QSystemTest::timeFormat ()

Returns the time format that is currently used on the device.

String QSystemTest::timeZone ()

Returns the time zone that is currently used on the device.

See also setTimeZone().

String QSystemTest::userName ()

Returns the username that is running the test on the desktop machine.

void QSystemTest::verify ( Boolean condition, String message = null )

Verifies that condition is true. If condition is not true, the current test fails. If message is given, it will be appended to the failure message.

Example:

    select("Frank", "Contacts");
    waitForTitle("Details: Frank");
    var details = getText();
    // Verify that Frank's phone number is shown somewhere
    verify( details.contains("12345") );
    // Same, but with more details in error message
    verify( details.contains("12345"), "Frank's phone number is missing!" );

void QSystemTest::verifyImage ( String expectedName, String queryPath = null, String comment = null, StringArray maskedWidgets = [] )

Grabs a snapshot of the widget specified by queryPath, and compares it against the reference snapshot expectedName.

New snapshots are gathered by running the test in learn mode, and are stored in the testdata subdirectory of the directory containing the test script. When learn mode is used, a failed image comparison will result in a tester being presented with a manual verification dialog.

If there is a mismatch between the images, the current test fails.

When in learn mode, if comment is provided it will be shown to the user to help in determining whether or not the pixmap should be accepted.

maskedWidgets is a list of query paths specifying widgets to be excluded from the snapshot. This allows constantly changing widgets to be hidden from view while the snapshot is taken.

Example:

    select("Mark task complete", optionsMenu());
    verifyImage( "task_completed", "", "Verify that the current task is shown with a green tick indicating completion" );

See also saveScreen().

Number QSystemTest::visibleResponseTime ()

Returns the currently set Visual Response Time. This time is used in QtUiTest to decide whether the User Interface is responsive to user events. For instance, after selecting "New Event" from the options menu a user expects a dialog in which a new event can be entered. If Qt Extended does not respond in some visible way within the visual response time, the test will fail.

By default the visual response time is set to 4 seconds, i.e. any UI that doesn't respond to events within this time is considered at fault.

The visibleResponseTime is also used as the default value for some queries such as waitForTitle().

See also setVisibleResponseTime() and waitForTitle().

void QSystemTest::wait ( Number msecs )

Wait for msecs milliseconds, while still processing events from the event loop.

Boolean QSystemTest::waitExpectedMessageBox ( Number timeout, Boolean waitForAll = true, String title = null, String text = null )

Waits for expected message boxes to occur up until a maximum of timeout ms. Returns true if the expected message box occurs during or before this function.

It is an error to call this function for a message box which has not been passed to expectMessageBox() or addExpectedMessageBox().

If waitForAll is true (the default) ALL messageBoxes will need to be shown before the wait terminates, or else it is sufficient if any of the expected message boxes has been shown.

When a title and text are specified the function will wait until that specific message box has been shown. Note that specifying a title and text only makes sense when waitForAll is set to false.

See also addExpectedMessageBox(), clearExpectedMessageBox(), clearExpectedMessageBoxes(), and expectMessageBox().

void QSystemTest::waitFor ( Number timeout = 10000, Number intervals = 20, String message = null )

Denotes the start of a block of code which should be repeatedly executed until it returns true. If the block of code doesn't return true within timeout milliseconds, the current test fails with the given message.

intervals is the maximum amount of times the block of code should be executed; i.e., the code will be executed every timeout / intervals milliseconds.

Example:

    // Start scanning for bluetooth devices, and wait a while until the list of
    // bluetooth devices is not empty.
    select("Scan...",optionsMenu());
    waitFor() {
        return getList().length > 0;
    }

void QSystemTest::waitForTitle ( String title, Number timeout = 0 )

Waits for the current title to change to title The test fails if the current title hasn't changed to title within timeout ms.