illuminator 0.1.0

data/gem/resources/js/Illuminator.js

@@ -0,0 +1,228 @@
+/**
+ * Main entry point
+ *
+ * There are no arguments to this function, because it will be controlled by Config arguments
+ * and invoked by testAutomatically.js (a generated file).  See the documentation on how to
+ * set up and run Illuminator.
+ */
+function IlluminatorIlluminate() {
+    // initial sanity checks
+    assertDesiredSimVersion();
+
+    // send test definitions back to framework
+    if (!host().writeToFile(config.buildArtifacts.automatorScenarioJSON,
+                            JSON.stringify(automator.toScenarioObject(false), null, "    ")))
+    {
+        throw new IlluminatorSetupException("Could not save necessary build artifact to " +
+                                            config.buildArtifacts.automatorScenarioJSON);
+    }
+    notifyIlluminatorFramework("Saved scenario definitions to: " + config.buildArtifacts.automatorScenarioJSON);
+
+    // run app-specific callback
+    if (!automator._executeCallback("onInit", {entryPoint: config.entryPoint}, false, false)) return;
+
+    // choose entry point and go
+    switch (config.entryPoint) {
+
+    case "runTestsByName":
+        automator.runNamedScenarios(config.automatorScenarioNames, config.automatorSequenceRandomSeed);
+        break;
+
+    case "runTestsByTag":
+        if (0 == (config.automatorTagsAny.length + config.automatorTagsAll.length + config.automatorTagsNone.length)) {
+            UIALogger.logMessage("No tag sets (any / all / none) were specified, so printing some information about defined scenarios");
+            automator.logInfo();
+            notifyIlluminatorFramework("Successful launch");
+        } else {
+            automator.runTaggedScenarios(config.automatorTagsAny,
+                                         config.automatorTagsAll,
+                                         config.automatorTagsNone,
+                                         config.automatorSequenceRandomSeed);
+        }
+        break;
+
+    case "describe":
+        notifyIlluminatorFramework("Successful launch");
+        var appMapMarkdownPath    = config.buildArtifacts.appMapMarkdown;
+        var automatorMarkdownPath = config.buildArtifacts.automatorMarkdown;
+        var automatorJSONPath     = config.buildArtifacts.automatorJSON;
+        host().writeToFile(appMapMarkdownPath, appmap.toMarkdown());
+        UIALogger.logMessage("Wrote AppMap definitions to " + appMapMarkdownPath);
+        host().writeToFile(automatorMarkdownPath, automator.toMarkdown());
+        UIALogger.logMessage("Wrote automator definitions to " + automatorMarkdownPath);
+        host().writeToFile(automatorJSONPath, JSON.stringify(automator.toScenarioObject(true), null, "    "));
+        UIALogger.logMessage("Wrote automator definition data to " + automatorJSONPath);
+        break;
+
+    default:
+        notifyIlluminatorFramework("Successful launch");
+        throw new IlluminatorSetupException("Unknown Illuminator entry point specified: " + config.entryPoint);
+    }
+}
+
+
+/**
+ * Send a message back to the log analyzers (ruby)
+ *
+ * @param message string
+ */
+function notifyIlluminatorFramework(message) {
+    UIALogger.logDebug(config.saltinel + " " + message + " " + config.saltinel);
+}
+
+function isMatchingVersion(input, prefix, major, minor, rev) {
+    var findStr = prefix + major;
+
+    if (undefined !== minor) {
+        findStr += "." + minor;
+        if (undefined !== rev) {
+            findStr += "." + rev;
+        }
+    }
+
+    return input.indexOf(findStr) > -1;
+}
+
+function isSimVersion(major, minor, rev) {
+    return isMatchingVersion(target().systemVersion(), "", major, minor, rev);
+}
+
+function assertDesiredSimVersion() {
+    var ver = target().systemVersion();
+    if (("iOS " + ver).indexOf(config.automatorDesiredSimVersion) == -1) {
+        throw new IlluminatorSetupException("Simulator version " + ver + " is running, but generated-config.js " +
+            "specifies " + config.automatorDesiredSimVersion);
+    }
+}
+
+function actionCompareScreenshotToMaster(parm) {
+    var masterPath   = parm.masterPath;
+    var maskPath     = parm.maskPath;
+    var captureTitle = parm.captureTitle;
+    var delayCapture = parm.delay === undefined ? 0.4 : parm.delay;
+
+    delay(delayCapture); // wait for any animations to settle
+
+    var diff_pngPath = IlluminatorScriptsDirectory + "/diff_png.sh";
+    UIATarget.localTarget().captureScreenWithName(captureTitle);
+
+    var screenshotFile  = captureTitle + ".png";
+    var screenshotPath  = config.screenshotDir + "/" + screenshotFile;
+    var compareFileBase = config.screenshotDir + "/compared_" + captureTitle;
+
+    var output = target().host().performTaskWithPathArgumentsTimeout("/bin/sh",
+                                                                     [diff_pngPath,
+                                                                      masterPath,
+                                                                      screenshotPath,
+                                                                      maskPath,
+                                                                      compareFileBase],
+                                                                     20);
+
+    // turn the output into key/value pairs separated by ":"
+    var outputArr = output.stdout.split("\n");
+    var outputObj = {};
+    for (var i = 0; i < outputArr.length; ++i) {
+        var sp = outputArr[i].split(": ", 2)
+        if (sp.length == 2) {
+            outputObj[sp[0]] = sp[1];
+        }
+    }
+
+    // sanity check
+    if (!outputObj["pixels changed"]) {
+        throw new IlluminatorRuntimeVerificationException("actionCompareScreenshotToMaster: diff_png.sh failed to produce 'pixels changed' output");
+    }
+
+    // if differences are outside tolerances, throw errors
+    var allPixels = parseInt(outputObj["pixels (total)"]);
+    var wrongPixels = parseInt(outputObj["pixels changed"]);
+
+    var allowedPixels = parm.allowedPixels === undefined ? 0 : parm.allowedPixels;
+    var errmsg = "";
+    if (allowedPixels < wrongPixels) {
+        errmsg = ["Screenshot differed from", masterPath,
+                  "by", wrongPixels, "pixels. ",
+                  "Comparison image saved to:", compareFileBase + ".png",
+                  " and comparison animation saved to:", compareFileBase + ".gif"].join(" ");
+
+        if (parm.deferFailure === true) {
+            automator.deferFailure(errmsg);
+        } else {
+            throw new IlluminatorRuntimeVerificationException(errmsg);
+        }
+    }
+
+    if (parm.allowedPercent !== undefined) {
+        var wrongPct = 100.0 * wrongPixels / allPixels;
+        if (wrongPct > parm.allowedPercent) {
+            errmsg = ["Screenshot differed from", masterPath,
+                      "by", wrongPct, "%. ",
+                      "Comparison image saved to:", compareFileBase + ".png",
+                      " and comparison animation saved to:", compareFileBase + ".gif"].join(" ");
+
+            if (parm.deferFailure === true) {
+            } else {
+                throw new IlluminatorRuntimeVerificationException(errmsg);
+            }
+        }
+    }
+}
+
+function actionLogAccessors(parm) {
+    if (parm !== undefined && parm.delay !== undefined) {
+        delay(parm.delay);
+    }
+    var visibleOnly = parm !== undefined && parm.visibleOnly === true;
+    UIALogger.logDebug(target().elementReferenceDump("target", visibleOnly));
+}
+
+function actionCaptureElementTree(parm) {
+    target().captureImageTree(parm.imageBaseName);
+}
+
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+// Appmap additions - common capabilities
+////////////////////////////////////////////////////////////////////////////////////////////////////
+appmap.createOrAugmentApp("Illuminator").withScreen("do")
+    .onTarget(config.implementation, function() { return true; })
+    // onTarget(config.implementation...) is a HACK.
+    // Illuminator doesn't define implementations, so we use what we're given.
+    //   (i.e. you shouldn't copy/paste this example into your project code)
+
+    .withAction("delay", "Delay a given amount of time")
+    .withParam("seconds", "Number of seconds to delay", true, true)
+    .withImplementation(function(parm) {delay(parm.seconds);})
+
+    .withAction("debug", "Print the results of a debug function")
+    .withParam("debug_fn", "Function returning a string", true)
+    .withImplementation(function(parm) { UIALogger.logMessage(parm.debug_fn()); })
+
+    .withAction("logTree", "Log the UI element tree")
+    .withImplementation(function() { UIATarget.localTarget().logElementTree(); })
+
+    .withAction("logAccessors", "Log the list of valid element accessors")
+    .withParam("visibleOnly", "Whether to log only the visible elements", false, true)
+    .withParam("delay", "Number of seconds to delay before logging", false, true)
+    .withImplementation(actionLogAccessors)
+
+    .withAction("captureElementTree", "Take individual screenshots of all screen elements")
+    .withParam("imageBaseName", "The base name for the image files", true, true)
+    .withImplementation(actionCaptureElementTree)
+
+    .withAction("fail", "Unconditionally fail the current test for debugging purposes")
+    .withImplementation(function() { throw new IlluminatorRuntimeVerificationException("purposely-thrown exception to halt the test scenario"); })
+
+    .withAction("verifyScreenshot", "Validate a screenshot against a png template of the expected view")
+    .withParam("masterPath", "The path to the file that is considered the 'expected' view", true, true)
+    .withParam("maskPath", "The path to the file that masks variable portions of the 'expected' view", true, true)
+    .withParam("captureTitle", "The title of the screenshot to capture", true, true)
+    .withParam("delay", "The amount of time to delay before taking the screenshot", false, true)
+    .withParam("allowedPixels", "The maximum number of pixels that are allowed to differ (default 0)", false, true)
+    .withParam("allowedPercent", "The maximum percentage of pixels that are allowed to differ (default 0)", false, true)
+    .withParam("deferFailure", "Whether to defer a failure until the end of the test", false, true)
+    .withImplementation(actionCompareScreenshotToMaster)
+
+    .withAction("testAsAction", "Execute an entire test as one action")
+    .withParam("test", "The function that performs the entire test")
+    .withImplementation(function (parm) { parm.test(); });

