Recording Scripts: Comparing Values and Images within a Script


JavaStar provides two types of comparison features: Verify and Synchronize. Both allow you to specify all or a portion of the window for comparison to recorded states. You can compare the attributes of a component or an image of what the component looks like. The difference between Verify and Synchronize is what happens during playback.

When you play back a test, a Verify operation performs the comparison as you specify. If the comparison fails, Verify attempts the comparison again, repeating attempts until it reaches the time-out value (which you can set in Playback Options). If the comparison fails at time-out, Verify notes the failure and the script continues to execute. The script itself does not fail and can end normally, though the log contains a failure that you can examine when you view the results.

A synchronize operation is the same as a verification,with one exception. When the timeout expires without a match, throws an SyncException and ends script execution, rather than logging a failure and continuing.

Choosing Between Verify and Synchronize

Use Verify when you are verifying attributes of a component (or an image) that are not critical to the continued operation of the script. For example, if you are checking the contents of a text field where the results won't impact the ability of the script to continue, Verify is a good choice.

Use Synchronize when your script needs to wait for a particular state change in the application before it can progress, or when the results of a comparison are critical to the script being able to finish. For example, if you expect the application to enable a button that you want to validate, and if you require that button for further testing, it makes sense to choose Synchronize over Verify.

Note - The JavaStar API provides a third way for you to do comparisons--the JS.check() function. This method does a boolean check of an attribute or value you specify. You use JS.check() by editing your script to include the call; JavaStar does not insert these checks automatically while recording. For information on JS.check(), see check(boolean, String) in the "Component and Control Classes" chapter of the JavaStar API Reference.

How JavaStar Compares Component Attributes

When you select a component for comparison, JavaStar compares the attributes of the component and the attributes of its superclass. JavaStar doesn't compare every attribute, just the most relevant ones. For example, when you compare the attributes of a button, JavaStar compares the label, but not the foreground and background color.

Table 4-1 lists the attributes that are compared for each component type.

Comparison of Attributes

If you compare a... Then the following attributes are compared...
Button Label Action command
Canvas Graphics (optional)
Checkbox Label State
CheckboxMenuItem State
Choice All items Selected index Selected item
Component Is it enabled? Is it being shown? Is it visible? What kind of cursor? Popup menus
Container All components have to match. For BorderLayout, the components are compared according to their orientation, i.e., only east, west, north, south, and center are compared. The rest of the components are ignored. For layout other than BorderLayout, components are compared according to their position in the component array returned by the getComponents() method.
Dialog Title Is it modal? Is it resizable?
FileDialog Mode (load or save) Directory File
Frame Title MenuBar Is it resizable?
Label Alignment of text Text
List Does it allow multiple selections? All items Number of visible lines Selected items
Menu All MenuItems Is it a tear-off Menu?
MenuBar All Menus HelpMenu
MenuItem Is it enabled? Label Action command Short cut
Panel Graphics (optional)
PopupMenu No additional attributes
Scrollbar Unit increment Block increment Minimum value Maximum value Orientation Current value Visible amount
ScrollPane Scrollbar display policy Size of the view port Current scroll position
TextArea Number of columns Number of rows Visibility of scrollbars
TextComponent Text Is it editable?
TextField Is echo char set? Number of columns Echo char
Window Warning string

Selecting Components

When setting up a comparison, use the mouse and keystrokes described in Table 4-2. When you select a component, the component flashes to show you what you selected, and the selection code appears in the Select for Verification or Select for Synchronization dialog.

Once you select a component, you can use the arrow keys to further navigate. The up arrow selects the parent of the component and the down arrow selects its first child. The right and left arrows move to the components that precede and follow this component, respectively.

Selecting GUI Components for Comparison

If you want to select... Then...
A frame or dialog window Click a component of the frame and press F1.
Any other kind of component Click it.

Note - You can't select a menu or menubar for verification or synchronization. You can only verify these components through the containing frame.

Selecting Data Members and Methods

The Verify and Synchronize functions let you compare return values for one or more of a component's data members and simple methods. To do this, you select the option to compare using simple methods and data members. The procedure described in the section Verifying or Synchronizing Components explains the steps in detail. What's important to know now is how JavaStar defines the terms.

A simple method is any method that does not take any parameters and that returns a basic Java type--for example, int, long, float, and boolean, as well as String, java.awt.Point, java.awt.Color, java.awt.Rectangle, and java.awt.Dimension.

Note that if you query for the return value of a method while you're in the Verify or Synchronize screens, JavaStar executes the method. If the method you choose alters the state of the component, this could create a false comparison, so use caution.

Gold Files and Directories

