index.js

/*!
 *
 * Copyright (c) 2013 Sebastian Golasch
 *
 * 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.
 *
 */

'use strict';

// ext. libs
var Q = require('q');
var os = require('os');
var cp = require('child_process');
var appium = require('appium/lib/server/main');
var portscanner = require('portscanner');

/**
 * This module is a browser plugin for [DalekJS](//github.com/dalekjs/dalek).
 * It provides all a WebDriverServer & browser launcher for Safari on iOS.
 * 
 * At the moment this only works with the IPhone 
 *
 * The browser plugin can be installed with the following command:
 *
 * ```bash
 * $ npm install dalek-browser-ios --save-dev
 * ```
 *
 * You can use the browser plugin by adding a config option to the your Dalekfile
 *
 * ```javascript
 * "browsers": ["ios"]
 * ```
 *
 * Or you can tell Dalek that it should test in this browser via the command line:
 *
 * ```bash
 * $ dalek mytest.js -b ios
 * ```
 *
 * The Webdriver Server tries to open Port 9003 by default,
 * if this port is blocked, it tries to use a port between 9004 & 9093
 * You can specifiy a different port from within your [Dalekfile](/pages/config.html) like so:
 *
 * ```javascript
 * "browsers": {
 *   "ios": {
 *     "port": 5555 
 *   }
 * }
 * ```
 *
 * It is also possible to specify a range of ports:
 *
 * ```javascript
 * "browsers": {
 *   "ios": {
 *     "portRange": [6100, 6120] 
 *   }
 * }
 * ```
 *
 * If you would like to test on the IPad (IPhone) emulator, you can simply apply a snd. argument,
 * which defines the browser type:
 *
 * ```bash
 * $ dalek mytest.js -b ios:ipad
 * ```
 * 
 * @module DalekJS
 * @class IosDriver
 * @namespace Browser
 * @part iOS
 * @api
 */

