JavaScript Extensions

Useful JavaScript utilties and extensions

TuneupJS comes with several handy functions and extensions to existing JavaScript objects. These break down into a handful of extensions on core classes and extensions of the UIAutomation framework itself.

UIAutomation Extensions

These extensions can be found in the uiautomation-ext.js file.

UIATableView.prototype.cellNamed(name)

Returns the first table cell matching the given name parameter. This is a shortcut for:

this.cells().firstWithName(name);

UIATableView.prototype.assertCellNamed(name)

Performs an assertion that the target table view has a cell with the given name.

UIAElement.prototype.elementJSONDump(recursive, attributes, visibleOnly)

Dumps a String representation for the target in JSON format which can be used for making screen assertions.

If the recursive parameter is set to true, this function will recurse through the window hierarchy calling the same function on sub-views.

The attributes parameter is an array of strings indicating which attributes of each UIAElement you wish to log. If not specified, the default values are ["name", "label", "value", "isVisible"].

If the visibleOnly parameter is set to true, this method will ignore any views that are hidden. The default value is false.

UIAElement.prototype.logElementJSON(attributes)

Executes elementJSONDump without recursion on the target and logs the results via the UIALogger object. Note that the attributes given to this method are passed straight-through to elementJSONDump.

UIAElement.prototype.logVisibleElementJSON(attributes)

Executes elementJSONDump without recursion, passing the given attributes straight-through and ignoring any hidden elements.

UIAElement.prototype.logElementTreeJSON(attributes)

Executes elementJSONDump with recursion enabled and passing the attributes argument straight-through.

UIAElement.prototype.logVisibleElementTreeJSON(attributes)

Executes elementJSONDump with recursion enabled, passing attributes straight-through and ignoring hidden elements.

UIAElement.prototype.waitUntilVisible(timeout)

Blocks execution of the test until the target UIAElement is visible or until timeout (in seconds) has occurred.

UIAutomation will allow you to get references to UIAElements that may not yet be visible on the screen. Use this method to pause your test until the UI has settled down so that you can safely make assertions against it.

UIAElement.prototype.waitUntilInvisible(timeout)

The inverse of waitUntilVisible.

UIAElement.prototype.waitUntilFoundByName(name, timeout)

Waits for a child-element with the given name to appear before the timeout (in seconds) passes.

UIAElement.prototype.waitUntilNotFoundByName(name, timeout)

Wait until the child element named by name is not found before timeout (in seconds) passes.

UIAElement.prototype.waitUntilAccessorSuccess(f, timeout, label)

Wait until the function f returns a valid object. For convenience, return the element that was found. The optional label argument can be given for more useful error messages if the method fails.

UIAElement.prototype.waitUntil(filter, condition, timeout, description)

Waits until the element fulfills a condition up to a timeout (in seconds).

The filter argument is a function applied to each sub-element for any transformation required to be applied before filtering. For a simple pass-through, provide a function like this:

function(e) { return e; };

The condition argument is a function applied to each filtered element. This function will be executed for the filtered elements and if it is unable to return true before timeout, the function will throw an exception.

The timeout specifies the wait period before failing the execution of this method (in seconds).

The description parameter is used as a part of the error message in the exception thrown if the function fails.

UIAElement.prototype.waitUntilHasName(name, timeout)

Wait for the element to have the given name before the given timeout.

UIAElement.prototype.vtap(timeout)

Wait for the given element to be visible (before timeout) and then tap it.

UIAElement.prototype.svtap(timeout)

Wait for the given element to be visible (before timeout) and scroll it to be visible, then tap it.

UIAElement.prototype.tapAndWaitForInvalid(timeout)

Tap the element and wait for it to be invalid (typically due to a new view-controller appearing on-screen) before the given timeout.

UIAElement.prototype.equals(other)

Two element objects are equal if they have the same name, type and rect() on the screen.

UIAElement.prototype.captureWithName(name)

Captures the view as a PNG with the given name

UIAElementNil.prototype.isNotNil()

Always returns true. This function is handy when iterating through child-elements, some of which may be instances of UIAElementNil, which does not have this method.

UIAElementNil.prototype.isValid()

Always returns false. This function is handy when iterating through child-elements, some of which may be instances of UIAElementNil, which does not have this method.

UIAElementNil.prototype.isVisible()

Always returns false. This function is handy when iterating through child-elements, some of which may be instances of UIAElementNil, which does not have this method.

UIAElementArray.prototype.withNameRegex(pattern)

Returns items in the array whose name() property matches the given regular expression pattern.

UIAElementArray.prototype.firstWithNameRegex(pattern)

Returns the first item whose name() matches the given regular expression pattern.

UIAApplication.prototype.navigationTitle()

