Telephone Accessories User Manual

Manuals Brands Sun Microsystems Manuals Telephone Accessories 1.2

Java

™

ME TCK Framework

Developers Guide

Version 1.2

July 2007

Sun Microsystems, Inc.

www.sun.com

Summary of content (130 pages)

PAGE 1

Java™ ME TCK Framework Developers Guide Version 1.2 Sun Microsystems, Inc. www.sun.
PAGE 2

Copyright 2007 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Test suite developer’s guide for the Java ME TCK Framework. THIS PRODUCT CONTAINS CONFIDENTIAL INFORMATION AND TRADE SECRETS OF SUN MICROSYSTEMS, INC. USE, DISCLOSURE OR REPRODUCTION IS PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SUN MICROSYSTEMS, INC. U.S. Government Rights—Commercial software. Government users are subject to the Sun Microsystems, Inc.
PAGE 3

Contents Preface 1. xv Introduction Getting Started 1 1 Development Environment Use of the Framework 3 3 Target Environment 3 Connectivity Requirements Resource Limitations Framework Bundle 4 5 6 Framework Components 6 Framework Components on the Harness Side Framework Components on the Device Side Test Types 7 8 Automated Tests 9 Distributed Tests 10 Interactive Tests OTA Tests 2.
PAGE 4

Writing an Automated Test ▼ 15 To Create a Simple Automated Test Building an Updated Simple Test Suite ▼ ▼ 3. 19 To Build an Updated Test Suite Testing an Updated Simple Test Suite To Test an Updated Test Suite Test Suite Construction Test Suite Structure 19 20 20 23 23 testsuite.
PAGE 5

remote Attribute 44 remoteSource Attribute executeArgs Attribute Distributed Test Execution 45 45 46 Testing User Interfaces With Interactive Tests Client Test Component 48 49 Remote Test Component 49 Test Description for Interactive Tests 49 Required Interactive Test Keywords Interactive Test Execution 50 50 Example of an Interactive Test 52 Testing Application Provisioning With OTA Tests Server Component of an OTA Test 53 Client Test Component of an OTA Test Test Description for OTA Tes
PAGE 6

Marking Trusted Tests 62 Using an Attribute to Mark Double-Duty Tests Granting or Denying Security Permissions Granting Security Permissions 64 Denying Security Permissions 66 Adding Resource Files in Tests Enabling Test Selection 70 selectIf Test Selection A.
PAGE 7

CommServers Messaging 85 85 Test Export Support Libraries CDC Agents src Directory 85 85 86 Framework Server Classes and Interfaces Agent Classes 87 Digital Signer 87 Preverification Script 86 87 Java ME Technology Version of Harness Classes 87 Basic Interview Classes Containing General Questions Communication Channel doc Directory C.
PAGE 8

viii Java ME TCK Framework Developer’s Guide • July 2007
PAGE 9

Figures FIGURE 1-1 Framework Configuration for Standard Automated Tests FIGURE 1-2 Framework Configuration for Distributed Tests 11 FIGURE 1-3 Framework Configuration for Interactive Tests 13 FIGURE 1-4 Framework Configuration for OTA Tests FIGURE 4-1 Automated Test Execution 42 FIGURE 4-2 Distributed Test Execution 47 FIGURE 4-3 Interactive Test Execution 51 FIGURE 4-4 OTA Test Execution 10 14 58 ix
PAGE 10

x Java ME TCK Framework Developer’s Guide • July 2007
PAGE 11

Tables TABLE 1-1 Configurations and Supported Test Types TABLE C-1 Framework Test Description Fields TABLE C-2 Framework Keywords 8 92 94 xi
PAGE 12

xii Java ME TCK Framework Developer’s Guide • July 2007
PAGE 13

Code Examples CODE EXAMPLE 3-1 Simple Test Suite testsuite.
PAGE 14

CODE EXAMPLE 4-19 Test Description That Grants Permissions for a Security Test CODE EXAMPLE 4-20 deny Attribute in the Test Description CODE EXAMPLE 4-21 Test Description That Denies Permissions for a Security Test CODE EXAMPLE 4-22 Test That Requires an Image Resource CODE EXAMPLE 4-23 resources Attribute in the Test Description CODE EXAMPLE 4-24 Test Description That Includes Resources CODE EXAMPLE A-1 run Method CODE EXAMPLE A-2 Definition of main 78 CODE EXAMPLE A-3 Test Case Method xi
PAGE 15

Preface This guide describes how to use resources from the Java™ Platform, Micro Edition Technology Configuration Kit Framework (Framework) to develop and configure test suites and tests for Java Platform, Micro Edition (Java ME platform) technologies.
PAGE 16

■ JavaTest Harness User’s Guide: Graphical User Interface This guide provides a description of using the harness Graphical-User Interface (GUI). This guide is available from the Java ME Technology APIs and Docs web site at http://java.sun.com/javame/reference/apis.jsp. ■ JavaTest Harness User’s Guide: Command-Line Interface This guide provides a description of using the harness command-line interface. This guide is available from the Java ME Technology APIs and Docs web site at http://java.sun.
PAGE 17

Platform Commands This document does not contain information about basic platform commands and procedures such as shutting down the system, booting the system, and configuring devices. Refer to the following for this information: ■ Software documentation that you received with your system ■ Solaris™ Operating System documentation at http://docs.sun.
PAGE 18

