Scriptability Test Plan

As noted in Designing for Scriptability, planning for testing should be an integral part of your application design and implementation. Your test plan should include regular milestones to confirm each step of scriptability. These can include:

1. Validating your terminology (verifying that your sdef is semantically correct).

2. Verifying that the application is receiving Apple events.

3. Verifying that your script commands get instantiated and executed when the corresponding Apple events are received.

4. Verifying that the expected methods are called to get and set scriptable values.

5. Verifying that support for more complex script statements you support, such as every and whose statements, is working. (For examples of these types of statements, see the object specifiers for the filter (whose) and every reference forms in Table 6-1.)

Your test plan should also include performance testing. For more information, see Performance Issues for Scriptability.

Use AppleScript Scripts to Test Your Application

As you implement your application, you should build up a suite of test scripts to exercise its scriptability. And the more features you make scriptable, the more your script testing can serve as a testbed for your entire application.

From Script Editor, you can cut and paste the Event Log output from your test scripts and save it for later regression testing. As you make changes to your application, whether in script-specific code or not, you can compare the current output to the saved version to help you find possible side-effects.

Make your test scripts as complete as possible by following these guidelines:

• Exercise the entire hierarchy of your AppleScript object model: for example, have your scripts get and set every accessible property of every accessible object, using repeat loops and every statements.

  After getting and setting values, use a log statement to log the properties property of the objects to record the changes.

• Test access by every applicable reference form: for example, iterate over scriptable collections by name, by ID, by index, and by any other form that applies. (See Table 6-1 for a list of reference forms.)

• Test creating new objects by using the make command and specifying properties.

  For example, this script tests Sketch by creating a new graphic object in an existing document:

  
  
  

  Listing 8-1  Simple test script

  tell application "Sketch"

  tell document "Test Doc.sketch"

  make new circle at end with properties {x position:50, y position:30, width:60, height:60}

  end tell

  end tell

• Test using whose clauses: they're a powerful scripting feature that is important to users.

  A whose clause can provide a good stress test for your scriptability, and may turn up performance issues.

• Run scripts that make changes then reverse them, then check whether the end result matches the starting point.

• Run your test scripts regularly, even after code changes that you don't expect to affect your application's scriptability.

For additional information on using test scripts, including examples, see Implementing a Verb-First Command—Align and Implementing an Object-First Command—Rotate.

Turn On Debugging Output for Scripting

Turning on Cocoa’s debugging output for scripting will help you debug your scriptable application. Debugging output shows information such as

• loaded scriptability information (from an sdef file or from script suite and script terminology files)

• executed script commands

• the arguments to executed commands

To turn on this support, you set a debugging value in the user defaults system provided by OS X. Default values in the global domain are accessible to any application. For example, during development, an application can set a user default value that a debugger checks to determine whether to display certain debug information. That’s the approach that Cocoa takes to log debug information for scripting.

defaults write com.apple.CocoaExamples.Sketch NSScriptingDebugLogLevel 1

defaults read com.apple.CocoaExamples.Sketch NSScriptingDebugLogLevel

defaults write com.apple.CocoaExamples.Sketch NSScriptingDebugLogLevel 0

tell application "Sketch"

    tell the first document

        set height of first circle to 100

    end tell

end tell

