| Java Device Test Suite Developer’s Guide |    
|
| C H A P T E R 6 |
|
Writing the testsuite.info File |
The testsuite.info file at the top of the test pack directory is a properties file. It contains a list of properties and values. The harness uses some of these properties. You can define additional properties that your tests require to run as desired. Obtaining a Property Value describes how to retrieve a property value in a test. For each property, you can define its value, its visibility to the harness users, and, if it is visible, assign attributes to the property value, and determine where the property appears in the harness.
You can create testsuite.info with any text editor. A testsuite.info file can contain any UTF-8 character.
The testsuite.info file consists of two kinds of lines:
TestPackName=Sample Runtime Tests
# Required entries
For advanced developers, a more detailed description of the testsuite.info file syntax can be found at http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html.
Specify lines in any order. However, you must observe testsuite.info syntax and semantic requirements exactly. No error messages inform you of mistakes. If you make an error, a test, the tester edition harness, or the administrator edition harness exhibits unexpected behavior.
To see example testsuite.info files, refer to the sample test packs in devKitHome/tests/.
An entry like MyPort=8086 specifies that 8086 is the default value for MyPort. Specify a default value that is highly likely to work at your site or sites where a test pack installation will take place. An administrator or user can override the value you specify (subject to the property’s scope as described in Scope) but your goal is to provide defaults that do not normally require an override.
A property’s scope defines its visibility to administrators and testers through the harness. A property can have the following scopes:
A property has an implicit default scope. The property default scope is visible and its value is editable in the Java Device Test Suite Configuration Editor. You do not need to specify the scope to apply the default. Use the default scope for properties that a tester will more commonly access.
| Note - Do not define a hidden property without a default value. |
| Note - Do not give a property more than one scope or define a property more than once. |
The entries in CODE EXAMPLE 6-1 show how to specify property scopes.
# default scope implied MyInOutPort=8088 # advanced scope MyOutPort=8087 MyOutPort.scope=advanced # hidden scope MyInPort=8086 MyInPort.scope=hidden |
To define a property that is visible to users but not editable, code it as shown in CODE EXAMPLE 6-2.
# DeployMode value is visible, but not editable DeployMode=HTTP DeployMode.readonly=true |
The harness can validate a property value set by a tester against attributes you define for the property. The attributes are listed in order of priority in case there is a conflict, such as a type of boolean and max of 6. Conflicting lower-priority attributes (in this example, max) are ignored.
The entries in CODE EXAMPLE 6-3 show how to specify property attributes.
The default or advanced scope property’s category determines where the harness accesses and displays a property in the harness’s Configuration Editor. The Configuration Editor’s left pane lists test packs (bold font entries). Each test pack contains a list of categories. Testers choose a category and the properties assigned to the category display in the center pane. Default scope properties appear at the top of the pane. Advanced scope properties follow.
All test packs have a default category named General. Properties not explicitly assigned to a category are assigned to General.
FIGURE 6-1 shows the Configuration Editor with a selected category in the left pane and its assigned default and advanced properties in the center pane.
FIGURE 6-1 Configuration Editor
For more information about the Configuration Editor, see the Java Device Test Suite online help.
CODE EXAMPLE 6-4 shows how to specify categories for default scope properties. You can specify a text description for a category. If the category name includes a space character, you must escape it with a back slash “\” as the example shows. If you do not provide a text description, the category name is used. For example, FIGURE 6-1 has “Bluetooth General” for both the category name (blue band) and the category description below it.
CODE EXAMPLE 6-5 shows how to specify categories for advanced scope properties.
There is no point to assigning a category to a property whose scope is hidden.
You can supply a short description for a property that appears in the harness Configuration Editor's More Info (right) pane next to the Description title (as shown in FIGURE 6-1). To add the short description, follow the property definition with a .doc line attribute, for example:
MyPort=8086 MyPort.doc=Specify an IP port that the test server can use.
Supply a .doc attribute entry for every property whose scope is not hidden.
Many property values are path names. The path name separator is the slash (/) character.
The reserved word ${TS_DIR} can be used in path names (and must not be used for anything else).
In a property you define, ${TS_DIR} refers to the root of the test pack’s directories in the Relay file system. If your test pack includes tests that have client and server parts, you can use ${TS_DIR} to give server parts access to test pack files that the test pack installer copies to the Relay file system. For example, suppose a server part needs a sample media file that you have created in packWorkDir/test_data/samples/.
1. Set the predefined TestServerResources property to test_data/.
The test pack installer copies the directories named in TestServerResources to the Relay file system.
2. Define another property, for example, SamplesForServer, and set it to ${TS_DIR}/test_data/samples/.
3. Write the client part to retrieve SamplesForServer and pass its value to the server when it (the client) calls Runner.launchServer().
When the client (running on the test device) asks for the value of SamplesForServer, (see Obtaining a Property Value) it receives the absolute path to test_data/ in the Relay file system.
4. Write the server part to use the value passed to it to find the samples/ directory.
Writing Network Tests describes the details of client and server interaction.
A testsuite.info file must include predefined properties that the harness uses to load and display the test pack components. The following properties are required:
The preceding properties must have a scope of hidden (see Scope).
Benchmark and OTA test packs require additional properties in testsuite.info. For information about these additional properties, see the sample files.
A testsuite.info file might include other predefined properties that the harness uses to load and display the test pack components. The following properties are optional:
The root represents a directory several levels above the server-side Java source files. The directory containing source files is determined by the path implicit in the namespace of the package. For example, in the Developer’s Kit runtime examples, the tests/runtime/testsuite.info file defines TestServerSourcesDir to include the root src/server. The actual server-side Java source (for example, the file GenericRequestThread.java) is found in the directory
tests/runtime/src/server2/com/sun/samples/network/server/http/
The file GenericRequestThread.java includes the line
package com.sun.samples.network.server.http;
which shows how the namespace maps to the location of this source file in the file system.
You can specify the test pack version in this property or in the file testpack.version.properties, which is described in Test Pack Versioning Alternative.
| Note - Do not use both versioning mechanisms. TestSuiteVersion in testsuite.info overrides testpack.version.properties. |
While you are developing or modifying a test pack, you must prefix the version number with the characters ++, for example:
TestSuiteVersion=++1.4
These characters ensure that when you launch the harness, it synchronizes templates with the latest changes you have made in the test pack, for example, new properties. When you have finished development, remove the ++ characters, increment the TestSuiteVersion value by an amount of your choosing, and run ant pack to create the installable test pack.
TSPermissions=javax.microedition.io.Connector.http ,javax.microedition.io.Connector.sms,javax.microedition.apdu.sat,javax.microedition.payment.process
If you specify TSPermissions, you must include the permission javax.microedition.io.Connector.http in the list. The MicroAgent in each bundle uses the HTTP API to communicate with the Relay. If you do not specify TSPermissions, the harness automatically requests javax.microedition.io.Connector.http.
If you specify TSPermissions, hide it from administrators and testers with this line:
TSPermissions.scope=hidden
The harness uses the TSPermissions property to reduce the number of permission requests it includes in test bundles. The requested permissions in a bundle are the intersection of the permissions selected in the configuration’s Security Permissions questions and the value of the TSPermissions property in the test pack whose tests are in the bundle. In other words, the harness uses TSPermissions properties to filter out irrelevant user-selected permissions.