XML Schema

TestDriver is driven by a single input XML Schema that defines the tasks to be performed. This XML schema is also called as driver file and is detailed in the following section.

Tests are organised as <tasks> where, each task is a set of operations to be carried out on the PC or on the Symbian device. In addition to tests, an operation may consist command-line tasks to be performed on the PC and/or the Symbian device.

Conventions used

Conventions used in the following sections are explained below:

Each box represents an XML element also called as a tag (see Figure 1), where top rectangle is the name of the tag, <task> in this case, and middle rectangle contains the attributes (represented by circled 'a') that the main tag can have, name and timeout in this case. The bottom most rectangle contains the the elements/tags that the main tag can contain, for example, <executeOnPC>, <transferToSymbian>, and so on.

Task that can be run within a main task is called a subtask.

An element/tag


An element/tag

<driver>

The generic XML structure defining tasks that are used to run tests is shown below:

TestDriver Schema.


TestDriver Schema.

The <driver> tag is the root node of the TestDriver files. This must contain a <task> tag and can contain a <driverInfo> tag within:

The following is the structure of a typical driver file:

Driver XML file


Driver XML file

<task>

The <task> tag is a logically grouped set of operations to be executed by the TestDriver. It is a container for all other tasks and is indentified by a unique name. A task has the following attributes:

  • timeout: Used to specify the timeout duration in seconds. When the timeout is less than or equal to 0 seconds, it is considered as no timeout.

    Note: While describing asynchronous tasks, set the value of timeout to greater than 0.

  • preRebootDevice: Used to specify (True/False) whether to restart the device before executing the task. If set to true, the device is restarted before executing the task. For more details on restarting the target device, refer to Restarting the device.

Any operation including a non-test related operation, can be run using the following tasks, placed within the <task> tag. A task can be one of the following:

  1. task: A container of other tasks.

  2. executeOnPC: A task to be performed on the PC.

  3. executeOnSymbian: A task to be performed on a Symbian device.

  4. transferToSymbian: A task of transferring files to a Symbian device.

  5. retrieveFromSymbian: A task of transferring files from a Symbian device

  6. flashrom: A task of reflashing the device with a ROM image, which is located on the PC in the absolute location specified using the PCPath attribute. For more details on reflashing the target device, refer to Reflashing the device.

    For details on PCPath, refer to transferToSymbian task.

The diagram shows the operations that can be performed under a task.

Operations in a task


Operations in a task

To simplify the process of running the common tasks, such as executing a test or build Symbian code, subtasks are made available to these tasks which combine any of the four tasks into a single tag. The details of the subtask tags and their attributes are discussed in the respective sections.

Operations are categorised based on the phase of the TestDriver in which these operations are executed:

TestDriver uses two main commands 'testdriver build' and 'testdriver run' to buld and run tests respectively. These commands walks through the XML tree (link would be provided), starting from the tag specified using the -s switch. For more details, see Building tests.

  • Running the 'testdriver build' command (see command reference for more details) involves the following operations:

    1. executing all operations within <executeOnPC>

    2. creating the repositories/SIS files for the <transferToSymbian> operation.

  • Running the 'testdriver run' command (see command reference for more details) involves the following operations:

    1. executing all operations in <executeOnSymbian>

    2. transfering the created repositories/SIS files in the build phase to the Symbian device (hardware or emulator) for the <transferToSymbian> operation and any other operations.

    3. retrieving files from the Symbian device in the <retrieveFromSymbain> operation.

Note: All operations in a task are executed in the order they appear in the XML file.

Tasks can be run in two modes:

  • synchronous mode, where the TestDriver launches tasks and wait for them to terminate or till time out

  • asynchronous mode, where the TestDriver launches tasks without waiting for them to terminate.

When all operations in a task are completed, the TestDriver waits for subtasks to finish or kill them if they have timed out before doing the clean-up.

Additional tasks

<driverInfo>

Each driver file contains <driverInfo> tag that has additional user information which would be printed in the report. For example, description, testcase and so on. This is not directly used by the TestDriver. It works as an annotation tool for the .driver files.

Driver information


Driver information

Example for <driverInfo>

The following is an example XML file using the <driverInfo> tag:

<reportInfo>
    <info key="use case">Testing TestDriver</info>
    <info key="discription">This is an annotation for TestDriver files</info>
    <info key="random key">some value</info>
</reportInfo>

<reference>

This subtask allows you to refer to another task in the current or another XML file. This acts like an import statement, where you need to specify the fully qualified URI using the attribute URI. The URI accepts the following variables: ${epocroot}, ${sourceroot}, ${xmlroot}, ${platform} and ${build} and does not allow wildcards. Currently the TestDriver supports file protocol.

Refering to another task


Refering to another task

Example for <reference>

The following is an example XML file using the <referenece> task is:

<reference URI="file:/h:/epoc32/testdriver/systemtest/systemtest.driver#systemtest.pt_coretests" />

This task refers to the file systemtest.pt_coretests that is in the location h:/epoc32/testdriver/systemtest/systemtest.driver.

<transfers>

This task allows you to transfer a file from the PC to the Symbian device. When used within the transferToSymbian tag, wildcards and variables are allowed. When used within the retrieveFromSymbian tag, wildcards and variables are not allowed.