2006-02-24 13:51:29.951 Sketch[8245] Command: Intrinsics.set

    Direct Parameter: <NSPropertySpecifier: height>

    Receivers: <NSIndexSpecifier: circles 1 of orderedDocuments 1>

    Arguments: {Value = <NSAppleEventDescriptor: 100

2006-02-24 13:51:29.953 Sketch[8245] Result: (null)

2005-05-20 13:38:39.736 Sketch[2005-05-20 13:40:55.215 Sketch[516] Suite NSCoreSuite, apple event code 0x3f3f3f3f

2005-05-20 13:40:55.223 Sketch[516] Suite NSTextSuite, apple event code 0x3f3f3f3f

2005-05-20 13:40:55.253 Sketch[516] Suite Sketch, apple event code 0x736b7463

2005-05-20 13:40:55.259 Sketch[516] Command: NSCoreSuite.Set

    Direct Parameter: <NSPropertySpecifier: height>

    Receivers: <NSIndexSpecifier: circles 1 of orderedDocuments 1>

    Arguments: {Value = 100; }

    Key Specifier: <NSPropertySpecifier: height>

2005-05-20 13:40:55.261 Sketch[516] Result: (null)

Debugging Scriptability Information

To view an sdef file in a dictionary viewer, double-click it in the Finder. Double-clicking an sdef file in an Xcode project similarly opens it in a dictionary viewer window. To view or edit the XML for the file, open the sdef file with any plain text editor; in Xcode, select the sdef file and choose File > Open As > Plain Text File.

As you add information to an sdef file, you can verify that the file is still valid (semantically correct) by opening it with Script Editor or Xcode. If those applications cannot parse the file, you will see “Nothing to see here; move along.” displayed in the dictionary viewer. You can then open the Console log to see specific parsing errors.

xmllint --noout --postvalid --xinclude YourApp.sdef

 Command: get ('core'/'getd')

        Implementation class: NSGetCommand

        Name: "get", description: "Returns the value of the specified object(s)."

        Unnamed argument ('----'), type: specifier ('obj '), optional: no

            (No user-readable name or description needed for unnamed arguments)

        Result type: any ('****')

            Description: <none>

    Command: set ('core'/'setd')

        Implementation class: NSSetCommand

        Name: "set", description: "Sets the value of the specified object(s)."

        Unnamed argument ('----'), type: specifier ('obj '), optional: no

            (No user-readable name or description needed for unnamed arguments)

        Argument: Value ('data'), type: any ('****'), optional: no

            Name: "to", description: "The new value."

        Result type: <none> ('null')

            Description: <none>

print object [NSClassFromString(@"NSScriptCommand") currentCommand]

print object [[NSClassFromString(@"NSScriptCommand") currentCommand] appleEvent]

#define    myMasterSwitch    ( 0 )

#if        myMasterSwitch

#define    myLog1(x)    NSLog(x)

#define    myLog2(x,y)    NSLog(x,y)

#else

#define    myLog1(x)

#define    myLog2(x,y)

#endif

myLog2(@"SKTAlignCommand performDefaultImplementation command = %@", self);

2006-02-01 13:15:31.622 Sketch[1662] ME SKTAlignCommand performDefaultImplementation command = Sketch Suite.align

    Direct Parameter: <CFArray 0x3d3780 [0xa073a150]>{type = mutable-small, count = 2, values = (

    0 : <NSIndexSpecifier: graphics 1 of orderedDocuments named "SketchDoc">

    1 : <NSIndexSpecifier: graphics 2 of orderedDocuments named "SketchDoc">

)}

    Receivers: (null)

    Arguments: {

        "" = (

            <NSIndexSpecifier: graphics 1 of orderedDocuments named "SketchDoc">,

            <NSIndexSpecifier: graphics 2 of orderedDocuments named "SketchDoc">

        );

        toEdge = 1986359907;

    }

Additional Debugging Tips

There are a number of Apple event debugging tips that work well both for applications that use the Apple Event Manager directly and those that use frameworks such as Cocoa. For example, the chapter Testing and Debugging Apple Event Code in Apple Events Programming Guide describes how you can:

• Determine if your application is receiving Apple events (and log the information in those events).

• Use Script Editor as a test tool to send events to your application.

• Observe Apple events for multiple applications.

• Find third-party resources for monitoring and debugging Apple events and scriptable applications.

Performance Issues for Scriptability

Performance considerations should be an integral part of your test plan, so that as you implement your application, you always know when its performance increases or decreases. You may have a pretty good idea of which code paths are most likely to cause trouble, but acquiring regular timing information will help avoid surprises.

In general, you won't have to worry about performance in receiving Apple events and translating them into command objects, as applications don't commonly receive great numbers of Apple events, and Cocoa can decode them quite rapidly. However, your application should not rely on Apple events to communicate information that is more suitable to a lighter weight form of communication, such as notifications. See Kernel and Device Drivers Layer in Mac Technology Overview for more information on the interprocess communications options available in OS X.

If an Apple event initiates a script command that requires your application to perform an asynchronous (and perhaps lengthy) operation, you can suspend the command and resume it when the operation is complete, as described in Suspending and Resuming Apple Events and Script Commands. Depending on the operation, you may want to provide progress information while the command is suspended. However, suspending a command (or an Apple event) does not prevent the originating script from timing out if your application takes too long to respond to an event.

Performance can also be an issue in determining how to implement a particular application script command. For example, it may be easier to implement an object-first command, where the command calls a method for each object on which it operates. However, using an object-first approach may have performance consequences in cases where significant overhead is incurred for each object, especially when dealing with large numbers of objects. As an alternative, using the verb-first approach may allow you to minimize overhead and optimize operations on multiple objects. These approaches are described in Object-first Versus Verb-first Script Commands.

For most applications, performance of Cocoa scripting's default handling of whose clauses should be sufficient. However, if you find the need to speed it up, you can use the mechanism described in Implementing A Method for Evaluating Object Specifiers.

Cocoa scripting relies on key-value coding (KVC) to get and set values and find objects in your application. Performance of KVC can vary depending on the methods you implement to support it. This is especially true for operations on arrays. For tips on handling these issues, see Performance Considerations With KVC.

For a general introduction to performance issues, see Performance Starting Point for OS X.