Inherits from NSObject
Declared in SLTerminal.h

Overview

The singleton SLTerminal instance communicates with the Automation instrument in order to evaluate arbitrary JavaScript, in particular scripts which call APIs defined by the UIAutomation JavaScript framework.

The methods in the SLTerminal (DebugSettings) category may be useful in debugging Subliminal. They may not be of much use in debugging tests because tests don’t use the terminal directly.

The methods in the SLTerminal (Internal) category are to be used only within Subliminal.

The SLTerminal (ConvenienceFunctions) category defines APIs that structure the definition and evaluation of JavaScript functions.

It is oftentimes more readable and efficient to evaluate some bit of JavaScript by defining a generic function and then calling it with specific arguments, rather than formatting and evaluating a long block of statements each time.

Tasks

Getting the Shared Terminal

Evaluating JavaScript

  • – eval:

    Evaluates the specified JavaScript script within UIAutomation and returns the result as an Objective-C object.
  • – evalWithFormat:

    Evaluates the specified JavaScript script after substituting the specified argument variables into the script.

Debugging Subliminal

Internal Methods

Evaluating Functions

Waiting on Boolean Expressions and Functions

Properties

evalQueue

The serial queue on which the receiver evaluates all JavaScript.

@property (nonatomic, readonly) dispatch_queue_t evalQueue

Declared In

SLTerminal.h

scriptLoggingEnabled

Determines whether the terminal will log scripts as it evaluates them.

@property (nonatomic) BOOL scriptLoggingEnabled

Discussion

If YES, the terminal will log each script before evaluating it. This allows developers to understand exactly what UIAutomation is doing when a given Subliminal API is invoked.

Declared In

SLTerminal.h

scriptNamespace

The namespace (in SLTerminal.js) in which the SLTerminal defines variables.

@property (nonatomic, readonly) NSString *scriptNamespace

Declared In

SLTerminal.h

Class Methods

sharedTerminal

Returns the terminal.

+ (SLTerminal *)sharedTerminal

Return Value

The shared SLTerminal instance.

Declared In

SLTerminal.h

Instance Methods

currentQueueIsEvalQueue

Whether or not the current queue is the evalQueue.

- (BOOL)currentQueueIsEvalQueue

Return Value

Whether or not the current queue is the evalQueue.

Discussion

To avoid deadlocks, use this method to check if you’re on the evalQueue before dispatch_syncing a block to it.

Declared In

SLTerminal.h

eval:

Evaluates the specified JavaScript script within UIAutomation and returns the result as an Objective-C object.

- (id)eval:(NSString *)script

Parameters

script

The script to evaluate. May be a JavaScript expression, statement, or sequence of statements. This value must not be nil.

Return Value

The value of the last expression evaluated, as an Objective-C object:

  • If the value is of type "string", -eval: will return an NSString * that is equal to the value.
  • If the value is of type "boolean", -eval: will return an NSNumber * whose -boolValue is equal to the value.
  • If the value is of type "number", -eval: will return an NSNumber * whose primitive value (using an accessor appropriate to the value’s format) is equal to the value.
  • Otherwise, -eval: will return nil.

Discussion

The evaluation is done using eval().

This method blocks until the script has been evaluated, and so must not be called from the main thread.

Exceptions

NSInvalidArgumentException

Thrown if script is nil.

NSInternalInconsistencyException

Thrown if this method is called from the main thread.

SLTerminalJavaScriptException

Thrown if the script could not be evaluated, or if the script threw an exception when evaluated.

Declared In

SLTerminal.h

evalFunctionWithName:params:body:withArgs:

Adds the JavaScript function with the specified description to the terminal’s namespace, if necessary; evaluates it with the given arguments; and returns the result, if any.

- (NSString *)evalFunctionWithName:(NSString *)name params:(NSArray *)params body:(NSString *)body withArgs:(NSArray *)args

Parameters

name

The name of the function to add to the terminal’s namespace, if necessary.

params

The string names of the parameters of the function.

body

The body of the function: one or more statements, with no function closure.

args

The arguments to the function, as strings.

Return Value

The result of evaluating the specified function, or nil if the function does not return a value.

Discussion

This is a convenience wrapper for the other methods in this section. An invocation of this method like

NSString *result = [[SLTerminal sharedTerminal] evalFunctionWithName:@"SLAddTwoNumbers"
                                                              params:@[ @"one", @"two" ]
                                                                body:@"return one + two;"];
                                                            withArgs:@[ @"5", @"7" ]];

is equivalent to calling

[[SLTerminal sharedTerminal] loadFunctionWithName:@"SLAddTwoNumbers"
                                           params:@[ @"one", @"two" ]
                                             body:@"return one + two;"];
NSString *result = [[SLTerminal sharedTerminal] evalFunctionWithName:@"SLAddTwoNumbers"
                                                            withArgs:@[ @"5", @"7" ]];

Exceptions

NSInternalInconsistencyException

Thrown if a function with the specified description has previously been loaded with different parameters and/or body.

SLTerminalJavascriptException

Thrown if the function name, params, or body cannot be evaluated when the function is added to the terminal’s namespace, or if an exception occurs when evaluating the function.

See Also

Declared In

SLTerminal+ConvenienceFunctions.h

evalFunctionWithName:withArgs:

Evaluates a JavaScript function existing in the terminal’s namespace with the given arguments and returns the result, if any.

- (NSString *)evalFunctionWithName:(NSString *)name withArgs:(NSArray *)args

Parameters

name

The name of a function previously added to the terminal’s namespace.

args

