QtopiaSystemTest Namespace Reference
[QtUiTestModule]

Detailed Description

The QtopiaSystemTest namespace provides script based system test functionality for Qt Extended.

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.

All system tests which make use of the QtopiaSystemTest namespace also have access to the QSystemTest namespace.

Type Documentation

enum QtopiaSystemTest::MemoryType
flags QtopiaSystemTest::MemoryTypes

This enum specifies which type of memory to measure when using the memory related performance functions.

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

enum QtopiaSystemTest::SampledMemoryInfoFlag
flags QtopiaSystemTest::SampledMemoryInfoFlags

This enum specifies which data to retrieve from the recorded memory usage information when using the getSampledMemoryInfo() function.

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

enum QtopiaSystemTest::VersionType

This enum specifies which version is returned by getVersion().

Function Documentation

void QtopiaSystemTest::backgroundAndGotoHome ()

Background all currently running applications and return to the Home screen.

See also Application Management.

String QtopiaSystemTest::callAccept ()

Returns an alias that will be resolved by Qt Extended to activate the callAccept function, either by simulating a Call-Accept keyclick or by selecting a Call Accept somehow on a touchscreen. Example:

    select(callAccept()); // presses the CallAccept button

The test will fail if no Call Accept can be simulated.

See also optionsMenu(), softMenu(), and callHangup().

String QtopiaSystemTest::callHangup ()

Returns an alias that will be resolved by Qt Extended to activate the callHangup function, either by simulating a Call-Hangup keyclick or by selecting a Call Hangup somehow on a touchscreen. Example:

    select(callHangup()); // presses the CallHangup button

The test will fail if no Call Hangup can be simulated.

See also optionsMenu(), softMenu(), and callAccept().

String QtopiaSystemTest::documentsPath ()

Returns the path of the documents directory on the test system.

Example:

    // Put a test image into the image directory in documents on the test system.
    putFile( baseDataPath() + "tiger.jpg", documentsPath() + "image/tiger.jpg");

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

Number QtopiaSystemTest::getMemoryInfo ( MemoryTypes type )

Measure and return the current memory usage, in kilobytes, on the test system for memory of the given type.

If type is a flag containing multiple types, the memory usage of the desired types will be added together.

Example:

    // Get the amount of effectively free memory on the system.
    function freeMemory() {
        return getMemoryInfo(FreeMemory|BuffersMemory|CacheMemory);
    }

It is not necessary to call startSamplingMemory() before using this function.

See also startSamplingMemory(), stopSamplingMemory(), and getSampledMemoryInfo().

QVariant QtopiaSystemTest::getSampledMemoryInfo ( MemoryTypes types, SampledMemoryInfoFlags flags )

Get information about sampled memory for the specified memory types, using the given flags to decide what data to return.

Use startSamplingMemory(), stopSamplingMemory() and this function to measure the effective memory usage of particular use cases of Qt Extended.

For example:

    spin_the_yoyo: function() {
        var total_memory = getMemoryInfo(TotalMemory);

        // Ensure we start measuring from the home screen
        gotoHome();
        startSamplingMemory(500);

        // Spin the yoyo
        startApplication("yoyo-manager");
        select("Spin");
        waitForTitle("Spin complete");

        // Measure the memory used to spin the yoyo
        stopSamplingMemory();
        var min_free = getSampledMemoryInfo(EffectiveFreeMemory, SampleMinimum);
        var min_free_line = getSampledMemoryInfo(EffectiveFreeMemory, SampleMinimum|SampleLine);
        print("Max used memory: " + (total_memory - min_free) + " Kb, at line " + min_free_line);
    }

String QtopiaSystemTest::getVersion ( VersionType type = QtExtendedVersion )

Returns the version number specified by type.

Example:

    print( "Qt Extended Version: " + getVersion(QtExtendedVersion) );
    print( "Qt Version:          " + getVersion(QtVersion) );
    print( "Linux Version:       " + getVersion(KernelVersion) );

void QtopiaSystemTest::gotoHome ()

Close all currently running applications and return to the Home screen.

See also Application Management.

void QtopiaSystemTest::ipcSend ( String channel, String message, 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 )

Send an IPC message on a Qt Extended IPC channel. The optional arguments arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8 and arg9 are arguments to the IPC message.

Example:

    // Put a new document on the system and force a document rescan
    putFile("testdata/mydoc.txt", "$HOME/Documents/mydoc.txt");
    ipcSend("QPE/DocAPI", "scanPath(QString,int)", "all", 1);

String QtopiaSystemTest::launcherMenu ()

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

    select( "Contacts", launcherMenu() );

