Writing Card Files Manually

C H A P T E R 25

In Java Device Test Suite releases prior to version 2.1, card files were authored directly by the test developer. Beginning with version 2.1, card files are, by default, generated automatically from markup you embed in comment blocks in the source code. For more information, refer to Chapter 4.

Note - If you create card files manually in a directory that contains test classes, you must add this line to your test pack’s build.properties file:
generate.card.files=false
If you fail to override the default value of true, automatically generated card files overwrite the ones you create manually. If you write card files only in directories that have no test classes, as described in Classless Card Files, your card files are preserved regardless of the value of generate.card.files.

A tool exists for checking the contents and consistency of card files, regardless of whether they were generated or authored directly. For more information, refer to Chapter 12.

This chapter describes how to directly edit a card file. It contains the following sections:

Comment Lines

Test Case Definitions

Required File Definitions

Property Definitions

Choosing Between Card File and testsuite.info Properties

While the testsuite.info file describes a test pack as a whole, card files describe the contents of directories that contain test classes. The word “card” has no special significance. Every directory that contains one or more test classes must have a card file that names the test classes, the test cases they contain, related files they access, and properties they use.

The card file naming structure is containingDir.card, where containingDir is the unqualified name of the directory containing the card file. For example, a directory named uitests must have the card file uitests.card.

In general syntax, a card file is a Java programming language properties file. For a technical description of property file syntax, see http://java.sun.com/j2se/1.5.0/docs/api/java/util/ Properties.html#load(java.io.InputStream)

However, there are two differences:

A card file property can have multiple values. For example, the following multiple assignment is meaningful in a card file:

Class.requires=/x
Class.requires=/y

In a card file, Class.requires has two values, /x and /y.

In a card file, the \n escape sequence is not supported for property values.

You can write card file lines in any order. However, be sure to observe the syntax and requirements noted in the following sections. The harness does not check for invalid entries. An error can cause unexpected behavior by the harness or a test.

CODE EXAMPLE 25-1 shows a simple card file for a directory containing two test classes, SampleAutomatedTest1.java and SampleAutomatedTest2.java, and a class used by SampleAutomatedTest1.java, RequiredClass.java.

CODE EXAMPLE 25-1 Simple Card File
# Specify the test cases in a test class SampleAutomatedTest1=TestCase1,TestCase2 # Specify a file needed by a test case in this class SampleAutomatedTest1.requires=RequiredClass.class # Specify a property used by a test case, and its default value SampleAutomatedTest1.property=TestProp=test # Specify the test case in a second test class SampleAutomatedTest2=TestCase1

CODE EXAMPLE 25-1 Simple Card File

# Specify the test cases in a test class
SampleAutomatedTest1=TestCase1,TestCase2
 
# Specify a file needed by a test case in this class
SampleAutomatedTest1.requires=RequiredClass.class
 
# Specify a property used by a test case, and its default value
SampleAutomatedTest1.property=TestProp=test
 
# Specify the test case in a second test class
SampleAutomatedTest2=TestCase1

Comment Lines