Typographic Conventions This guide uses the following typographic conventions: Typeface* Meaning Examples AaBbCc123 The names of commands, files, and directories; on-screen computer output Edit your .login file. Use ls -a to list all files. % You have mail. AaBbCc123 What you type, when contrasted with on-screen computer output % su Password: AaBbCc123 Book titles, new words or terms, words to be emphasized. Replace command-line variables with real names or values.
PAGE 19

Accessing Sun Documentation Online The Java Developer Connection™ program web site enables you to access Java platform technical documentation at http://java.sun.com/. Sun Welcomes Your Comments We are interested in improving our documentation and welcome your comments and suggestions. Provide feedback to Sun at http://java.sun.com/docs/forms/sendusmail.
PAGE 20

xx Java ME TCK Framework Developer’s Guide • July 2007
PAGE 21

CHAPTER 1 Introduction This chapter introduces using the Framework resources to develop test suites for the Java ME platform, including descriptions of the kinds of tests that a test suite can include.
PAGE 22

Note – The TCK Project Planning Guide and the Java Technology Test Suite Development Guide documents were originally developed as part of a product used by the Java Community Process (JCP) Specification Leads. For that reason, these documents refer to JCP procedures that might not apply to a test developer’s Framework project.
PAGE 23

Development Environment The following tools and resources are the minimum software requirements for the Framework development environment: ■ JDK, version 5.0 or later ■ JavaTest harness, version 3.2.2 or later For TCK development, download the latest Java Compatibility Test Tools (Java CTT) from the Java Community Process (JCP) program web site.
PAGE 24

Configuration (CDC) and a profile such as Mobile Information Device Profile (MIDP), Foundation Profile (FP), Personal Basis Profile (PBP), or Personal Profile (PP). ■ Configuration - CLDC and CDC are configurations that provides a basic set of libraries and virtual-machine features that must be present in an implementation of a Java ME environment.
PAGE 25

Resource Limitations Hardware resources on test devices are often limited. Resource constrained devices can quit operation when excess native resources are requested. The Framework can run tests on resource constrained target devices with limited available memory and persistent storage.
PAGE 26

Framework Bundle The Framework resources are packaged and provided to users as a zip bundle. When the bundle is unzipped the following directories and files are placed in the Framework root directory: ■ doc - Contains the Java ME TCK Framework Developer’s Guide (PDF and HTML formats). ■ redistributables - Contains the following directories: ■ ■ javame_tck_framework_12/src - Contains the source files.
PAGE 27

Framework Components on the Harness Side The following components are used for running CLDC, MIDP, and CDC tests in the Distributed, OTA, and Automated test configurations with the harness: ■ Execution server - Used in CLDC and MIDP Distributed and Automated test configurations. The execution server contains no internal test-related logic. Its only function is to forward data. It is as lightweight as possible.
PAGE 28

An agent is a separate program that works in conjunction with the harness to run tests on the device. In CDC, the agent is started once, and when started, in a loop, it uses the communication channel to the harness to download the test classes and to execute them on the device, and then reports back the results.
PAGE 29

Automated Tests Automated tests for CLDC, MIDP, and CDC configurations execute on the test device without requiring user interaction. Automated tests can be queued up and run by the test harness and their results recorded without the user being present. The configuration for standard automated test execution is the most common and the most simple of the tests that are run on the device. Automated tests are also the most convenient and the fastest tests for a user to run, since they are fully automated.
PAGE 30

FIGURE 1-1 Framework Configuration for Standard Automated Tests PC or Workstation Device JavaTest Harness 1 getNextApp 2 Application Bundle AMS (agent + tests) 3 getNextTest Execution Server 4 Test Name Agent 5 sendTestResult Tests Diagram of a standard automated test configuration. Distributed Tests Distributed tests are a special type of automated tests.
PAGE 31

Distributed tests are typically slower (due to extra communication between remote components) and more complex than simple automated tests and should be used only when it’s not possible to write simple automated tests. FIGURE 1-2 illustrates the Framework configuration for running CLDC and MIDP distributed tests. Distributed tests are currently not supported in CLDC (without MIDP).
PAGE 32

Interactive Tests Interactive tests are the tests that require some form of user interaction and cannot be executed without such interaction. From a design point of view, interactive tests are a subtype of distributed test. As a subtype of distribute test, interactive tests generally execute on the test device under the control of a component called an agent. However, unlike distributed tests, interactive tests also require some form of user interaction as a part of the test.
PAGE 33

FIGURE 1-3 Framework Configuration for Interactive Tests PC or Workstation JavaTest Harness Device 1 getNextApp Application Bundle 2 (agent + tests) Execution Server 3 getNextTest AMS 4 Test Name 11 Send Test Result Passive Agent Agent Server-Side Test Messaging Service 9 7 8 5 Check/Send Message Tests 6 Get Message Request an Action (if interactive) 10 Requested Action Diagram of the interactive test configuration.
PAGE 34

OTA tests validate API functionality while the device is connected to a remote host (the PC or workstation where the harness runs). In this configuration, one part of the OTA test runs on the remote host (the PC or workstation where the harness runs) using a passive agent and the other part of the test runs on the device. OTA tests require user interaction as a part of each test. FIGURE 1-4 illustrates the Framework configuration for running OTA tests.
PAGE 35

