|
Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions | |
The QSystemTest namespace provides script based system test functionality for Qt. More...
#include <QSystemTest>
This namespace is under development and is subject to change.
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.
The Array type as documented in ECMA-262, section 15.4.
The following extensions are provided in QtUiTest.
| Boolean Array.prototype.contains(value) | Returns true if the array contains the given value. |
The Boolean type as documented in ECMA-262, section 15.6.
This enum specifies whether enter() should commit the entered value (eg, by simulating a Select keypress) or not.
| Constant | Value | Description |
|---|---|---|
| QSystemTest::Commit | 0x00 | Commit the value (default). |
| QSystemTest::NoCommit | 0x01 | Do not commit the value. |
The Function type as documented in ECMA-262, section 15.3.
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.
| Constant | Value | Description |
|---|---|---|
| QSystemTest::LearnNone | 0 | Learn mode is off. Any mismatches encountered will cause a test failure. |
| QSystemTest::LearnNew | 1 | The test should attempt to learn data which does not match existing test data. |
| QSystemTest::LearnAll | 2 | The test should attempt to learn all data, even if it matches existing test data. |
See also learnMode(), setLearnMode(), and verifyImage().
The Number type as documented in ECMA-262, section 15.7.
An Array object in which every element is a QVariant.
This enum describes the modes for skipping tests during execution of the test data.
| Constant | Value | Description |
|---|---|---|
| QSystemTest::SkipSingle | 0x01 | Skip the rest of this test function for the current test data entry, but continue execution of the remaining test data. |
| QSystemTest::SkipAll | 0x02 | Skip the rest of this test function, and do not process any further test data for this test function. |
See also skip() and QTest::SkipMode.
This enum describes additional behaviour to use when starting applications by startApplication().
| Constant | Value | Description |
|---|---|---|
| QSystemTest::NoFlag | 0x00 | Don't apply any of the below flags. |
| QSystemTest::WaitForFocus | 0x01 | Wait for the application to gain keyboard focus before returning. |
| QSystemTest::BackgroundCurrentApplication | 0x02 | Use multitasking to background the current application. The default behaviour is to exit the current application. |
The StartApplicationFlags type is a typedef for QFlags<StartApplicationFlag>. It stores an OR combination of StartApplicationFlag values.
The String type as documented in ECMA-262, section 15.5.
The following extensions are provided in QtUiTest.
| Boolean String.prototype.contains(String text) | Returns true if the string contains the given text. |
| Boolean String.prototype.contains(QRegExp regex) | Returns true if the string is matched by the given regular expression. |
| Boolean String.prototype.startsWith(String text) | Returns true if the string starts with the given text. |
| String String.prototype.left(Number n) | Returns the first n characters of the string. |
| String String.prototype.right(Number n) | Returns the last n characters of the string. |
An Array object in which every element is a String.
This enum defines the mode that is used to synchronize the device system time.
| Constant | Value | Description |
|---|---|---|
| QSystemTest::HostTimeSynchronization | 0x00 | Switches time synchronization to manual and syncs the device to the host machine time. |
| QSystemTest::ManualTimeSynchronization | 0x01 | Switches time synchronization to manual. |
| QSystemTest::AutoTimeSynchronization | 0x02 | Switches time synchronization to automatic. The device will use the network time as provided by a Phone Network to set the device system time. |
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().
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().
Removes the message box with the given title and text from the list of expected message boxes.
See also addExpectedMessageBox() and waitExpectedMessageBox().
Clears the list of expected message boxes.
See also addExpectedMessageBox(), waitExpectedMessageBox(), and clearExpectedMessageBox().
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.
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().
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" );
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().
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." ]
}
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().
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.
Returns the date format that is currently used on the device.
See also setDateFormat().
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.
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.
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.
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.
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
Uses the reason to mark the current testfunction as expected to fail.
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()); }
Immediately fail the current test with the specified message.
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.
Returns text stored in the clipboard, or an empty string if the clipboard does not contain any text.
See also setClipboardText().
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().
Returns the current date and time of the test system.
See also setDateTime() and setTimeSynchronization().
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.
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().
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.
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.
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.
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.
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.
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.
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.
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.
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().
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.
This is an overloaded member function, provided for convenience.
Invokes the given method using connection type Qt.AutoConnection.
Returns whether the compile time option is defined.
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().
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.
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.
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.
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.
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.
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.
Returns the current learn mode.
See also setLearnMode().
Simulates a mouse click / touchscreen tap at co-ordinates ( x, y ).
Example:
mouseClick(200, 300);
See also Query Paths and Mouse / Touchscreen Simulation.
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.
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.
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.
Returns true if the primary input method is mouse/touchscreen.
See also Qtopia::mousePreferred().
Simulates a mouse / touchscreen press at co-ordinates ( x, y ).
Example:
mousePress(200, 300);
See also Query Paths and Mouse / Touchscreen Simulation.
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.
Simulates a mouse / touchscreen release at co-ordinates ( x, y ).
Example:
mouseRelease(200, 300);
See also Query Paths and Mouse / Touchscreen Simulation.
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.
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().
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().
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.
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().
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().
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.
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).
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().
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.
Sets the time format on the device to ampm. Accepted values for ampm:
See also setDateFormat().
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().
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().
Copies text into the clipboard.
See also getClipboardText().
Sets the date format on the device to dateFormat. Accepted values for dateFormat:
See also dateFormat() and set12HourTimeFormat().
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().
Sets the current learn mode.
See also learnMode().
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.
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.
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.
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().
Sets the timeZone on the device.
See also timeZone().
Sets the Visual Response Time to time.
See also visibleResponseTime() and waitForTitle().
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().
Cause a test to skip with the given message and mode.
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.
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.
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().
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().
Returns the name of the currently executing test case.
See also currentTestFunction().
Returns the time format that is currently used on the device.
Returns the time zone that is currently used on the device.
See also setTimeZone().
Returns the username that is running the test on the desktop machine.
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!" );
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().
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().
Wait for msecs milliseconds, while still processing events from the event loop.
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().
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; }
Waits for the current title to change to title The test fails if the current title hasn't changed to title within timeout ms.
| Copyright © 2009 Trolltech | Trademarks | Qt Extended 4.4.3 |