A comment line begins with a pound sign (#), for example:

# This is a comment.

The harness ignores comment lines.

Test Case Definitions

A card file must contain one line for each test class in the directory. The line names the test class and its test cases, separated by commas, for example:

# Test class (SpriteTest.java) with a single test case (Rotate)
SpriteTest=Rotate
 
# Test class with two test cases
CollisionTest=SpritePixel,ImageBounds

Note - Do not separate test case names with space characters. Such a space causes the build to fail.

In this guide, a test class named in a card file is referred to as TestClassName, and a test case named in a card file is referred to as testCaseName. In the previous examples, SpriteTest and CollisionTest are TestClassNames and Rotate, SpritePixel, and ImageBounds are testCaseNames.

Required File Definitions

If a test case requires another file (for example, a helper class or a file containing an image or a sound), name the file (or files) as shown in CODE EXAMPLE 25-2.

CODE EXAMPLE 25-2 Example Required File Definitions
SpriteTest.requires=com/sun/midp/images/sprite1.png SpriteTest.requires=EncErr_Streams.class

In this example, SpriteTest is the test class name.

Observe the following requirements when writing path names:

The path name separator must be a slash (/) character.

If the path name contains a separator (as in the first line in the CODE EXAMPLE 25-2), the path is relative to the directory specified in the test pack property TestClassesDir. For example, for runtime test packs, this directory is typically bin/client/verified (relative to the test pack root).

If the path name does not contain a separator (as in the second line in CODE EXAMPLE 25-2), the file is in the same directory as the card file.

Note - Properties are not inherited. In particular, required file properties declared in class X do not apply to X’s superclass or subclasses. Be sure to declare the files that each class requires.

After a build, you can use the Card File Checker utility to verify that all of the required files are recorded with a .requires property. For more information, see Chapter 12.

Property Definitions

If a test class or case needs a user-editable property, name the property and specify its default value with the following syntax:

TestClassName.property=PropertyName=DefaultValue

For example:

SpriteTest.property=MaxDistance=12

To add a user-editable property to a case, use the following syntax:

TestClassName.testCaseName.property=PropertyName=DefaultValue

For example:

MaterialBasic.setGetShininess.property=MaxDistance=12

You can use the same property name for different test classes or cases that are in the same card file, but if you do so, you are defining different properties. The following example defines two properties that have the same name.

SpriteTest.property=MaxDistance=12
ImageTest.property=MaxDistance=20

In this example, if SpriteTest retrieves MaxDistance with Runner.getProperty() as described in Obtaining a Property Value, it receives the value 12 (assuming the user has not changed the default value). If ImageTest retrieves MaxDistance, it receives the value 20.

A user can inspect or override a default test case property value from the tester edition of the harness. To inspect or override a default test case property value, right click the test case in the harness tree and choose Configure Test.

Note - If a test class extends a superclass, and the superclass needs a property that is undefined in testsuite.info, specify the property for the test class (the subclass). For example, if test class X extends class Y, and class Y uses property MaxSize, make this card file entry:
X.property=MaxSize=value.

Class and Case Keyword Definitions

Use a keyword property definition to provide the harness with a list of keywords to filter (subset) test cases. Select a keyword based on its descriptive relevance to the test class or test case from the perspective of the tester. To see the current list of keywords and their definitions, launch the harness and create or open a work directory. Open an interview from the harness menu bar by means of Configure > Edit Configuration or Configure > New Configuration. In the Test Selection section of the interview, answer Yes to Specify Keywords? The More Info pane displays the current list of keywords.

Use the keyword specifier in the card file to specify the keyword for an individual test case or all of the test cases in a test class. A test case can have more than one keyword. Multiple keywords are separated by spaces.

Use one of the following syntaxes in a card file to add keywords:

TestClassName.keyword=keyword1 keyword2

In this case, all test cases under TestClassName are marked with the list of mentioned keywords.

TestClassName.testCaseName.keyword=keyword1 keyword2 keyword3

In this case, only individual TestClassName.testCaseName test case are marked with the list of mentioned keywords.

Note - All interactive tests must have the keyword interactive.

Note - Avoid adding incorrectly named keywords, as this is not checked at any step.

Special Property Definitions

Use a special property definition to direct the harness to add a line to the JAD file that it creates for each test bundle. In effect, a special property definition is a way to pass a static parameter to an application management system (AMS), sometimes called a Java application manager. The static parameter only applies to the test bundle associated with the JAD file.

Use the following syntax in a card file to add a line to the JAD file:

ClassName.specialproperty=<jad>.n=LineToAdd

n is a number that distinguishes multiple specialproperty entries in the same card file. The harness does not interpret LineToAdd but simply copies it to the JAD file. The test device AMS interprets LineToAdd when it downloads the JAD file. It is the test developer’s responsibility to ensure that LineToAdd is meaningful to the AMS and follows the JAD file syntax. The JAD file is defined in the MIDP 1.0 specification.

For example, to add a line to a JAD file associated with a test bundle containing, MIDlet2:AlarmMidlet include a line like this in the card file:

SpriteTest.specialproperty=<jad>.1=MIDlet2:AlarmMidlet

Choosing Between Card File and `testsuite.info` Properties

Define a property for a test case to use in either the testsuite.info file or a card file. Consider the following to make your choice:

If test cases in multiple test classes use a property, it is easier to define it in the testsuite.info file, which makes it accessible to all test cases in the test pack.

If a property must be accessible to administrators, define it in the testsuite.info file.

If a property only needs to be accessible to users, and is only used by one or more test cases in one test class, define the property in the card file.