CHAPTER 2 Writing a Simple Automated Test Automated test execution is the most common and simple of the test configurations that are run on the test device. User interaction is not required to run automated tests. The following instructions describe how to create a simple automated test and add it to an existing Framework supplied test suite.
PAGE 36

■ Each test case method must take no arguments, and must return a Status object that represents the outcome of the test case. The Status can be either Status.passed(String) or Status.failed(String). ■ Developers must update the runTestCases() method to add the test cases that are executed. This is a CLDC-MIDP specific method (the abstract method is defined in CLDCspecific MultiTest). For CDC-specific Multitest, this method is not required because reflection is available on CDC stacks.
PAGE 37

*/ public class Test3 extends MultiTest { protected void runTestCases() { if (isSelected("helloWorld")) { addStatus(helloWorld()); } } public Status helloWorld() { String message1 = new String("Hello World !"); String message2 = new String("Hello World !"); ref.println("message1: "+message1); ref.println("message2: "+message2); if (!message2.equals(message1)) { return Status.failed("Failed: see ref for details"); } return Status.passed("OK"); } } 2.
PAGE 38

executeClass sample.pkg3.Test3 keywords runtime positive Note – The contents of this test description file correspond to the Test3.java test class. 4. Save this file in the Simple Test Suite source as SimpleTestSuite/tests/pkg3/index.html. The index.html must be contained in the same directory as its test class (in this case, Test3.java). 5.
PAGE 39

Building an Updated Simple Test Suite The following steps demonstrate how to build an updated test suite after adding a test. ▼ To Build an Updated Test Suite After completing the procedures contained in “Writing an Automated Test” on page 15, you must run the build to assemble the updated test suite. Before building the updated test suite, your development environment must meet the minimum requirements described in “Development Environment” on page 3.
PAGE 40

3. Enter the ant command to invoke the ant build script. The build creates a SimpleTestSuite-build directory containing the test suite. After creating the updated test suite, you must test it (see “Testing an Updated Simple Test Suite” on page 20) before making the test suite available to users. Testing an Updated Simple Test Suite The following steps demonstrate how to test an updated test suite.
PAGE 41

3. Use the Configuration Editor to provide configuration information required to run the updated test suite. 4. After you complete the interview, choose Run Test > Start on the Test Manager main menu to start the test suite. 5. Use the following command to start the WTK. c:\WTK_InstallDir\bin\emulator ^ -Xautotest:http://%JAVATEST_HOST%:%JAVATEST_PORT%/test/getNextApp.jad If you answered the interview questions correctly, all of the tests run successfully.
PAGE 42

22 Java ME TCK Framework Developer’s Guide • July 2007
PAGE 43

CHAPTER 3 Test Suite Construction This chapter describes the organization and construction of a Java ME technology test suite that uses Framework resources. Additional information about constructing test suites for use with the JavaTest harness can be located in Chapters 4 and 8 of the JavaTest Architect’s Guide.
PAGE 44

■ lib directory ■ tests directory ■ classes directory ■ doc directory testsuite.jtt File The testsuite.jtt file is located in the root directory of the test suite. It provides a registry of information about the test suite and defines test suite properties. The harness uses these properties to instantiate a TestSuite object that acts as a portal to all information about the test suite. Whenever the harness requires information about the test suite, it queries the TestSuite object. The testsuite.
PAGE 45

The testsuite.jtt file is located under the root directory of the Simple Test Suite. You can also find it under the build/ directory of the Simple Test Suite source. lib Directory The lib directory usually contains the javatest.jar file that provides all of the classes required to execute the harness, all of the JAR files under the lib directory of the Java ME TCK Framework, and the library classes. The test suite developer can use the library classes to simplify the creation of tests. With javatest.
PAGE 46

Organize the tests hierarchically the way you want them displayed in the test tree. The Test Manager in the harness displays the test hierarchy, enabling users to select and run specific groups of tests from the GUI. Test Class A test class or test source is a Java technology class that either implements the test interface or extends the test class. A test class can rely on inner, sub, or independent classes and contains one or more test cases.
PAGE 47

CODE EXAMPLE 3-2 Simple Test Class (Continued) return Status.passed("OK"); else return Status.failed("2 + 2 did not make 4"); } } } Additional examples (Test1.java and Test2.java)can be found in the following Simple Test Suite directories: ■ SimpleTestSuite/tests/sample/pkg1/ ■ SimpleTestSuite/tests/sample/pkg2/ Test Description file Each subdirectory that contains one or more test classes must also contain a corresponding test description. The test description is contained in HTML format.
PAGE 48

The classes directory generally contains following sub-directories: ■ classes/preverified - Contains the preverified test classes. ■ classes/shared/testClasses.lst - The test class dependency file (testClasses.lst) provides information to the Framework test bundling infrastructure regarding which classes should be bundled for each test. This information is used in CLDC and MIDP, but ignored in CDC.
PAGE 49

In the test description file, $testHost and $testPort are test environment variables and are replaced by actual values obtained from the test environment. ■ The test suite configuration interview must include a corresponding and appropriate question asking the user to specify the values of the host and port number. The configuration interview creates entries in the test environment from user answers as name-value pairs.
PAGE 50

1. Define the environment variable required by the test. In the example (Test2.java), the test case SampleStringValue() checks if the sampleValue that is passed in equals Hello. The harness requires the sampleValue environment variable to run the test. Because the value for sampleValue cannot be known ahead of time, it must be provided in the configuration interview by the user. The decodeArg(String[],int)method decodes the argument and passes the value to the sampleValue environment variable.
PAGE 51