var IosDriver = {

  /**
   * Verbose version of the browser name
   *
   * @property longName
   * @type string
   * @default Mobile Safari iOS
   */

  longName: 'Mobile Safari iOS (iPhone)',

  /**
   * Default port of the Appium WebDriverServer
   * The port may change, cause the port conflict resolution
   * tool might pick another one, if the default one is blocked
   *
   * @property port
   * @type integer
   * @default 4723
   */

  port: 4723,

  /**
   * WebHook port
   *
   * @property webhookPort
   * @type integer
   * @default 9003
   */

  webhookPort: 9003,

  /**
   * Default host of the Appium WebDriverServer
   * The host may be overridden with
   * a user configured value
   *
   * @property host
   * @type string
   * @default localhost
   */

  host: 'localhost',

  /**
   * Root path of the appium webdriver server
   *
   * @property path
   * @type string
   * @default /wd/hub
   */

  path: '/wd/hub',

  /**
   * Default desired capabilities that should be
   * transferred when the browser session gets requested
   *
   * @property desiredCapabilities
   * @type object
   */

  desiredCapabilities: {
    device: 'iPhone Emulator',
    name: 'Safari remote via WD',
    app: 'safari',
    version: '6.1',
    browserName: ''
  },

  /**
   * Driver defaults, what should the driver be able to access.
   *
   * @property driverDefaults
   * @type object
   */

  driverDefaults: {
    viewport: true,
    status: {
      os: {
        arch: os.arch(),
        version: os.release(),
        name: 'Mac OSX'
      }
    },
    sessionInfo: true
  },

  /**
   * Special arguments that are needed to invoke
   * appium. These are the defaults, they need to be modified later on 
   *
   * @property appiumArgs
   * @type object
   */

  appiumArgs: {
    app: null,
    ipa: null,
    quiet: true,
    udid: null,
    keepArtifacts: false,
    noSessionOverride: false,
    fullReset: false,
    noReset: false,
    launch: false,
    log: false,
    nativeInstrumentsLib: false,
    safari: false,
    forceIphone: false,
    forceIpad: false,
    orientation: null,
    useKeystore: false,
    address: '0.0.0.0',
    nodeconfig: null,
    port: null,
    webhook: null
  },

  /**
   * Different browser types (iPhone / iPad)
   *
   * @property browserTypes
   * @type object
   */

  browserTypes: {

    /**
     * IPad emulator
     *
     * @property ipad
     * @type object
     */

    ipad: {
      name: 'iPad'
    }

  },

  /**
   * Resolves the driver port
   *
   * @method getPort
   * @return {integer} port WebDriver server port
   */

  getPort: function () {
    return this.port;
  },

  /**
   * Resolves the maximum range for the driver port
   *
   * @method getMaxPort
   * @return {integer} port Max WebDriver server port range
   */

  getMaxPort: function () {
    return this.maxPort;
  },

  /**
   * Resolves the webhook port
   *
   * @method getWebhookPort
   * @return {integer} WebHook server port
   */

  getWebhookPort: function () {
    return this.webhookPort;
  },

  /**
   * Resolves the maximum range for the webhook port
   *
   * @method getWebhookPort
   * @return {integer} WebHook Max WebHook port
   */

  getMaxWebhookPort: function () {
    return this.maxWebhookPort;
  },

  /**
   * Returns the driver host
   *
   * @method getHost
   * @return {string} host WebDriver server hostname
   */

  getHost: function () {
    return this.host;
  },

  /**
   * Launches appium & corresponding emulator or device,
   * kicks off the portscanner
   *
   * @method launch
   * @param {object} configuration Browser configuration
   * @param {EventEmitter2} events EventEmitter (Reporter Emitter instance)
   * @param {Dalek.Internal.Config} config Dalek configuration class
   * @return {object} promise Browser promise
   */

  launch: function (configuration, events, config) {
    var deferred = Q.defer();

    // store injected configuration/log event handlers
    this.reporterEvents = events;
    this.configuration = configuration;
    this.config = config;

    // check if the user wants to run the iPad emulator
    if (configuration && configuration.type === 'ipad') {
      this.longName = this.longName.replace('iPhone', 'iPad');
      this.appiumArgs.forceIpad = true;
    }

    // check for a user set port
    var browsers = this.config.get('browsers');
    if (browsers && Array.isArray(browsers)) {
      browsers.forEach(this._checkUserDefinedPorts.bind(this));
    }

    // check if the current port is in use, if so, scan for free ports
    portscanner.findAPortNotInUse(this.getPort(), this.getMaxPort(), this.getHost(), this._checkPorts.bind(this, deferred));
    return deferred.promise;
  },

  /**
   * Kills the Appium Server process,
   * kills simulator processses
   * with a slight timeout to prevent 
   * appium from throwing errors
   * 
   * @method kill
   * @chainable
   */

  kill: function () {
    // kill appium servers
    this.appiumServer.webSocket.server.close();
    this.appiumServer.rest.listen().close();
    // slight timeout for process killing
    setTimeout(this._processes.bind(this, this._kill.bind(this)), 1000);
    return this;
  },

  /**
   * Kills the non blacklisted simulator processes & restores
   * the stderr handler
   *
   * @method _kill
   * @param {object|null} err Error or null
   * @param {array} result List of currently running simulator processes
   * @chainable
   * @private
   */

  _kill: function (err, result) {
    // kill simulator processes
    result.forEach(this._killProcess.bind(this));
    // (re)establish stderr/stdout stream
    this._reinstantiateLog();
    return this;
  },

  /**
   * Checks a blacklist & kills the process when
   * not found
   *
   * @method _killProcess
   * @param {integer} processID Process ID
   * @chainable
   * @private
   */

  _killProcess: function (processID) {
    var kill = true;

    // walk through the list of processes that are
    // open before the driver started
    this.openProcesses.forEach(function (pid) {
      if (pid === processID) {
        kill = false;
      }
    });

    if (kill === true) {
      cp.spawn('kill', [processID]);
    }

    return this;
  },

  /**
   * Checks & switches the appium server port,
   * scans the range for the webhook port
   *
   * @method _listProcesses
   * @param {object} deferred Promise
   * @param {object|null} err Error or null
   * @param {integer} port Appium server port to use
   * @chainable
   * @private
   */

  _checkPorts: function (deferred, error, port) {
    // check if the port was blocked & if we need to switch to another port
    if (this.port !== port) {
      this.reporterEvents.emit('report:log:system', 'dalek-browser-ios: Switching to port: ' + port);
      this.port = port;
    }

    // check if the current webhook port is in use, if so, scan for free ports
    portscanner.findAPortNotInUse(this.getWebhookPort(), this.getMaxWebhookPort(), this.getHost(), this._launch.bind(this, deferred));
    return this;
  },

  /**
   * Checks & switches the webhook port,
   * loads a list of running simulator processes
   *
   * @method _listProcesses
   * @param {object} deferred Promise
   * @param {object|null} err Error or null
   * @param {integer} port Webhook port to use
   * @chainable
   * @private
   */

  _launch: function (deferred, error, port) {
    // check if the port was blocked & if we need to switch to another port
    if (this.webhookPort !== port) {
      this.reporterEvents.emit('report:log:system', 'dalek-browser-ios: Switching to webhook port: ' + port);
      this.webhookPort = port;
    }

    // launch appium & the emulator
    this._processes(this._listProcesses.bind(this, deferred));
    return this;
  },

  /**
   * Stores open processes,
   * suppresses stdout logs,
   * starts appium
   *
   * @method _listProcesses
   * @param {object} deferred Promise
   * @param {object|null} err Error or null
   * @param {array} result List of currently running simulator processes
   * @chainable
   * @private
   */

  _listProcesses: function (deferred, err, result) {
    // save list of open emulator processes, before we launched it
    this.openProcesses = result;
    // nasty hack to surpress socket.io debug reports from appium
    this._suppressAppiumLogs();
    // run appium
    appium.run(this._loadAppiumArgs(this.appiumArgs), this._afterAppiumStarted.bind(this, deferred));
    return this;
  },

  /**
   * Stores the appium server reference,
   * restores the stdout logs
   *
   * @method _afterAppiumStarted
   * @param {object} deferred Promise
   * @param {object} appiumServer Appium server instance
   * @chainable
   * @private
   */

  _afterAppiumStarted: function (deferred, appiumServer) {
    this.appiumServer = appiumServer;
    deferred.resolve();
    return this;
  },

  /**
   * Configures appium
   *
   * @method _loadAppiumArgs
   * @param {object} appiumArgs Appium specific configuration
   * @return {object} Modified appium configuration
   * @private
   */

  _loadAppiumArgs: function (appiumArgs) {
    appiumArgs.port = this.getPort();
    appiumArgs.webhook = this.getHost() + ':' + this.getWebhookPort();
    return appiumArgs;
  },

  /**
   * Process user defined ports
   *
   * @method _checkUserDefinedPorts
   * @param {object} browser Browser configuration
   * @chainable
   * @private
   */

  _checkUserDefinedPorts: function (browser) {
    this._checkAppiumPorts(browser);
    this._checkWebhookPorts(browser);
    return this;
  },

  /**
   * Process user defined appium ports
   *
   * @method _checkAppiumPorts
   * @param {object} browser Browser configuration
   * @chainable
   * @private
   */

  _checkAppiumPorts: function (browser) {
    // check for a single defined port
    if (browser.ios && browser.ios.port) {
      this.port = parseInt(browser.ios.port, 10);
      this.maxPort = this.port + 90;
      this.reporterEvents.emit('report:log:system', 'dalek-browser-ios: Switching to user defined port: ' + this.port);
    }

    // check for a port range
    if (browser.ios && browser.ios.portRange && browser.ios.portRange.length === 2) {
      this.port = parseInt(browser.ios.portRange[0], 10);
      this.maxPort = parseInt(browser.ios.portRange[1], 10);
      this.reporterEvents.emit('report:log:system', 'dalek-browser-ios: Switching to user defined port(s): ' + this.port + ' -> ' + this.maxPort);
    }

    return this;
  },

  /**
   * Process user defined webhook ports
   *
   * @method _checkWebhookPorts
   * @param {object} browser Browser configuration
   * @chainable
   * @private
   */

  _checkWebhookPorts: function (browser) {
    // check for a single defined webhook port
    if (browser.ios && browser.ios.webhookPort) {
      this.webhookPort = parseInt(browser.ios.webhookPort, 10);
      this.maxWebhookPort = this.webhookPort + 90;
      this.reporterEvents.emit('report:log:system', 'dalek-browser-ios: Switching to user defined webhook port: ' + this.webhookPort);
    }

    // check for a webhook port range
    if (browser.ios && browser.ios.webhookPortRange && browser.ios.webhookPortRange.length === 2) {
      this.webhookPort = parseInt(browser.ios.webhookPortRange[0], 10);
      this.maxWebhookPort = parseInt(browser.ios.webhookPortRange[1], 10);
      this.reporterEvents.emit('report:log:system', 'dalek-browser-ios: Switching to user defined webhook port(s): ' + this.webhookPort + ' -> ' + this.maxWebhookPort);
    }

    return this;
  },

  /**
   * Tracks running simulator processes
   *
   * @method _processes
   * @param {function} fn Callback
   * @chainable
   * @private
   */

  _processes: function (fn) {
    var cmd = ['ps -ax', '|', 'grep "iPhone Simulator.app"'];
    cp.exec(cmd.join(' '), this._transformProcesses.bind(this, fn));
    return this;
  },

  /**
   * Transforms the process list output into
   * a json structure
   * 
   * @method _transformProcesses
   * @param {function} fn Callback
   * @param {null|object} err Error if error, null if not
   * @param {string} stdout Terminal output
   * @chainable
   * @private
   */

  _transformProcesses: function(fn, err, stdout){
    var result = [];
    stdout.split('\n').forEach(this._scanProcess.bind(this, result));
    fn(err, result);
    return this;
  },

  /**
   * Scans and transforms the process list
   *
   * @method _scanProcess
   * @param {array} result Transformed result
   * @param {string} line Process list entry
   * @chainable
   * @private
   */

  _scanProcess: function (result, line){
    var data = line.split(' ');
    data = data.filter(this._filterProcessItem);

    if (data[1] === '??') {
      result.push(data[0]);
    }

    return this;
  },

  /**
   * Filters process list items
   *
   * @method _filterProcessItem
   * @param {string} item Process list entry
   * @return {bool|string} Process item or false
   * @private
   */

  _filterProcessItem: function (item) {
    if (item !== '') {
      return item;
    }

    return false;
  },

  /**
   * Overwrite default stdout & stderr handler
   * to suppress some appium logs 
   *
   * @method _suppressAppiumLogs
   * @chainable
   * @private
   */

  _suppressAppiumLogs: function () {
    // TODO: Check if the log level of appium can be set to 0
    var _supLogs = function (data) {
      if (data.search('6minfo') === -1 && data.search('33mwarn') === -1 && data.search('90mdebug') === -1) {
        this.oldWrite.bind(process.stdout)(data);
      }
    }.bind(this);

    // store old std. handler
    this.oldWrite = process.stdout.write;
    this.oldWriteErr = process.stderr.write;

    // overwrite with ugliness
    process.stdout.write = _supLogs;
    process.stderr.write = _supLogs;
    return this;
  },

  /**
   * Reinstantiate stdout handler after appium has
   * been started
   *
   * @method _reinstantiateLog
   * @chainable
   * @private
   */

  _reinstantiateLog: function () {
    setTimeout(function () {
      process.stdout.write = this.oldWrite;
      process.stderr.write = this.oldWriteErr;
    }.bind(this), 8000);
    return this;
  }

};

// expose the module
module.exports = IosDriver;