See also softMenu(), callAccept(), and callHangup().

String QtopiaSystemTest::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 softMenu(), callAccept(), and callHangup().

void QtopiaSystemTest::reboot ()

Reboot the device running Qt Extended.

This method instructs QPE to reboot the device in the same way as the "Reboot" option in the shutdown dialog. Whether or not this method succeeds depends on how QPE was launched and the permissions of the user account under which it is running.

Example:

    // Start performance testing, and reboot Qt Extended to get the cold startup time of Qt Extended setSetting("$HOME/Settings/Trolltech/StartupFlags.conf", "PerfTest", "State", 1);
    reboot();

See also restartQtopia() and Application Management.

void QtopiaSystemTest::restartQtopia ()

Restart Qtopia.

This method instructs QPE to restart in the same way as the "Restart" option in the shutdown dialog. This is actually implemented by simply closing QPE and relying on the script which started it to restart it. Hence whether or not this method succeeds depends on how QPE was launched.

Example:

    // Restore Greenphone to factory defaults for the next test
    setSetting("$HOME/Settings/Trolltech/StartupFlags.conf", "RestoreDefaults", "State", 1);
    restartQtopia();
    // Put back the setting so we don't restore to factory defaults after next restart
    setSetting("$HOME/Settings/Trolltech/StartupFlags.conf", "RestoreDefaults", "State", 0);

See also reboot() and Application Management.

Boolean QtopiaSystemTest::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 QtopiaSystemTest::shutdownQtopia ()

Shut down Qtopia.

String QtopiaSystemTest::softMenu ()

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

    select( "Help", softMenu() ); // select the item with text 'Help' from the soft menu
    print( signature(softMenu()) ); // to print the name of the resolved widget.

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

The test will fail if no visible soft menu is found, or if multiple soft menus are found.

See also callAccept() and callHangup().

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

Start the specified application.

application can be the name of a binary to execute on the test system (e.g. 'addressbook') or the full name of an application as shown in the launcher grid (e.g. 'Contacts'). The application must connect to the test framework within timeout ms or the test fails.

flags specifies additional behaviour.

The application will be launched by sending a Qt Extended IPC message. To simulate launching an application by key clicks, use select( <appname>, launcherMenu() ).

Example:

    // Start several apps and keep them in the background
    startApplication("Notes", 1000, BackgroundCurrentApplication);
    startApplication("Contacts", 1000, BackgroundCurrentApplication);
    startApplication("todolist", 1000, BackgroundCurrentApplication);

    // Now start btsettings without Background, which means all current apps
    // will be exited.
    startApplication("btsettings");

See also Application Management.

void QtopiaSystemTest::startSamplingMemory ( Number interval = 500 )

Start sampling memory at fixed intervals.

Every interval milliseconds, the current memory usage will be sampled and stored. Once sampling has finished, the data can be retrieved using getSampledMemoryInfo().

Each memory sample causes network traffic between the system test and Qt Extended. Therefore, using an extremely small interval will have a negative impact on performance.

See also stopSamplingMemory(), getMemoryInfo(), and getSampledMemoryInfo().

void QtopiaSystemTest::stopSamplingMemory ()

Stop sampling memory.

See also startSamplingMemory(), getMemoryInfo(), and getSampledMemoryInfo().

QtopiaSystemTestModem QtopiaSystemTest::testModem ()

Get the QtopiaSystemTestModem currently used as the modem device.

If Qt Extended is not currently connected to a QtopiaSystemTestModem, Qt Extended will be restarted and forced to connect to a new QtopiaSystemTestModem, which will be returned.

The returned QtopiaSystemTestModem may be explicitly deleted if desired. Otherwise, it will be destroyed when the system test completes. In either case, when the QtopiaSystemTestModem is destroyed, Qt Extended will be restarted and will no longer connect to the simulated modem.

Example:

    // Change operator name from within a system test
    QVERIFY( testModem() );
    testModem()->setVariable("OP", "Qt Extended Comms");
    testModem()->send("+CREG: 5");

See also restartQtopia() and Telephony Simulation.

void QtopiaSystemTest::waitForCurrentApplication ( String application, Number timeout = 10000 )

Returns true if the specified application gains focus within timeout milliseconds.

void QtopiaSystemTest::waitForQtopiaStart ( Number timeout = 60000 )

Waits up to timeout milliseconds for Qt Extended to become fully initialized. On the desktop, the first call to this function will start Qt Extended using the runqtopia script.

Once initialized:

• the Date format will be set to 'D/M/Y'.
• the Time format will be set to 24 hour.