A gold file is where JavaStar records the attributes of a component for comparison purposes. You generate gold files when you use Verify or Synchronize to compare using gold file attributes. Because the component you select might be a frame, gold files also contain the attributes for child components, as well. When you compare failure results later on, JavaStar reconstructs the components using these attributes. If an attribute includes an image (such as an image on a Canvas) that image is also saved to the gold file.

JavaStar stores gold files in a directory named scriptname.gold, located in the work directory. All comparison images are named sequentially, using the format C1, C2, C3, and so on. When you later run a test, any gold file comparison failures are stored in the failure directory you define. Failure files use the name format of f. followed by the gold file name. So, if the C2 comparison fails, you'll find the C2.f file in your failure directory, showing the component attributes during the test run. The gold files are not changed until you specifically specify that you want them replaced or deleted.

Other chapters that discuss gold files:

Verifying or Synchronizing Components

The procedure and the screens for verifying and synchronizing are identical, except for their titles. Because the steps to use these features are identical as well, this procedure shows screen shots just one of the two options (Verify).

Remember that even though the comparison procedures are the same, verifications and synchronizations do not cause the same types of failures when the comparisons don't match. A verification logs the failure and continues, while a synchronization ends script execution with an exception. This is the only difference between the two comparison types.

This procedure assumes you are already in record mode and have progressed your test to the point at which you're ready to do your comparison.

  1. Click Verify or Synchronize.
    This pauses recording and changes the right side of the Record/Playback window to show the Verify or Synchronize screen.

    Verify--first screen

  2. Choose whether you want to compare a single component or all visible windows of your program under test.
    Select an Object is the default option. If you choose All visible windows, Verify ignores any components you select next.

  3. If you chose Select an Object, move the mouse to your program under test and click the component you want to verify.
    You can select any GUI component in your application or applet. Table 4-2 describes how to select the different types of GUI components.
    Once you click on a component, the selection code appears in the text portion of the verify screen.

  4. Decide whether you want to use the default comparison JavaStar suggests or if you want to customize the comparison.
    Once you select All visible windows or click on a component, JavaStar updates the screen to present you with the most likely comparison you might want to do. For example, if you chose a button, JavaStar suggests a comparison using enabled--which means to compare and see if this button is enabled. Refer to Figure 4-4 to see this example.
    To accept the default, click Use default, then skip ahead to step 8.
    To change the default, click Customize.

    Verify--first screen with a component selected

  5. Choose the method of comparison you want to use.
    The screen now shows your options for comparison (see Figure 4-5.)

    How to Verify screen

Choose your comparison type based on these descriptions:

Comparison Options

Verify Means
Using enabled Verify that the component selected (such as a button or a panel) is enabled.
Using text Compare the text of the selected component. The definition of component text depends on the type of component. For a text entry field, this is the text inside the field. For a Button, it's the Button Label. For a Frame, it's the title, and for a Label, it's the text of the label.
Using simple methods and data members Compare the return value for this component's data members or methods. You'll be able to select which data members and methods you want to compare when you advance to the next screen.
Using attributes
in gold file
Compare the component text and attributes to the information stored in a gold file. The gold file is generated when you set up the comparison.
Include image in compare When comparing the contents and attributes of the selected component, also perform an image comparison. This option is only enabled when the component you are comparing is a canvas or a panel containing images. You can only select this option once you've turned on Using attributes in gold file.

  1. If you chose to compare using a method other than simple methods and data members, skip to the next step. Otherwise, click the Select simple methods and data members button.
    For simple methods and data members, the screen changes to present you with a list of the data members and methods (including inherited ones) available for this component. See Figure 4-6 for an example. The list is presented alphabetically by field/method name.
    At any point, you can examine the current return value for a method by clicking the returns button, or get the value of a data member by clicking the = button. This does not select the item for comparison--it just tells you what the item returns.

    Note - Use caution when clicking returns, as this executes the method. If the method alters the state of the component, this could create a false comparison.

    To select one or more items for comparison:

    1. Scroll to the item you want to compare.

    2. To highlight the line, click anywhere on the line other than on the returns button.

      Verify--data member/method selection

  2. Click Enter a Purpose.
    The screen changes to show you the component you have selected (What), the type of comparison you chose (How), and leaves a blank for you to provide a purpose (Why).

    Verify--enter a purpose

  3. Type a purpose for the comparison in the Why field.
    The string you enter shows up in the log file, and can be helpful when evaluating failures.

  4. Click Insert verification into text to record the comparison.
    JavaStar records the attribute values or gold file to compare and adds the comparison code to the script. You can see the comparison code in the Record/Playback window. After you click Finish, the Select for Verification/Select for Synchronization dialog stays open, so you can define more comparisons.

  5. When you are done defining comparisons, click the Continue button in the left panel of the window.
    This closes the Verify/Synchronize screen and returns you to record mode.



Send feedback to JavaStar-feedback@suntest.com
Copyright © 1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, CA 94303. All rights reserved.