Initial commit

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Alex Vollmer
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,69 @@
+# Overview #
+
+Tune-up is a collection of JavaScript utilities that builds upon and improves
+the `UIAutomation` library provided by Apple for testing iOS applications via
+Instruments (get it? "tune-up"? Instruments? get it?). 
+
+While the JavaScript library provided by Apple is fairly complete and robust,
+it is a bit wordy and repetitive at times. This project aims to reduce as much
+pain as possible when writing UI tests by enhancing the existing API. It also
+provides some basic structure for your tests in a manner familiar to most
+testers.
+
+# Installation #
+
+Put the files for this project in the same location as your test scripts
+that your run from Instruments. At the top of each test script include the
+following:
+
+    #import "tuneup.js"
+
+# Test Structure #
+
+To create a test case, use the `test()` function, which takes the name of
+the test case as a string, and a function. The function will be given a
+`UIATarget` instance and a `UIAApplication` instance. For example:
+
+    test("Sign-In Screen", function(target, app) {
+      // The target and app arguments are your portals into the running application
+      // Exercise and validate to your heart's content
+    });
+
+    test("Sign-out Screen", function(target, app) {
+      // now exercise and validate the sign-out screen
+    });
+
+See the `test.js` file for details.
+
+## Assertions ##
+
+Tune-up comes with a handful of basic xUnit-like assertions (and more are on
+the way). For now though, the basic assertions supported are:
+
+  * `assertNotNull`
+  * `assertEquals`
+  * `assertTrue`
+  * `assertFalse`
+  * `fail`
+
+See the `assertions.js` file for all the details.
+
+## `UIAutomation` Extensions ##
+
+The `UIAutomation` library is pretty full-featured, but is a little wordy.
+Tune-up provides several extensions to the built-in `UIAutomation` classes in
+an attempt to cut down on the verbosity of your tests.
+
+See the `uiautomation-ext.js` for details.
+
+# Note on Patches/Pull Requests #
+
+  * Fork the project.
+  * Make your feature addition or bug fix.
+  * Test the darn thing with your own apps (built-in testing to come)
+  * Commit to your local repo and send me a pull request. Bonus points for 
+    topic branches.
+
+# Copyright #
+
+Copyright (c) 2010 Alex Vollmer. See LICENSE for details.

assertions.js

@@ -0,0 +1,49 @@
+/**
+ * Assert that the +received+ object matches the +expected+ object (using
+ * plain ol' ==). If it doesn't, this method throws an exception with either
+ * a default message, or the one given as the last (optional) argument
+ */
+function assertEquals(expected, received, message) {
+  if (received != expected) {
+    if (! message) message = "Expected " + expected + " but received " + received;
+    throw message;
+  }
+}
+
+/**
+ * Asserts that the given expression is true and throws an exception with
+ * a default message, or the optional +message+ parameter
+ */
+function assertTrue(expression, message) {
+  if (! expression) {
+    if (! message) message = "Assertion failed";
+    throw message;
+  }
+}
+
+/**
+ * Asserts that the given expression is false and otherwise throws an 
+ * exception with a default message, or the optional +message+ parameter
+ */
+function assertFalse(expression, message) {
+  assertTrue(! expression, message);
+}
+
+/**
+ * Asserts that the given object is not null or UIAElementNil (UIAutomation's
+ * version of a null stand-in). If it is null, an exception is thrown with
+ * a default message or the given optional +message+ parameter
+ */
+function assertNotNull(thingie, message) {
+  if (thingie == null || thingie.toString() == "[object UIAElementNil]") {
+    if (message == null) message = "Expected not null object";
+    throw message;
+  }
+}
+
+/**
+ * Just flat-out fail the test with the given message
+ */
+function fail(message) {
+  throw message;
+}

lang-ext.js

@@ -0,0 +1,22 @@
+/**
+ * Extend +destination+ with +source+
+ */
+function extend(destination, source) {
+  for (var property in source) {
+    destination[property] = source[property];
+  }
+  return destination;
+};
+
+extend(Array.prototype, {
+  /**
+  * Performs the given function +f+ on each element in the array instance.
+  * The function is given the index of the current object and the object
+  * itself for each element in the array.
+  */
+  each: function(f) {
+    for (i = 0; i < this.length; i++) {
+      f(i, this[i]);
+    }
+  }
+});

test.js

@@ -0,0 +1,36 @@
+/**
+ * Run a new test with the given +title+ and function body, which will
+ * be executed within the proper test declarations for the UIAutomation
+ * framework. The given function will be handed a +UIATarget+ and
+ * a +UIApplication+ object which it can use to exercise and validate your
+ * application.
+ *
+ * The +options+ parameter is an optional object/hash thingie that 
+ * supports the following:
+ *    logTree -- a boolean to log the element tree when the test fails (default 'true')
+ *
+ * Example:
+ * test("Sign-In", function(target, application) {
+ *   // exercise and validate your application.
+ * });
+ *
+ */
+function test(title, f, options) {
+  if (options == null) {
+    options = {
+      logTree: true
+    };
+  }
+  target = UIATarget.localTarget();
+  application = target.frontMostApp();
+  UIALogger.logStart(title);
+  try {
+    f(target, application);
+    UIALogger.logPass(title);
+  }
+  catch (e) {
+    UIALogger.logError(e);
+    if (options.logTree) target.logElementTree();
+    UIALogger.logFail(title);
+  }
+}

tuneup.js

@@ -0,0 +1,4 @@
+#import "assertions.js"
+#import "uiautomation-ext.js"
+#import "lang-ext.js"
+#import "test.js"

uiautomation-ext.js

@@ -0,0 +1,60 @@
+#import "assertions.js"
+#import "lang-ext.js"
+
+extend(UIATableView.prototype, {
+  /**
+   * A shortcut for:
+   *  this.cells().firstWithName(name)
+   */
+  cellNamed: function(name) {
+    return this.cells().firstWithName(name);
+  },
+
+  /**
+   * Asserts that this table has a cell with the name (accessibility label)
+   * matching the given +name+ argument.
+   */
+  assertCellNamed: function(name) {
+    assertNotNull(this.cellNamed(name), "No table cell found named '" + name + "'");
+  }
+});
+
+extend(UIAElement.prototype, {
+  /**
+   * A shortcut for touching an element and waiting for it to disappear.
+   */
+  tapAndWaitForInvalid: function() {
+    this.tap();
+    this.waitForInvalid();
+  }
+});
+
+extend(UIAApplication.prototype, {
+  /**
+   * A shortcut for getting the current view controller's title from the
+   * navigation bar. If there is no navigation bar, this method returns null
+   */
+  navigationTitle: function() {
+    navBar = this.mainWindow().navigationBar();
+    if (navBar) {
+      return navBar.name();
+    }
+    return null;
+  }
+});
+
+extend(UIANavigationBar.prototype, {
+  /**
+   * Asserts that the left button's name matches the given +name+ argument
+   */
+  assertLeftButtonNamed: function(name) {
+    assertEquals(name, this.leftButton().name());
+  },
+
+  /**
+   * Asserts that the right button's name matches the given +name+ argument
+   */
+  assertRightButtonNamed: function(name) {
+    assertEquals(name, this.rightButton().name());
+  }
+});