C H A P T E R 11 |
Developing an Over-the-Air Test Package |
This chapter describes how to create an over-the-air (OTA) provisioning test package. It contains the following sections:
Test pack development is an iterative, non-linear process that varies according to local practices and preferences. As you read the following sections, remember that when developing tests you might perform some steps many times, and you might perform the steps in a different sequence than they are described in this chapter. You might also choose to build and test your developing test pack more frequently than this chapter suggests. If you use a source code control system, you might have to modify some instructions, such as “make the file writable.”
OTA test pack development is quite different from runtime or benchmark test pack development. OTA test source files are essentially empty except for Javadoc tool class and case documentation and other markup (see Chapter 4). The Java Device Test Suite provides all OTA test code, which is driven by properties you specify. The test code does not run on a test device. It runs on the Relay.
In OTA tests, the Relay acts as a provisioning server. It performs these services:
Each test has at least one associated MIDlet that the user downloads to the test device. You write these test MIDlets.
Program logic is different in OTA tests compared to other test types (where the test logic runs predominately within the test device). In OTA tests, the program logic is an interplay between the following.
1. The test MIDlet, installed successfully (or not) onto the test device, and executed in the device.
2. The installation procedure. The tester reads test instructions and interacts with the test device and the MIDlet.
3. The AMS, a part of the test device that manages the installation and launching of the MIDlet. For example, the AMS sends an installation status report to the relay after MIDlet installation.
To develop an OTA test pack, you must also know how to modify Ant build scripts.
An OTA test has two sets of files:
See the property MIDletSourcesDir in the file devKitHome/ota/testsuite.info for an example of good paths to MIDlet source files. It is important to structure the paths to avoid namespace conflicts, and this is reflected in the directory structure of the OTA examples.
You can create the file sets in any order. This section describes how to write the files in a test package. Writing Application Files describes how to write application files.
An OTA test source file is only a container for online test documentation and properties. It has no executable statements. The OTA servlet and, for some tests, the associated test MIDlet, do the work of the test. For a sample interactive test, see devKitHome/tests/ota/src/client/com/sun/samples/interactive/Interactive.java. Interactive and semi-automated test source files have the same format.
Tests that use protected APIs must be granted permission to call methods in those interfaces. This is done by digital certificates in the test device which are associated with protection domains.
OTA test developers must specify the protection domain for the users of applications that use protected APIs. The available domains are specified in the MIDP specification.
Use the following syntax in a source file comment (see Test Class and Case Comment Blocks) to make a domain available to testers:
* @card.property SecurityDomain=DomainID
The SecurityDomain property value is the domain name (DomainID).
The DomainID is one of four OTA pre-defined domains or a custom domain (described later in this section):
* @card.property SecurityDomain=ThirdPartyTrusted
The preceding example means the OTA MIDlet packs associated with this test case are signed with a key setup user interface (using the Manage Keystores command and corresponding Configuration Editor pane) for the specified protection domain, so that the MIDlet suite are associated with this protection domain in the device where the MIDlet is installed.
In addition to the pre-defined domains previously mentioned, you can create custom domains. Custom domains map to specific certificates in their respective keystores. Custom domains as well as the default domains must be made apparent to the tester. The tester enters the domains in the harness Configuration Editor in the left pane under Over The Air Test MIDlets. Custom domain names have the following restrictions:
For more information about protection domains, certificates, and keystores, see the Java Device Test Suite Test Notes and the administrator harness online help.
Every OTA test case has an associated application (MIDlet, technically a MIDlet suite). The test case’s evaluation file typically instructs the user to download the associated MIDlet to the test device.
FIGURE 11-1 shows, on the left, a directory containing one test class that has two test cases. On the right, the figure shows the application files you must create for this example in which both test cases use the same application (MIDlet.java).
FIGURE 11-1 Test and Application File Correspondence
An application source file is a MIDlet, as defined by the MIDP 1.0 and 2.0 specifications. For an example used with an interactive OTA test, see devKitHome/tests/ota/src/apps/samples/interactive/PropExample.java. Multiple tests can use the same application if their source file comments name the shared application’s JAD file and JAR file (which are created by the build script). If a test requires its associated application to perform an operation on the test device, make sure that the application displays information that tells the user to click Passed or Failed in the evaluation window, and that the evaluation window instructs the user to launch the application.
In the same directory as the application, create a build.xml file. This file is application specific. See the samples in the subdirectories of devKitHome/tests/ota/src/apps/samples/ for examples. By default, all MIDlet JAD and JAR files are created in the directory specified by TestMIDletDir. You can have a MIDlet’s JAD file and JAR file created in a subdirectory by specifying a value for subDir in the following build.xml line:
<mkdir dir=”${MIDlet.dest.dir}/subDir”/>
Correspondingly, add subDir to all build.xml lines that contain MIDlet.dest.dir.
The @card.property tags in the source file must name the same directory. Here is a hypothetical example line from a build.xml file:
<mkdir dir=”${MIDlet.dest.dir}/mySubDir”/>
The corresponding source file lines are as follows:
* @card.property=JADPath1=mySubDir/TestMIDletJADFile.jad * @card.property=JARPath1=mySubDir/TestMIDletJARFile.jar
In the same directory as the application, create a manifest file named manifest. The MIDP 1.0 and MIDP 2.0 specifications define the manifest file format and contents. See devKitHome/tests/ota/src/apps/samples/interactive/color/manifest for an example.
For MIDlets that use protected APIs, code the permission requests in the MIDlet JAD file and JAR file manifest. To see how these files are built, inspect devKitHome/tests/ota/src/apps/samples/signed/build.xml.
An application can send timestamped log messages by HTTP. In the test results, these messages are identical to those that runtime tests can create as described in Logging. To generate a log message, add the following line to the application’s JAD file:
logurl: ${URL_SIMPLE_LOG_RECEIVER}
CODE EXAMPLE 11-1 shows how to send a log message to the Relay. The class JdtsLogLevel defines the available log level constants, such as TRACE and DEBUG.
The example in devKitHome/tests/ota/src/client/com/sun/samples/interactive/Interactive.java has test cases that illustrate several optional features of the interactive OTA test infrastructure:
ing HTML relocated fro