a. Create a class (SampleInterview) that is a subtype of the Interview class. The following code creates the SampleInterview class. public class SampleInterview extends Interview { .... } b. Identify the new interview (SampleInterview) as a sub-interview of the parent interview. In the new sub-interview class, the constructor must take a reference to the parent interview as an argument and pass this reference to the superclass constructor.
PAGE 52

d. Use the setFirstQuestion method in the constructor to specify the first question in the sub-interview. The following setFirstQuestion code in the SampleInterview example specifies the first question. public class SampleInterview extends Interview { public SampleInterview(MidpTckBaseInterview parent) throws Fault { super(parent, "sample"); setResourceBundle("i18n"); setHelpSet("help/sampleInterview"); setFirstQuestion(first); } } e. Specify the question type.
PAGE 53

f. Implement exporting the configuration value to the test environment. One of the goals of the interview is to export the configuration value to the test environment. Each question has an export() method that is used for this purpose. The following code in the SampleInterview example exports the value to the test environment. StringQuestion first = new StringQuestion(this, "hello") { public void export(Map map) { map.put("sample.string.value", String.
PAGE 54

h. Use the getNext() method to determine the next question in the subinterview. Every question except the Final question must provide a getNext() method that determines the next (successor) question or null. Alternatively, if the Framework’s interview extension library is used, it’s possible to link questions without subclassing via Question.setPathResolver() or Question.linkTo() methods. For detailed information, see the com.sun.tck.j2me.interview.lib package API documentation.
PAGE 55

j. Use the FinalQuestion marker to identify the last question in the subinterview. At the end of the sub-interview, have the last question return an instance of FinalQuestion. FinalQuestion is only a marker and does not have question text, More Info, or a getNext method. The following code in the SampleInterview example identifies the final question in the sub-interview. Question qXXX = .........
PAGE 56

4. Update the interview .properties (resource) file. All question text is located in the interview.properties file associated with the interview class files and is identified by a unique question key. The question key is based on a name assigned by the test developer and must uniquely identify the question with the interview. Question keys are created in the following form: interview-class-name.question-name The interview .
PAGE 57

a. Create a help directory under the directory where the interview classes are located. For this example, use the following location: SimpleTestSuite/src/sample/suite/help b. Create a helpset file (sampleInterview.hs) under the help directory. The helpset file specifies the location of the map file for the More Info system. The following example shows the contents of the sampleInterview.hs helpset file used in the Simple Test Suite.
PAGE 58

d. Create a map file (sampleInterview.jhm) in the default directory. The JavaHelp system uses IDs from a map file to identify both the location and the HTML files that it loads for the More Info system. Each More Info file must have a corresponding entry in the map file of the form . The following example shows the contents of the map file used in the Simple Test Suite.
PAGE 59

e. Create the More Info topic files. The More Info topic files are provided in HTML format and displayed in the Configuration Editor’s More Info pane. Refer to the JavaTest Architect’s Guide for the procedure for creating More Info topic files. The following is an example of a More Info file. SampleInterview.hello PAGE 60
Building a Test Suite Refer to Chapter 2, “Building an Updated Simple Test Suite” on page 19 for the procedure to build a Java ME technology test suite by using Framework resources.
PAGE 61

CHAPTER 4 Writing Tests This chapter describes how to write different types of Java ME technology tests that use Framework resources and to set special properties required by the tests. General information about the process of creating tests can be located in Chapters 5 and 6 of the Java Technology Test Suite Development Guide. Additional information about writing tests for use with the JavaTest harness can be located in Chapters 3 of the JavaTest Architect’s Guide.
PAGE 62

Automated Test Execution FIGURE 4-1 and the associated text are for CLDC and MIDP execution mode. In the diagram, arrows indicate the direction of dataflow between the device and the workstation. The numbered items indicate the sequence and the content of the dataflow. FIGURE 4-1 Automated Test Execution PC or Workstation Device JavaTest Harness 1 getNextApp 2 Application Bundle AMS (agent + tests) 3 getNextTest Execution Server 4 Test Name Agent 5 sendTestResult Tests 1.
PAGE 63

While the tests from the application bundle are loaded onto the device by the AMS, the execution server establishes the sequence in which the tests in the bundle are run. 5. sendTestResult - The agent returns the test results to the execution server. Items 3, 4, and 5 repeat until all tests in the application bundle are run.
PAGE 64

The client test component must use the send and handleMessage methods in the J2MEDistributedTest class to send and receive messages to or from the other named components of the distributed test. Remote Test Component The remote test component of the distributed test must extend the com.sun.tck.j2me.services.messagingService.J2SEDistributedTest class and, to send messages to the client component of the distributed test, invoke the send method in the DistributedTest.
PAGE 65

The following is an example of the remote attribute entry that must be added to the test description file. CODE EXAMPLE 4-2 remote Attribute remote networkAgent: sample.pkg.SampleDistributedTest -msgSwitch $testMsgSwitch In the example, the remote attribute execution command is composed of the following values: ■ sample.pkg.SampleDistributedTest is the fully qualified name of the remote test class.
PAGE 66

The following is an example of the executeArgs attribute entry in which the $testMsgSwitch and $timeOut environment variables are specified. CODE EXAMPLE 4-4 executeArgs Attribute With Multiple Environment Variables executeArgs -msgSwitch $testMsgSwitch -timeout $timeOut Distributed Test Execution FIGURE 4-2 and the associated text are for MIDP execution mode. In the diagram, arrows indicate the direction of dataflow between the device and the workstation.
PAGE 67

FIGURE 4-2 Distributed Test Execution PC or Workstation JavaTest Harness Device 1 getNextApp 2 Application Bundle (agent + tests) Execution Server 3 getNextTest AMS 4 Test Name Passive Agent Send Test Result 9 Agent Server-Side Test Messaging Service 7 8 5 Check/Send Message 6 Get Message Tests 1. getNextApp - The AMS issues a getNextApp command to the execution server on the workstation. The AMS implementation is device specific and must be provided by the licensee. 2.
PAGE 68

5. Check or Send Message- The test sends either a message or a check message request to the Framework messaging service on the harness. 6. Get Message - The Framework messaging service on the harness sends the test a get message command. 7. Check or Send Message - The server-side test sends either a message or a check message request to the Framework messaging service on the harness. 8. Get Message - The Framework messaging service on the harness sends the server-side test a get message command. 9.
PAGE 69

Client Test Component The client test component of the interactive test must extend the MidDistribInteractiveTest class. This is the base class for distributed interactive tests and extends the com.sun.tck.j2me.services.messagingService.J2MEDistributedTest class. The MidDistribInteractiveTest class provides all of the common interfaces required by distributed interactive tests (such as setFormTitle, waitForMessage, messageReceived, addStatus, and cleanUp).
PAGE 70

The test description might also include the remoteSource and executeArgs attributes. See “remoteSource Attribute” on page 45 and “executeArgs Attribute” on page 45 for a description and example of these attribute entries. Required Interactive Test Keywords The following is an example of the keywords that must be added to the test description file for an interactive test. Both the distributed keyword and the interactive keyword are required.
PAGE 71

FIGURE 4-3 Interactive Test Execution PC or Workstation JavaTest Harness Device 1 getNextApp Application Bundle 2 (agent + tests) Execution Server 3 getNextTest AMS 4 Test Name 11 Send Test Result Passive Agent Agent Server-Side Test Messaging Service 9 Request an Action (if interactive) 7 8 5 Check/Send Message Tests 6 Get Message 10 Requested Action 1. getNextApp - The AMS issues a getNextApp command to the execution server on the workstation.
PAGE 72

4. Test Name - The execution server returns the name of the next test in the application bundle that the AMS should run. While the tests from the application bundle are loaded onto the device by the AMS, the execution server establishes the sequence in which the tests in the bundle are run. 5. Check or Send Message - The test sends either a message or a check message request to the Framework messaging service on the harness. 6.
PAGE 73

Testing Application Provisioning With OTA Tests Over-the-air (OTA) tests are MIDP-specific tests that verify an OTA application provisioning implementation. This includes obtaining, installing, and removing applications (MIDlet suites), and enforcing security requirements. Each OTA test has an associated application (a MIDlet suite) that is downloaded from the provisioning server and is installed and launched on the test device.
PAGE 74

done at the build time. If the test writer creates a JAR file or a JAD file with special information about the MIDlet suite as part of the bundle, the test writer must also create a manifest file (.mf). Test Description for OTA Tests The test description file for OTA tests must contain the ota keyword, the executeClass attribute, and the remote attribute. The test description might also include other attributes such as the remoteSource and executeArgs attributes.
PAGE 75

remote Attribute The remote attribute specifies the execution command for the server test component. The following is an example of the remote attribute entry that must be added to the test description file. CODE EXAMPLE 4-8 remote Attribute Entry remote networkAgent: sample.pkg.OTA.OTATest1 -httpServerPort $httpServerPort -testDir $testDir -OTAHandlerClass $OTAHandlerClass -OTAHandlerArgs $OTAHandlerArgs In the remote attribute, sample.pkg.OTA.

PAGE 76

CODE EXAMPLE 4-10 OTA Test Description File (Continued)

Test Specifications and Descriptions for Test

title

Over-the-Air Test

source

midlet/Test_MIDlet.java

executeClass

sample.pkg.OTA.

PAGE 77

CODE EXAMPLE 4-11 Trusted OTA Test Description File (Continued)

When other keywords (such as positive) are used, they are included in the same line as the trusted keyword and separated by white space.

PAGE 84

CODE EXAMPLE 4-17 Test Description for a Double Duty Test (Continued)

The value of the grant attribute is a list of space-separated permissions (in the example, javax.microedition.io.Connector.file.read and javax.microedition.io.Connector.file.

PAGE 86

CODE EXAMPLE 4-19 Test Description That Grants Permissions for a Security Test javax.microedition.io.Connector.file.write

Item	Value
title	Over-the-Air Test for trusted midlet
source	midlet/Test_MIDlet.java
executeClass	sample.pkg.OTA.Test_MIDlet
keywords	runtime positive trusted ota
remote	networkAgent: sample.pkg.OTA. PAGE 78 FIGURE 4-4 OTA Test Execution PC or Workstation JavaTest Harness Device 3 Request to Download Test Application OTA Server 4 Test Application AMS 5 Send Test Result Server-Side Test Passive Agent Test Application 1 Request an Action 2 Action 1. Request an Action - The server-side test requests an action from the test operator. 2. Action - The test operator action is sent to the AMS. 3. PAGE 79 Example of OTA Test The following is an example of an OTA server component. In the example, the source of the MIDlet suite is named Test_MIDlet.java and the JAD file is Test_MIDlet.jad. The JAD file contains the manifest file and the Test_MIDlet.class. PAGE 80 CODE EXAMPLE 4-12 Server Test Component Example (Continued) } } } } Testing Security-Constrained Functionality With Security Tests This section addresses writing different types of security tests, using keywords and attributes to mark different types of security tests, and using attributes in the test description to grant or deny the security permissions for the tests. PAGE 81 Trusted Tests Trusted tests verify API implementation behavior for signed MIDlet suites. In most cases, these tests verify that specification assertions related to signed MIDlet suites are properly implemented. Trusted MIDlet suites can be permitted to access APIs that are considered sensitive or to which access is restricted without any user action. The required permissions are granted without any explicit user action. Trusted tests must not be run in untrusted security mode. PAGE 82 If other keywords (such as positive) are used, they would be included in the same line as the untrusted keyword. The following is an example of a test description file that uses runtime, positive, and untrusted keywords. PAGE 83 The following is an example of adding a trusted keyword entry to a test description file. CODE EXAMPLE 4-15 trusted Keyword Entry
keywords	trusted
title	checking double duty test
source	Test.java
executeClass	sample.pkg. PAGE 85 The following is an example of a grant attribute and permissions added to a test description file. CODE EXAMPLE 4-18 grant Attribute Entry and Security Permissions
grant	javax.microedition.io.Connector.file.read javax.microedition.io.Connector.file.write