The arguments to the function, as strings.

Return Value

The result of evaluating the specified function, or nil if the function does not return a value.

Discussion

A function like

function SLAddTwoNumbers(one, two) {
    return one + two;
}

would be evaluated with the arguments 5, 7 by calling this method as follows:

NSString *result = [[SLTerminal sharedTerminal] evalFunctionWithName:@"SLAddTwoNumbers"
                                                            withArgs:@[ @"5", @"7" ]];

After evaluation, result would contain @"12".

Exceptions

NSInternalInconsistencyException

Thrown if a function with the specified name has not previously been loaded.

SLTerminalJavascriptException

Thrown if an exception occurs when evaluating the function.

See Also

Declared In

SLTerminal+ConvenienceFunctions.h

evalWithFormat:

Evaluates the specified JavaScript script after substituting the specified argument variables into the script.

- (id)evalWithFormat:(NSString *)script, ...

Parameters

script

A format string (in the manner of [NSString stringWithFormat:]) to be evaluated as JavaScript after formatting. This value must not be nil.

...

(Optional) A comma-separated list of arguments to substitute into script.

Return Value

The value of the last expression evaluated, as an Objective-C object. See eval: for more information.

Discussion

This method is a wrapper around eval:: see that method for further discussion.

Warning: Variable arguments that are strings need to be escaped, using [NSString slStringByEscapingForJavaScriptLiteral], if they are to be substituted into a JavaScript string literal.

Exceptions

NSInvalidArgumentException

Thrown if script is nil.

NSInternalInconsistencyException

Thrown if this method is called from the main thread.

SLTerminalJavaScriptException

Thrown if the script could not be evaluated, or if the script threw an exception when evaluated.

Declared In

SLTerminal.h

loadFunctionWithName:params:body:

Adds the JavaScript function with the specified description to the terminal’s namespace.

- (void)loadFunctionWithName:(NSString *)name params:(NSArray *)params body:(NSString *)body

Parameters

name

The name of the function.

params

The string names of the parameters of the function.

body

The body of the function: one or more statements, with no function closure.

Discussion

This method provides an idempotent, structured API for defining new functions.

A function like

function SLAddTwoNumbers(one, two) {
    return one + two;
}

would be added by calling this method as follows:

[[SLTerminal sharedTerminal] loadFunctionWithName:@"SLAddTwoNumbers"
                                           params:@[ @"one", @"two" ]
                                             body:@"return one + two;"];

Developers should prefix their functions' names to avoid collisions with functions defined by Subliminal. Subliminal reserves the “SL” prefix.

Exceptions

NSInternalInconsistencyException

Thrown if a function with the specified description has previously been loaded with different parameters and/or body.

SLTerminalJavascriptException

Thrown if the function name, params, or body cannot be evaluated.

See Also

Declared In

SLTerminal+ConvenienceFunctions.h

shutDown

Causes SLTerminal.js to finish evaluating commands.

- (void)shutDown

Discussion

The terminal starts up automatically when the UIAutomation instrument is attached and evaluating SLTerminal.js. SLTerminal.js then evaluates commands (scripts) sent through this terminal until this method is called, at which point SLTerminal.js will exit, and UIAutomation will terminate the application.

This method is called by the shared test controller when testing has finished.

Declared In

SLTerminal.h

waitUntilFunctionWithNameIsTrue:whenEvaluatedWithArgs:retryDelay:timeout:

Waits for a JavaScript function existing in the terminal’s namespace to evaluate to true, given the specified arguments, within a specified timeout.

- (BOOL)waitUntilFunctionWithNameIsTrue:(NSString *)name whenEvaluatedWithArgs:(NSArray *)args retryDelay:(NSTimeInterval)retryDelay timeout:(NSTimeInterval)timeout

Parameters

name

The name of a function previously added to the terminal’s namespace.

args

The arguments to the function, as strings.

retryDelay

The interval at which to re-evaluate the function.

timeout

The interval for which to wait.

Return Value

YES if and when the function evaluates to true within the timeout; otherwise, NO.

Discussion

This is a wrapper around waitUntilTrue:retryDelay:timeout: where condition is a call to the specified function with the given arguments.

Exceptions

NSInternalInconsistencyException

Thrown if a function with the specified name has not previously been loaded.

SLTerminalJavascriptException

Thrown if an exception occurs when evaluating the function.

Declared In

SLTerminal+ConvenienceFunctions.h

waitUntilTrue:retryDelay:timeout:

Waits for an arbitrary JavaScript expression to evaluate to true within a specified timeout.

- (BOOL)waitUntilTrue:(NSString *)condition retryDelay:(NSTimeInterval)retryDelay timeout:(NSTimeInterval)timeout

Parameters

condition

A boolean expression in JavaScript, on whose truth the method should wait.

retryDelay

The interval at which to re-evaluate condition.

timeout

The interval for which to wait.

Return Value

YES if and when the expression evaluates to true within the timeout; otherwise, NO.

Discussion

This method is designed to wait efficiently by performing the waiting/re-evaluation entirely within UIAutomation’s (JavaScript) context.

The expression will be re-evaluated at small intervals. If and when the expression evaluates to true, the method will immediately return YES; if the expression is still false at the end of the timeout, this method will return NO.

Warning: This method does not itself throw an exception if the condition fails to become true within the timeout. Rather, the caller should throw a suitably specific exception if this method returns NO.

Exceptions

SLTerminalJavascriptException

Thrown if condition cannot be evaluated.

See Also

Declared In

SLTerminal+ConvenienceFunctions.h