QtUiTest Namespace Reference
[QtUiTestModule]

Detailed Description

The QtUiTest namespace provides the plugin interfaces used for customizing the behaviour of QtUiTest.

When running a Qt Extended system test, functions such as select() and getText() are used to perform actions and retrieve information from widgets in Qtopia. This is implemented by wrapping each conceptual widget (which is not necessarily a QWidget) with a test widget class.

These test widgets each implement one or more of the widget interfaces in the QtUiTest namespace. The interfaces are used to determine what actions can be taken on a particular widget, and how to perform them.

For example, when the following system test code executes:

    select("Dog", "Favorite Animal");

QtUiTest will first look up the QWidget which is labelled by the text "Favorite Animal". It will then use qtuitest_cast to cast this widget to a QtUiTest::SelectWidget. If this is successful, it will then call select("Dog") on the list widget.

It is possible to customize the behavior of QtUiTest for particular widgets by creating custom test widget classes and a QtUiTest::WidgetFactory factory class to wrap QObject instances in test widgets.

Classes

class ActivateWidget

The ActivateWidget class provides an abstract base class for all test widgets which can conceptually be "activated" by a user. More...

class CheckWidget

The CheckWidget class provides an abstract base class for all test widgets which support 'checked' and 'unchecked' states. More...

class InputWidget

The InputWidget class provides an abstract base class for all test widgets which allow the user to input text. More...

class LabelWidget

The LabelWidget class provides an abstract base class for all test widgets which are conceptually labels. More...

class ListWidget

The ListWidget class provides an abstract base class for all test widgets which display a list of items to the user. More...

class SelectWidget

The SelectWidget class provides an abstract base class for all test widgets which allow the user to select from a range of items. More...

class TextWidget

The TextWidget class provides an abstract base class for all test widgets which display text to the user. More...

class Widget

The Widget class provides an abstract base class for all test widgets. More...

class WidgetFactory

The WidgetFactory class provides a factory interface for QtUiTest widget wrapper classes. More...

Type Documentation

enum QtUiTest::InputOption

This enum type specifies the options to be used when simulating key and mouse events.

enum QtUiTest::Key

This enum provides mappings for high-level conceptual keys to platform-specific values of Qt::Key.

enum QtUiTest::WidgetType

This enum type specifies different types of widgets which can be retrieved via QtUiTest::findWidget().

Function Documentation

Qt::Key QtUiTest::asciiToKey ( char c )

Returns the Qt::Key corresponding to c.

This function is commonly used in conjunction with keyClick() to enter a string of characters using the keypad.

Example:

    using namespace QtUiTest;
    QString text = "hello world";
    // ...
    foreach (QChar c, text) {
        keyClick( asciiToKey(c.toLatin1()), asciiToModifiers(c.toLatin1()) );
    }

Qt::KeyboardModifiers QtUiTest::asciiToModifiers ( char c )

Returns any Qt::KeyboardModifiers which would be required to input c.

This function is commonly used in conjunction with keyClick() to enter a string of characters using the keypad.

Example:

    using namespace QtUiTest;
    QString text = "hello world";
    // ...
    foreach (QChar c, text) {
        keyClick( asciiToKey(c.toLatin1()), asciiToModifiers(c.toLatin1()) );
    }

bool QtUiTest::connectFirst ( const QObject * sender, const char * signal, const QObject * receiver, const char * method )

Creates a connection from the signal in the sender object to the method in the receiver object. Returns true if the connection succeeds; otherwise returns false.

This function behaves similarly to QObject::connect() with the following important differences.

• The connection is guaranteed to be activated before any connections made with QObject::connect().
• The connection type is always Qt::DirectConnection.
• The connection cannot be disconnected using QObject::disconnect() (QtUiTest::disconnectFirst() must be used instead).
• The connection does not affect the return value of QObject::receivers().
• While method is being executed, the return value of QObject::sender() is undefined.
• QObject::connectNotify() is not called on the sending object.

This function is primarily used in conjunction with QtUiTestRecorder to ensure events are recorded in the correct order.

Note that this function cannot be used in a program which uses QSignalSpy.

See also QObject::connect() and QtUiTest::disconnectFirst().