Denying Security Permissions When writing security tests, a test writer can specify the permissions that the security policy must not grant in the protection domain for this test application to execute and pass. Test writers can specify the denied security permissions by including a deny attribute in the test description.

PAGE 87

CODE EXAMPLE 4-21 Test Description That Denies Permissions for a Security Test

In the example, isFeatureSupported is an environment variable. Most environment variables can be used as Boolean expressions to filter out tests from a test run.

PAGE 93

Item	Value
title	checking deny permission
source	Test.java
executeClass	sample.pkg. PAGE 88 For example, the following test requires a Duke.png to create the Image object for successful execution. CODE EXAMPLE 4-22 Test That Requires an Image Resource Public class Test2 { public Status testImage() { Image imgI = null; String imageDir = "/shared/sample/pkg3/"; try { imgI = Image.createImage(imageDir+"Duke.png"); } catch (IOException e) { .... } if (imgI == null) { return Status.failed("Failed: no image is created."); } return Status. PAGE 89 The following is an example of a test description file containing a resources entry, directory, and file name. PAGE 90 Enabling Test Selection Test selection in a test run is of value to a user when a test suite includes tests for optional features that were not implemented. Because the assumption of tests is that the target implementation must support these features, the implementation fails tests that are not be applicable to it. This section describes how a developer can enable the filtering of the tests (test selection) in a test suite. PAGE 91 ■ selectIf expression in test description - This mechanism provides a flexible way for developers to make individual tests selectable (com.sun.tck.j2me.javatest.ExprFilter) by including a selectIf expression in test description. The test developer can include a selectIf expression in the test description file for a test. Each selectIf field contains a Boolean expression that is evaluated by the filter. The test is selected by the harness for a test run if the value is true. PAGE 92 1. Add a selectIf entry to the test description file for a test class that users might be required to filter out of a test run. The following is an example of a selectIF entry added to a test description file.
selectIf	isFeatureSupported
selectIf	isFeatureSupported

Chapter 4 Writing Tests 73

PAGE 94

2. Write an interview question that obtains the value of the environment variable from the user. To obtain the value of environment variables from users, test developers must write an interview class and create the required interview questions. If an interview class already exists in the test source, the developer can either add new questions to the existing interview or create a new sub-interview class containing the required questions and link it to the existing interview class.

PAGE 95

private void init() throws Fault { setResourceBundle("i18n"); setHelpSet("help/sampleInterview"); first = new StringQuestion(this, "hello"); first.setExporter( Exporters.getStringValueExporter("sample.string.value")); first.linkTo(qFeatureSupport); setFirstQuestion(first); } // This is the added question: Does the implementation support the feature ? private YesNoQuestion qFeatureSupport = new YesNoQuestion(this, "featureSupport") { public void clear() { setValue(YesNoQuestion.

PAGE 96

Question keys are created in the following form: interview-class-name.question-name ■ The .smry entry specifies the question title (in the example, Feature Support) that the Configuration Editor displays to the user. ■ The .text entry specifies the question text (in the example, Does your system support the feature that ... ?) that the Configuration Editor displays to the user. 4. Create a More Info topic file for the question.

PAGE 97

APPENDIX A Test API The following is the Java ME technology-specific API that every test developer must know: ■ Test ■ Status ■ MultiTest ■ J2MEDistributedTest ■ J2SEDistributedTest ■ DistribInteractiveTest ■ OTATest Test Interface name: com.sun.tck.cldc.lib.Test This is a Java ME technology version of the standard harness Test interface. This interface is implemented by all Java ME technology tests.

PAGE 98

A test must also define main as follows: CODE EXAMPLE A-2 Definition of main public static void main(String[] args) { Test t = new (); Status s = t.run(args, System.err, System.out); s.exit(); } Defining main in this manner enables the test to also be run standalone, independent of the harness. Status Class name: com.sun.tck.cldc.lib.Status This is a Java ME technology version of the standard harness Status class. It embodies the result of a test, a status-code, and a related message.

PAGE 99

J2MEDistributedTest Class name: com.sun.tck.j2me.services.messagingService.J2MEDistributedTest This is the base class for distributed tests for the Java ME technology component of the test. Each distributed test has a unique name used for identification during message exchange. The send and handleMessage methods can be used to send and receive messages to or from the other named components of the test. J2SEDistributedTest Class name: com.sun.tck.j2me.services.messagingService.

PAGE 100

OTATest Class name: com.sun.tck.midp.lib.OTATest This is the base class for the Java SE technology component of an OTA test. It provides various convenience methods which trigger installation, execution, or removal of an application.

PAGE 101

APPENDIX B Framework Bundle This appendix describes the contents of the redistributables directory provided by the Framework bundle. The contents of the redistributables directory are organized in the following structure: ■ lib Directory ■ src Directory ■ doc Directory lib Directory The lib directory contains the Framework JAR files and keystore files. The files provided in the lib directory are not part of the Framework functional groupings.

PAGE 102

CLDC and MIDP Execution DTF CLDC and MIDP Agents and Clients CommClients midp_xprtclnt.jar midp_agent.jar midp_commClient.jar midp_httpclnt.jar midp_agent10.jar cldc_commClient.jar cldc_xprtclnt.jar cldc_agent.jar datagram_commClient.jar CommService client.jar j2me_commClients.jar Plugins cldc_httpsrvr.jar j2me_communication.jar midp_httpsrvr.jar Messaging jkssigner.jar j2me_messaging.jar CommServers tckbuild.jar j2mefw_jt.jar datagram_comServer.jar j2me_httpCommServer.

PAGE 103

Core The following are core Framework files provided in the lib directory: ■ j2mefw_jt.jar - Harness plug-in code. Most of the Java SE platform code to support ME TCKs is in this file. ■ interviewlib.jar - Helper library for interview creation. CLDC and MIDP Execution The Framework provides the following two functional groupings of CLDC and MIDP execution files: ■ Agent and client .jar files ■ Plug-in .jar files CLDC and MIDP Agents and Clients The following are CLDC and MIDP agent and client .

PAGE 104

■ cldc_agent.jar - Standard harness agent for CLDC. Application model: Main Communication channel: pluggable. Plug-ins The following are the plug-in.jar files provided in the lib directory: ■ cldc_httpsrvr.jar - Implementation of the server interface for the harness plug-in. This server works with the HTTP-based Client for CLDC. ■ midp_httpsrvr.jar - Implementation of the server interface for the harness plug-in. This server works with the HTTP-based Client for MIDP. ■ jkssigner.jar - X.

PAGE 105

■ cldc_commClient.jar - Implementation of the Client interface for the CLDC device. This client uses HTTP for communication. ■ datagram_commClient.jar - Distributed test communication client interface implementation that uses datagrams for communication. CommServers The following are the CommServers .jar files provided in the lib directory: ■ datagram_comServer.jar - Datagram-based communication server for use with distributed tests. ■ j2me_httpCommServer.

PAGE 106

Application model: Xlet Pluggable communication channel ■ applet_agent.jar - JavaTest agent for Personal Profile. Application model: Applet Pluggable communication channel src Directory The src directory contains the Framework test sources, test descriptions, precompiled Framework classes, and scripts for tests precompilation. Framework classes consist of server, agent, interview, and communication channel source files.

PAGE 107

Agent Classes The following are the agent classes and interfaces provided in the src directory: ■ com/sun/cldc/communication/Client - Communication interface ■ com/sun/cldc/communication/MultiClient - Communication interface ■ com/sun/tck/midp/javatest/agent/MIDletAgent - Standard agent ■ com/sun/tck/cldc/javatest/agent/CldcAgent- Standard agent Digital Signer com/sun/tck/midp/signer/JKSSigner implements SuiteSigner interface.

PAGE 108

■ com/sun/tck/midp/interview/VmAdvancedInterview ■ com/sun/tck/midp/interview/VmInterview ■ com/sun/tck/midp/interview/MidpTckInterview ■ com/sun/tck/midp/interview/MidpTckBaseInterview ■ com/sun/tck/midp/interview/ConnectionInterview ■ com/sun/tck/midp/interview/TrustedInterview ■ com/sun/tck/midp/interview/MidpCldcTckInterview ■ com/sun/tck/midp/interview/OTAInterview ■ com/sun/tck/midp/interview/SigtestInterview Communication Channel The following classes execute on the server side.

PAGE 109

This class provides an implementation of the harness distribution mechanism on top of HTTP. ■ com/sun/tck/midp/javatest/MidBundler - MIDP-specific extension that builds on top of the generic CLDC mechanism. ■ com/sun/tck/midp/javatest/MessageSwitch - Support for distributed tests on MIDP. This class provides an implementation of the harness distribution mechanism on top of HTTP. ■ com/sun/tck/midp/javatest/RemoteManager - Support for distributed tests on MIDP.

PAGE 110

90 Java ME TCK Framework Developer’s Guide • July 2007

PAGE 111

APPENDIX C Test Description Fields and Keywords This appendix describes the Framework supported fields and keywords for test description files. The JavaTest harness requires that each test is accompanied by machine readable descriptive data in the form of test suite-specific name-value pairs contained in a test description file. The JavaTest harness uses the contents of the test description file to configure and run tests.

PAGE 112

TABLE C-1 lists the test description fields supported by the Framework and describes how their values are used by the harness when the tests are run. TABLE C-1 92 Framework Test Description Fields Field Description title A descriptive string that identifies what the test does. The title appears in reports and in the harness status window. source For compiler tests, contains the names of the files that are compiled during the test run.

PAGE 113

TABLE C-1 Framework Test Description Fields (Continued) Field Description executeArgs An array of strings that are passed to the test classes being executed. The arguments might be fixed but often involve symbolic values that are substituted from the test environment (variables defined elsewhere in the test environment). The result of substituting values can be seen in the resulting .jtr files.

PAGE 114

TABLE C-1 Framework Test Description Fields (Continued) Field Description remote Contains information required to run distributed network tests. resources Contains the location of the resource files that are needed by the test class. The resources files can be image, data, or class files. Separate multiple resources with white space. remoteSource Contains the source name of the remote test class of this distributed test group. Separate multiple remote source files with white space.

PAGE 115

TABLE C-2 Framework Keywords (Continued) Keyword Description runtime Identifies tests used with runtime products. trusted Identifies tests which must be run in a trusted (operator, manufacturer, and trusted third party) security domain. untrusted Identifies tests which must be run in an untrusted (unidentified third party) security domain.

PAGE 116

96 Java ME TCK Framework Developer’s Guide • July 2007

PAGE 117

Glossary The definitions in this glossary are intended for Java Compatibility Test Tools (Java CTT) and Java Technology Compatibility Kits (TCK). Some of these terms might have different definitions or connotations in other contexts. This is a generic glossary covering all of Sun’s CTTs and TCKs, and therefore, it might contain some terms that are not relevant to the specific product described in this manual.

PAGE 118

appeals process Application IDentifier (AID) Application Management Software (AMS) Application Programming Interface (API) Application Protocol Data Unit (APDU) assertion assertion testing automated tests behavior-based testing 98 A process for challenging the fairness, validity, accuracy, or relevance of one or more TCK tests. Tests that are successfully challenged are either corrected or added to the TCK’s exclude list.

PAGE 119

boundary value analysis class A test case development technique that entails developing additional test cases based on the boundaries defined by previously categorized equivalence classes. The prototype for an object in an object-oriented language. A class might also be considered a set of objects which share a common structure and behavior.

PAGE 120

distributed tests domain equivalence class partitioning exclude list first-level appeals process framework Graphical User Interface (GUI) HTML test description implementation instantiation interactive tests 100 Tests consisting of multiple components that are running on both the device and the JavaTest harness host.

PAGE 121

Java Platform, Standard Edition (Java SE platform) Java Application Manager (JAM) Java Archive (JAR) file Java Compatibility Test Tools (Java CTT) Java Community Process (JCP) program Java platform libraries Java specification Java Specification Request (JSR) Java technology Java Technology Compatibility Kit JavaTest harness agent A set of specifications that defines the desktop runtime environment required for the deployment of Java technology applications.

PAGE 122

JavaTest harness A test harness developed by Sun to manage test execution and result reporting for a Technology Compatibility Kit (TCK). The harness configures, sequences, and runs test suites. The JavaTest harness provides flexible and customizable test execution. It includes everything a test architect needs to design and implement tests for implementations of a Java specification. keywords Used to direct the JavaTest harness to include or exclude tests from a test run.

PAGE 123

included according to the referencing rules set out in that platform edition specification. Other referenced specifications must be referenced in their entirety. Program Management Office (PMO) protected API protection domain Reference Implementation (RI) second-level appeals process The administrative structure that implements the Java Community Process (JCP) program. APIs that require that an applet have permission to access them.

PAGE 124

structure-based testing system configuration tag test description Technology Compatibility Kit (TCK) TCK coverage file technology implementation 104 A set of test development methodologies that are based on the internal structure or logic of the system under test, not the description, behavior, or requirements of that system. This is commonly known as white-box or glassbox testing. Compatibility testing does not make use of structure-based test techniques.

PAGE 125

test command template test description test environment test execution model A generalized specification of a test command in a test environment. The test command is specified in the test environment using variables so that it can execute any test in the test suite regardless of its arguments. Machine-readable information that describes a test to the test harness so that it can correctly process and run the related test.

PAGE 126

work directory 106 A directory associated with a specific test suite and used by the JavaTest harness to store files containing information about the test suite and its tests.

PAGE 127

Index Symbols C .

PAGE 128

I instantiation, 100 interactive tests, 100 ISO 7816-4, 98 J JAM, 101 JAR, 101 Java Application Manager, 101 Java Archive, 101 Java Community Process Program, 101 Java Compatibility Test Tools, 101 Java CTT, 101 Java Platform Libraries, 101 Java platform, Standard Edition, 101 Java SE, 101 Java specification, 98, 101 Java Specification Request, 101 Java technology, 101 Java Technology Compatibility Kit, 101 JavaTest agent, 101 JavaTest harness, 102 JSR, 101 jtx files, 100 K keywords, 102 M Maintenance Le

PAGE 129

work directory, 106 Index 109

PAGE 130

110 Java ME TCK Framework Developer’s Guide • July 2007