A shortcut for getting the current view controller's title from the navigation bar. If there is no navigation bar, this method returns null.

UIAApplication.prototype.isPortraitOrientation()

A shortcut for checking that the interface orientation in either portrait mode.

UIAApplication.prototype.isLandscapeOrientation()

A shortcut for checking that the interface orientation in one of the landscape orientations.

UIANavigationBar.prototype.assertLeftButtonNamed(name)

Asserts that the left button's name matches the given name argument.

UIANavigationBar.prototype.assertRightButtonNamed(name)

Asserts that the right button's name matches the given name argument

UIATarget.prototype.isPortraitOrientation()

A shortcut for checking that the interface orientation in either portrait mode.

UIATarget.prototype.isLandscapeOrientation()

A shortcut for checking that the interface orientation in one of the landscape orientations.

UIATarget.prototype.isSimulator()

Determine if we are running on a simulator.

UIATarget.prototype.isDeviceiPad()

A convenience method for detecting that you're running on an iPad.

UIATarget.prototype.isDeviceiPhone()

A convenience method for detecting that you're running on an iPhone or iPod Touch.

UIATarget.prototype.isDeviceiPhone5()

A shortcut for checking if target device is iPhone 5 (or iPod Touch 5th generation).

UIATarget.prototype.captureAppScreenWithName(imageName)

A convenience method for producing screenshots without status bar. You can use this method to capture screenshots for making screen assertions.

UIATarget.prototype.logDeviceInfo()

Logs device information via UIALogger which includes the device model, the size of the screen, the device name, the system name and the system version.

UIAKeyboard.prototype.keyboardType()

Returns one of the following constants:

  • KEYBOARD_TYPE_UNKNOWN
  • KEYBOARD_TYPE_ALPHA
  • KEYBOARD_TYPE_ALPHA_CAPS
  • KEYBOARD_TYPE_NUMBER_AND_PUNCTUATION
  • KEYBOARD_TYPE_NUMBER

UIAKeyboard.prototype.typeString(string)

Directly enters the given string one character at a time.

UIATextField.prototype.typeString(string)

Same as the method above, but attached directly to a text field.

UIATextField.prototype.clear()

Clears the text field using the typeString() function.

UIATextView.prototype.typeString(string)

Types a string into the text view via the typeString() method described above.

UIATextView.prototype.clear()

Clears the contents of the text view using typeString().

JavaScript Extensions

These can be found in the lang-ext.js file.

extend(destination, source)

Copies the properties from destination to source. This is the main function used to extend other JavaScript objects. Be careful with this one!

dumpProperties(object)

A debugging method that dumps the object's properties to a returned String.

getMethods(object)

Returns all of the methods for the given object as an array of functions.

reduce(callback, initialValue)

Applies the callback function to each node in the element tree starting from the current element.

Callback function takes (previousValue, currentValue <UIAElement>, accessor_prefix, toplevel <UIAElement>) where previousValue is: initialValue (first time), otherwise the previous return from the callback currentValue is the UIAElement at the current location in the tree accessor_prefix is the code to access this element from the toplevel element toplevel is the top-level element on which this reduce function was called.

find(criteria, varName)

Find elements by the given criteria function. Returns associative array {accessor: element} of results.

elementAccessorDump(varName, visibleOnly)

Dump tree in .js format for copy/paste use in code varname is used as the first element in the canonical name.

waitUntilAccessorSelect(lookupFunctions, timeoutInSeconds)

Wait until one lookup_function(this) in an associative array of lookup functions returns a valid lookup. Return an associative array of {key: <element found>, elem: <the element that was found>}

checkIsEditable()

Verify that a text field is editable by tapping in it and waiting for a keyboard to appear.

Array.prototype.contains(f)

Applies the given function f to each element in the array. The first element for which f returns true will be the object returned from this method.

For example:

var stuff = ["alpha", "bravo", "charlie"];
var foundCharlie = stuff.contains(function(i) { return i === "charlie" });
// foundCharlie = true
var foundEd = stuff.contains(function(i) { return i === "edward" });
// foundEd = false

Array.prototype.unique()

Returns only the unique elements in the array. For example:

var stuff = ["alpha", "bravo", "bravo", "charlie"];
var uniqStuff = stuff.unique();
// uniqStuff = ["alpha", "bravo", "charlie"]

String.prototype.trim()

Returns a String from the given target with the same content minus any leading or trailing whitespace characters.

String.prototype.ltrim()

Returns a String from the given target with the same content minus any leading whitespace characters.

String.prototype.rtrim()

Returns a String from the given target with the same content minus any trailing whitespace characters.

String.prototype.lcfirst()

Returns a String from the target with the same content but ensuring that the first letter is lower-cased.