bool QtUiTest::disconnectFirst ( const QObject * sender, const char * signal, const QObject * receiver, const char * method )

Disconnects signal in object sender from method in object receiver. Returns true if the connection is successfully broken; otherwise returns false.

The connection must have been established with QtUiTest::connectFirst().

Passing null arguments has the same wildcard effects as documented in QObject::disconnect().

If the same connection has been established multiple times, disconnectFirst() will disconnect all instances of the connection. There is no way to disconnect a single instance of a connection. This behavior matches QObject::disconnect().

See also QObject::disconnect() and QtUiTest::connectFirst().

QString QtUiTest::errorString ()

Returns a human-readable error string describing the last error which occurred while accessing a testwidget.

The error string is used to report directly to a tester any unexpected errors. The string will typically be used as a test failure message.

See also setErrorString().

QObject * QtUiTest::findWidget ( WidgetType type )

Returns a widget or test widget wrapper of type.

QtUiTest will attempt to find widgets by calling QtUiTest::WidgetFactory::find() on all loaded widget factories.

Note that it is possible to call this function from an application where the only widget of type exists in the server. In this case, the reference implementation returns a special wrapper which transparently communicates with the server when calling functions. However, if custom factories are used which do not do this, this function is likely to return 0 in this case.

Example:

    using namespace QtUiTest;
    bool MyTextEdit::enter(QVariant const& item) {
        // Instead of explicitly simulating mouse or key clicks,
        // enter the text via the current input method.
        // Note that this works whether or not the input method is located in
        // the current process.
        InputWidget *iw = qtuitest_cast<InputWidget*>(findWidget(InputMethod));
        return (iw && iw->enter(item));
    }

void QtUiTest::keyClick ( int key, Qt::KeyboardModifiers modifiers = 0, InputOption options = NoOptions )

Simulate a key click event, using the given key and modifiers. key must be a valid Qt::Key or QtUiTest::Key. options are applied to the simulated event.

bool QtUiTest::keyClick ( QObject * object, int key, Qt::KeyboardModifiers modifiers = 0, InputOption options = NoOptions )

This is an overloaded member function, provided for convenience.

Simulate a key click event. Returns true if the event appears to be delivered to object within maximumUiTimeout() milliseconds. If it does not, the errorString() will be set accordingly.

bool QtUiTest::keyClick ( QObject * object, QByteArray const & signal, int key, Qt::KeyboardModifiers modifiers = 0, InputOption options = NoOptions )

This is an overloaded member function, provided for convenience.

Simulate a key click event. Returns true if object emits signal within maximumUiTimeout() milliseconds. If it does not, the errorString() will be set accordingly.

void QtUiTest::keyPress ( int key, Qt::KeyboardModifiers modifiers = 0, InputOption options = NoOptions )

Simulate a key press event, using the given key and modifiers. key must be a valid Qt::Key or QtUiTest::Key. options are applied to the simulated event.

void QtUiTest::keyRelease ( int key, Qt::KeyboardModifiers modifiers = 0, InputOption options = NoOptions )

Simulate a key release event, using the given key and modifiers. key must be a valid Qt::Key or QtUiTest::Key. options are applied to the simulated event.

int QtUiTest::maximumUiTimeout ()

Returns the maximum amount of time, in milliseconds, the user interface is allowed to take to generate some response to a user's action.

This value is useful to determine how long test widgets should wait for certain events to occur after simulating key/mouse events. The value may be device-specific.

void QtUiTest::mouseClick ( QPoint const & pos, Qt::MouseButtons buttons = Qt::LeftButton, InputOption options = NoOptions )

Simulate a mouse click event at the global co-ordinates given by pos, for the specified buttons. options are applied to the simulated event.

For Qt Extended, pos is interpreted as global screen co-ordinates. For all other platforms, pos is interpreted as local co-ordinates for the currently active window in this application.

bool QtUiTest::mouseClick ( QObject * object, QPoint const & pos, Qt::MouseButtons buttons = Qt::LeftButton, InputOption options = NoOptions )

This is an overloaded member function, provided for convenience.

Simulate a mouse click event. Returns true if the event appears to be delivered to object within maximumUiTimeout() milliseconds. If it does not, the errorString() will be set accordingly.