data/gem/resources/js/Preferences.js

@@ -0,0 +1,24 @@
+// Preferences.js
+//
+// Provides the set of known user preferences for Illuminator
+
+
+(function() {
+
+    var root = this,
+        preferences = null;
+
+    // put preferences in namespace of importing code
+    if (typeof exports !== 'undefined') {
+        preferences = exports;
+    } else {
+        preferences = root.preferences = {};
+    }
+
+    preferences.extensions = {};
+    preferences.extensions.reduceTimeout = 10; // seconds
+
+    preferences.automator = {};
+    preferences.automator.onError = {};
+
+}).call(this);

data/gem/resources/scripts/UIAutomationBridge.rb

@@ -0,0 +1,248 @@
+require 'bundler/setup'
+require 'rubygems'
+require 'json'
+require 'base64'
+require 'dnssd'
+require 'socket'
+require 'timeout'
+require 'optparse'
+
+# all parsing code goes here
+def parse_arguments(args)
+  ret = {}
+  ret["timeout"] = 15
+  op = OptionParser.new do |opts|
+    opts.banner = "Usage: #{__FILE__} [options]"
+    opts.separator ""
+    opts.separator "Specific options:"
+
+    opts.on("-a", "--argument=[JSON]",
+            "Pass the supplied JSON data over the bridge") do |v|
+      ret["argument"] = v
+    end
+
+    opts.on("-b", "--b64argument=[B64-JSON]",
+            "Pass the base64-encoded JSON data over the bridge") do |v|
+      ret["b64argument"] = v
+    end
+
+    opts.on("-s", "--selector=SELECTOR",
+            "Call the given function (selector) via the bridge") do |v|
+      ret["selector"] = v
+    end
+
+    opts.on("-c", "--callUID=UID",
+            "Use the given UID to properly identify the return value of this call") do |v|
+      ret["callUID"] = v
+    end
+
+    opts.on("-r", "--hardwareID=[HARDWAREID]",
+            "If provided, connect to the physical iOS device with this hardware ID instead of a simulator") do |v|
+      ret["hardwareID"] = v
+    end
+
+    opts.on("-t", "--timeout=[TIMEOUT]",
+            "The timeout in seconds for reading a response from the bridge (default 15)") do |v|
+      ret["timeout"] = v.to_i
+    end
+
+    opts.on_tail("-h", "--help", "Show this message") do
+      puts opts
+      exit
+    end
+
+  end
+  op.parse!(args)
+  return ret
+end
+
+
+# communicate the result to the console
+# success: boolean whether it all went well
+# failmsg: what to say went wrong
+# checkpoints: some stuff to print out, debug info
+# output_data: the actual results
+def print_result_and_exit(success, failmsg, checkpoints, response=nil)
+  output_data = {}
+  output_data["checkpoints"] = checkpoints
+  output_data["response"] = response unless response.nil?
+  output_data["success"] = success
+  output_data["message"] = failmsg
+  puts JSON.pretty_generate(output_data)
+  exit(success ? 0 : 1)
+end
+
+
+def get_host_port_of_hardware_id(hardware_id, timeout_seconds)
+  service = DNSSD::Service.new
+  host, port = nil, nil
+  begin
+    Timeout::timeout(timeout_seconds) do
+      service.browse '_bridge._tcp' do |result|
+        if result.name.eql? "UIAutomationBridge_#{hardware_id}"
+          resolver = DNSSD::Service.new
+          resolver.resolve result do |r|
+            host = r.target
+            port = r.port
+            break unless r.flags.more_coming?
+          end
+          break
+        end
+      end
+      return host, port
+    end
+  rescue Timeout::Error
+  end
+  return host, port
+end
+
+
+def connect(host, port, timeout=5)
+  addr = Socket.getaddrinfo(host, nil)
+  sock = Socket.new(Socket.const_get(addr[0][0]), Socket::SOCK_STREAM, 0)
+
+  if timeout
+    secs = Integer(timeout)
+    usecs = Integer((timeout - secs) * 1_000_000)
+    optval = [secs, usecs].pack('l_2')
+    sock.setsockopt Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, optval
+    sock.setsockopt Socket::SOL_SOCKET, Socket::SO_SNDTIMEO, optval
+  end
+  begin
+    sock.connect(Socket.pack_sockaddr_in(port, addr[0][3]))
+    return sock, ""
+  rescue Exception => e
+    return nil, "Failed to connect to #{host}:#{port} - #{e.class.name} - #{e.message}"
+  end
+end
+
+
+# these describe what we expect to have happen, and we will check them off as they do
+checkpoints = {}
+checkpoints["ruby"] = true
+checkpoints["argument"] = nil
+checkpoints["hardwareID"] = nil
+checkpoints["connection"] = nil
+checkpoints["request"] = nil
+checkpoints["response"] = nil
+checkpoints["callUIDMatch"] = nil
+
+
+# process the input
+options = parse_arguments(ARGV)
+
+# verify that the input selector was provided
+if options["selector"].nil?
+    print_result_and_exit(false, "selector not provided", checkpoints)
+end
+
+# decode b64 argument if provided
+unless options["b64argument"].nil?
+  begin
+    decoded_arg = Base64.strict_decode64(options["b64argument"])
+    options['argument'] = decoded_arg # the next if block will find & process this
+    JSON.parse(decoded_arg)
+  rescue ArgumentError => e
+    print_result_and_exit(false, "Error decoding b64argument: #{e.message}", checkpoints)
+  rescue JSON::ParserError => e
+    print_result_and_exit(false, "Decoded b64argument does not appear to contain (valid) JSON", checkpoints)
+  end
+end
+
+# parse JSON in argument if provided (or b64 provided)
+unless options["argument"].nil?
+  checkpoints["argument"] = false
+  begin
+    parsed_arg = JSON.parse(options["argument"])
+    options["jsonArgument"] = parsed_arg
+    checkpoints["argument"] = true
+  rescue JSON::ParserError => e
+    print_result_and_exit(false, "Error parsing JSON argument: #{e.message}", checkpoints)
+  end
+end
+
+# build the request that will go the server
+request_hash = {}
+request_hash['argument'] = options["jsonArgument"] unless options["jsonArgument"].nil?
+request_hash["selector"] = options["selector"]
+request_hash["callUID"] = options["callUID"]
+request = request_hash.to_json
+checkpoints["actual_request"] = request_hash
+
+# get the host/port according to whether we are using hardware
+host, port = '127.0.0.1', 4200
+unless options["hardwareID"].nil?
+  checkpoints["hardwareID"] = false
+  host, port = get_host_port_of_hardware_id(options["hardwareID"], 3)
+  if host.nil? or port.nil?
+    print_result_and_exit(false, "Failed to get host/port for hardware ID", checkpoints)
+  end
+  checkpoints["hardwareID"] = true
+end
+
+# connect
+checkpoints["host"] = host
+checkpoints["port"] = port
+checkpoints["connection"] = false
+socket_stream, err_message = connect host, port
+if socket_stream.nil?
+    print_result_and_exit(false, err_message, checkpoints)
+end
+checkpoints["connection"] = true
+
+begin
+  # send request
+  checkpoints["request"] = false
+  socket_stream.write(request)
+ 
+  checkpoints["request"] = true
+
+  # read response
+  checkpoints["response"] = false
+  response = ''
+
+  timeout(options["timeout"]) do
+    while true
+      new_data = nil
+      begin
+        timeout(0.1) do
+	  new_data = socket_stream.gets("}") # read up to closing brace at a time
+        end
+      rescue Timeout::Error
+        # nothing
+      end
+
+      unless new_data.nil?
+        response = response + new_data
+      end
+
+      begin
+        # successfully parse, or go back and try again
+        JSON.parse(response)
+        break
+      rescue
+        # nothing
+      end
+    end
+  end
+  checkpoints["response"] = true
+  checkpoints["response_length"] = response.length
+
+rescue Timeout::Error
+  print_result_and_exit(false, "Timed out waiting for response", checkpoints)
+rescue Exception => e
+  print_result_and_exit(false, "Error while waiting for response: #{e.inspect()}", checkpoints)
+ensure
+  socket_stream.close
+end
+
+resp = JSON.parse(response)
+
+# check callUID
+checkpoints["callUIDMatch"] = false
+if options["callUID"] != resp["callUID"]
+  print_result_and_exit(false, "Expected callUID=#{options["callUID"]} but got callUID=#{resp["callUID"]}", checkpoints, resp)
+end
+checkpoints["callUIDMatch"] = true
+
+print_result_and_exit(true, "all bridge options completed successfully", checkpoints, resp)