bool QtUiTest::mouseClick ( QObject * object, QByteArray const & signal, QPoint const & pos, Qt::MouseButtons buttons = Qt::LeftButton, InputOption options = NoOptions )

This is an overloaded member function, provided for convenience.

Simulate a mouse click event. Returns true if the event causes object to emit signal within maximumUiTimeout() milliseconds. If it does not, the errorString() will be set accordingly.

bool QtUiTest::mousePreferred ()

Returns true if widget interaction should prefer mouse events over key events.

For example, when Qt Extended is used on a touchscreen-only device, this function will return true.

void QtUiTest::mousePress ( QPoint const & pos, Qt::MouseButtons buttons = Qt::LeftButton, InputOption options = NoOptions )

Simulate a mouse press event at the co-ordinates given by pos, for the specified buttons. options are applied to the simulated event.

For Qt Extended, pos is interpreted as global screen co-ordinates. For all other platforms, pos is interpreted as local co-ordinates for the currently active window in this application.

void QtUiTest::mouseRelease ( QPoint const & pos, Qt::MouseButtons buttons = Qt::LeftButton, InputOption options = NoOptions )

Simulate a mouse release event at the global co-ordinates given by pos, for the specified buttons. options are applied to the simulated event.

For Qt Extended, pos is interpreted as global screen co-ordinates. For all other platforms, pos is interpreted as local co-ordinates for the currently active window in this application.

T qtuitest_cast ( const QObject * object )

Casts object to the specified Qt Extended test widget interface T.

If object already implements T, it is simply casted and returned. Otherwise, QtUiTest will attempt to find or create a test widget to wrap object, using all loaded QtUiTest::WidgetFactory plugins. If a test widget cannot be created to wrap object, 0 is returned.

In either case, the returned value must not be deleted by the caller.

Example:

    // Attempt to select the item "Foo" from the given widget
    bool selectFoo(QWidget *widget) {
        QtUiTest::SelectWidget* sw
            = qtuitest_cast<QtUiTest::SelectWidget*>(widget);
        if (!sw || !sw->canSelect("Foo")) {
            return false;
        }
        return sw->select("Foo");
    }

void QtUiTest::setErrorString ( QString const & error )

Sets the human-readable error string describing the last error which occurred while accessing a testwidget.

See also errorString().

void QtUiTest::setInputOption ( InputOption option, bool on = true )

Set or clear the specified option for subsequent simulated input events. The option is set if on is true, otherwise it is cleared.

bool QtUiTest::testInputOption ( InputOption option )

Returns true if option is currently set.

void QtUiTest::wait ( int ms )

Causes the process to wait for ms milliseconds. While waiting, events will be processed.

bool QtUiTest::waitForEvent ( QObject * object, QList<QEvent::Type> const & types, int ms = QtUiTest::maximumUiTimeout(), Qt::ConnectionType connectionType = Qt::QueuedConnection )

Causes the process to wait for ms milliseconds or until an event of any of the given types is received by object, whichever comes first.

While waiting, events will be processed.

Returns true if the event was received by object before timing out. When false is returned, errorString() is set accordingly.

If connectionType specifies a direct connection, this function will return immediately before the event is processed by object. If connectionType specifies a queued connection, this function will return once the event loop has run following the processing of the event.

bool QtUiTest::waitForEvent ( QObject * object, QEvent::Type type, int ms = QtUiTest::maximumUiTimeout(), Qt::ConnectionType connectionType = Qt::QueuedConnection )

This is an overloaded member function, provided for convenience.

Waits for an event of the given type.

bool QtUiTest::waitForSignal ( QObject * object, const char * signal, int ms = QtUiTest::maximumUiTimeout(), Qt::ConnectionType connectionType = Qt::QueuedConnection )

Causes the process to wait for ms milliseconds or until signal is emitted from object, whichever comes first.

While waiting, events will be processed.

Returns true if signal was emitted from object before timing out. When false is returned, errorString() is set accordingly.

If connectionType specifies a direct connection, this function will return immediately when the signal occurs, possibly before some objects have received the signal. If connectionType specifies a queued connection, this function will return once the event loop has run following the emit.