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 fs = require('fs');
var cp = require('child_process');
var portscanner = require('portscanner');

// int. libs
var chromedriver = require('./lib/chromedriver');

/**
 * This module is a browser plugin for [DalekJS](//github.com/dalekjs/dalek).
 * It provides all a WebDriverServer & browser launcher for Google Chrome.
 *
 * The browser plugin can be installed with the following command:
 *
 * ```bash
 * $ npm install dalek-browser-chrome --save-dev
 * ```
 *
 * You can use the browser plugin by adding a config option to the your [Dalekfile](/pages/config.html)
 *
 * ```javascript
 * "browser": ["chrome"]
 * ```
 *
 * Or you can tell Dalek that it should test in this browser via the command line:
 *
 * ```bash
 * $ dalek mytest.js -b chrome
 * ```
 *
 * The Webdriver Server tries to open Port 9002 by default,
 * if this port is blocked, it tries to use a port between 9003 & 9092
 * You can specifiy a different port from within your [Dalekfile](/pages/config.html) like so:
 *
 * ```javascript
 * "browsers": [{
 *   "chrome": {
 *     "port": 5555 
 *   }
 * }]
 * ```
 *
 * It is also possible to specify a range of ports:
 *
 * ```javascript
 * "browsers": [{
 *   "chrome": {
 *     "portRange": [6100, 6120] 
 *   }
 * }]
 * ```
 *
 * If you would like to test Chrome Canary oder Chromium releases, you can simply apply a snd. argument,
 * which defines the browser type:
 *
 * ```bash
 * $ dalek mytest.js -b chrome:canary
 * ```
 *
 * for canary, and if you would like to use chromium, just append `:chromium`:
 *
 * ```bash
 * $ dalek mytest.js -b chrome:chromium
 * ```
 *
 * This will only work if you installed your browser in the default locations,
 * if the browsers binary is located in a non default location, you are able to specify
 * its location in your [Dalekfile](/pages/config.html):
 *
 * ```javascript
 * "browsers": [{
 *   "chrome": {
 *     "binary": "/Applications/Custom Located Chrome.app/MacOS/Contents/Chrome" 
 *   }
 * }]
 * ```
 *
 * This also works for the canary & chromium builds
 *
 * ```javascript
 * "browsers": [{
 *   "chrome": {
 *     "binary": "/Applications/Custom Located Chrome.app/MacOS/Contents/Chrome" 
 *   }
 * }]
 * ```
 *
 * @module DalekJS
 * @class ChromeDriver
 * @namespace Browser
 * @part Chrome
 * @api
 */

var ChromeDriver = {

  /**
   * Verbose version of the browser name
   *
   * @property longName
   * @type string
   * @default Google Chrome
   */

  longName: 'Google Chrome',

  /**
   * Default port of the ChromeWebDriverServer
   * 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 9002
   */

  port: 9002,

  /**
   * Default maximum port of the ChromeWebDriverServer
   * The port is the highest port in the range that can be allocated
   * by the ChromeWebDriverServer
   *
   * @property maxPort
   * @type integer
   * @default 9092
   */

  maxPort: 9092,

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

  host: 'localhost',

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

  desiredCapabilities: {
    browserName: 'chrome',
    chromeOptions: {}
  },

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

  driverDefaults: {
    viewport: true,
    status: true,
    sessionInfo: true
  },

  /**
   * Root path of the ChromeWebDriverServer
   *
   * @property path
   * @type string
   * @default /wd/hub
   */

  path: '/wd/hub',

  /**
   * Child process instance of the Chrome browser
   *
   * @property spawned
   * @type null|Object
   * @default null
   */

  spawned: null,

  /**
   * Chrome processes that are running on startup,
   * and therefor shouldn`t be closed
   *
   * @property openProcesses
   * @type array
   * @default []   
   */

  openProcesses: [],

  /**
   * Name of the process (platform dependent)
   * that represents the browser itself
   *
   * @property processName
   * @type string
   * @default chrome.exe / Chrome   
   */

  processName: (process.platform === 'win32' ? 'chrome.exe' : 'Chrome'),

  /**
   * Different browser types (Canary / Chromium) that can be controlled
   * via the Chromedriver
   *
   * @property browserTypes
   * @type object
   */

  browserTypes: {

    /**
     * Chrome Canary
     *
     * @property canary
     * @type object
     */

    canary: {
      name: 'Chrome Canary',
      linux: 'google-chrome-canary',
      darwin: '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
      win32: process.env.LOCALAPPDATA + '\\Google\\Chrome SxS\\Application\\chrome.exe'
    },

    /**
     * Chromium
     *
     * @property chromium
     * @type object
     */

    chromium: {
      name: 'Chromium',
      process: (process.platform === 'win32' ? 'chromium.exe' : 'Chromium'),
      linux: 'chromium-browser',
      darwin: '/Applications/Chromium.app/Contents/MacOS/Chromium',
      win32: process.env.LOCALAPPDATA + '\\Google\\Chrome SxS\\Application\\chrome.exe'
    }
  },

  /**
   * 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;
  },

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

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

  /**
   * Launches the ChromeWebDriverServer
   * (which implicitly launches Chrome itself)
   * and checks for an available port
   *
   * @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 for a user set port
    var browsers = this.config.get('browsers');
    if (browsers && Array.isArray(browsers)) {
      browsers.forEach(this._checkUserDefinedPorts.bind(this));
    }

    if (configuration) {
      if (configuration.chromeOptions) {
        this.desiredCapabilities.chromeOptions = configuration.chromeOptions;
      }

      // check for a user defined binary
      if (configuration.binary) {
        var binaryExists = this._checkUserDefinedBinary(configuration.binary);
        if (binaryExists) {
          // check for new verbose & process name
          this.longName = this._modifyVerboseBrowserName(configuration);
          this.processName = this._fetchProcessName(configuration);
        }
      }
    }

    // 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 ChromeWebDriverServer
   * & Chrome browser processes
   *
   * @method kill
   * @chainable
   */

  kill: function () {
    this._processes(process.platform, this._checkProcesses.bind(this));
    return this;
  },

  /**
   * Modifies the verbose browser name
   *
   * @method _modifyVerboseBrowserName
   * @param {object} configuration User configuration
   * @return {string} Verbose browser name
   * @private
   */

  _modifyVerboseBrowserName: function (configuration) {
    if (configuration.type && this.browserTypes[configuration.type]) {
      return this.browserTypes[configuration.type].name + ' (' + this.longName + ')';
    }

    return this.longName;
  },

  /**
   * Change the process name for browser instances like Canary & Chromium
   *
   * @method _fetchProcessName
   * @param {object} configuration User configuration
   * @return {string} Verbose browser name
   * @private
   */

  _fetchProcessName: function (configuration) {
    // check if the process name must be overridden (to shut down the browser)
    if (this.browserTypes[configuration.type] && this.browserTypes[configuration.type].process) {
      return this.browserTypes[configuration.type].process;
    }

    return this.processName;
  },

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

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

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

    return this;
  },

  /**
   * Checks if the binary exists,
   * when set manually by the user
   *
   * @method _checkUserDefinedBinary
   * @param {string} binary Path to the browser binary
   * @return {bool} Binary exists
   * @private
   */

  _checkUserDefinedBinary: function (binary) {
    // check if we need to replace the users home directory
    if (process.platform === 'darwin' && binary.trim()[0] === '~') {
      binary = binary.replace('~', process.env.HOME);
    }
    
    // check if the binary exists
    if (!fs.existsSync(binary)) {
      this.reporterEvents.emit('error', 'dalek-driver-chrome: Binary not found: ' + binary);
      process.exit(127);
      return false;
    }

    // add the binary to the desired capabilities
    this.desiredCapabilities.chromeOptions.binary = binary;

    return true;
  },

  /**
   * Checks if the def. port is blocked & if we need to switch to another port
   * Kicks off the process manager (for closing the opened browsers after the run has been finished)
   * Also starts the chromedriver instance 
   *
   * @method _checkPorts
   * @param {object} deferred Promise
   * @param {null|object} error Error object
   * @param {integer} port Found open port
   * @private
   * @chainable
   */

  _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-chrome: Switching to port: ' + port);
      this.port = port;
    }

    // get the currently running processes & invoke the chromedriver afterwards
    this._processes(process.platform, this._startChromedriver.bind(this, deferred));
    return this;
  },

  /**
   * Spawns an instance of Chromedriver
   * 
   * @method _startChromedriver
   * @param {object} deferred Promise
   * @param {null|object} error Error object
   * @param {string} result List of open chrome processes BEFORE the test browser has been launched
   * @private
   * @chainable
   */

  _startChromedriver: function (deferred, err, result) {
    var args = ['--port=' + this.getPort(), '--url-base=' + this.path];
    this.spawned = cp.spawn(chromedriver.path, args);
    this.openProcesses = result;
    this.spawned.stdout.on('data', this._catchDriverLogs.bind(this, deferred));
    return this;
  },

  /**
   * Watches the chromedriver console output to capture the starting message
   * 
   * @method _catchDriverLogs
   * @param {object} deferred Promise
   * @param {buffer} data Chromedriver console output
   * @private
   * @chainable
   */

  _catchDriverLogs: function (deferred, data) {
    var dataStr = data + '';
    var timeout = null;

    // timeout to catch if chromedriver couldnt be launched
    if (dataStr.search('DVFreeThread') === -1) {
      timeout = setTimeout(function () {
        deferred.reject();
        this.reporterEvents.emit('error', 'Chromedriver: ' + dataStr.trim());
        this.reporterEvents.emit('error', 'dalek-driver-chrome: Could not launch Chromedriver');
        process.exit(127);
      }.bind(this), 2000);
    }

    // look for the success message
    if (dataStr.search('Starting ChromeDriver') !== -1) {
      this.reporterEvents.emit('report:log:system', 'dalek-browser-chrome: Started ChromeDriver');
      if (timeout !== null) {
        clearTimeout(timeout);
      }
      deferred.resolve();
    }

    return this;
  },

  /**
   * Remove the chromedriver log that is written to the current working directory
   * 
   * @method _unlinkChromedriverLog
   * @param {bool} retry Delete has been tried min 1 time before
   * @private
   * @chainable
   */

  _unlinkChromedriverLog: function (retry) {
    var logfile = process.cwd() + '/chromedriver.log';
    try {
      if (fs.existsSync(logfile)) {
        fs.unlinkSync(logfile);
      }
    } catch (e) {
      if (!retry) {
        setTimeout(this._unlinkChromedriverLog.bind(this, true), 1000);
      }
    }
    
    return this;
  },

  /**
   * Tracks running browser processes for chrome on mac & linux
   *
   * @method _processes
   * @param {string} platform Current OS
   * @param {function} fn Callback
   * @chainable
   * @private
   */

  _processes: function (platform, fn) {
    if (platform === 'win32') {
      this._processesWin(fn);
      return this;
    }
    
    this._processesNix(fn);
    return this;
  },

  /**
   * Kills all associated processes
   * 
   * @method _checkProcesses
   * @param {object|null} err Error object or null
   * @param {array} result List of running processes
   * @chainable
   * @private
   */

  _checkProcesses: function (err, result) {
    // log that the driver shutdown process has been initiated
    this.reporterEvents.emit('report:log:system', 'dalek-browser-chrome: Shutting down ChromeDriver');
    // kill leftover chrome browser processes
    result.forEach(this[(process.platform === 'win32' ? '_killWindows' : '_killNix')].bind(this));
    // kill chromedriver binary      
    this.spawned.kill('SIGTERM');
    // clean up the file mess the chromedriver leaves us behind
    this._unlinkChromedriverLog();
    return this;
  },

  // UNIX ONLY
  // ---------

  /**
   * Kills a process
   * 
   * @method _killNix
   * @param {integer} processID Process ID
   * @chainable
   * @private
   */

  _killNix: function (processID) {
    var kill = true;
    this.openProcesses.forEach(function (pid) {
      if (pid === processID) {
        kill = false;
      }
    });

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

    return this;
  },

  /**
   * Lists all chrome processes on *NIX systems
   * 
   * @method _processesNix
   * @param {function} fn Calback
   * @chainable
   * @private
   */

  _processesNix: function (fn) {
    var processName = process.platform === 'darwin' ? this.processName : this.processName.toLowerCase();
    var cmd = ['ps -ax', '|', 'grep ' + processName];
    cp.exec(cmd.join(' '), this._processListNix.bind(this, fn));
    return this;
  },

  /**
   * Deserializes a process list on nix
   * 
   * @method _processListNix
   * @param {function} fn Calback
   * @param {object|null} err Error object
   * @param {string} stdout Output of the process list shell command
   * @chainable
   * @private
   */

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

  /**
   * Reformats the process list output on *NIX systems
   * 
   * @method _splitProcessListNix
   * @param {array} result Reference to the process list
   * @param {string} line Single process in text representation
   * @chainable
   * @private
   */

  _splitProcessListNix: function(result, line) {
    var data = line.split(' ');
    data = data.filter(this._filterProcessItemsNix.bind(this));
    result.push(data[0]);
    return this;
  },

  /**
   * Filters empty process list entries on *NIX
   * 
   * @method _filterProcessItemsNix
   * @param {string} item Item to check
   * @return {string|bool} Item or falsy
   * @private
   */

  _filterProcessItemsNix: function (item) {
    if (item !== '') {
      return item;
    }
    return false;
  },

  // WIN ONLY
  // --------

  /**
   * Lists all running processes (win only)
   *
   * @method _processesWin
   * @param {Function} callback Receives the process object as the only callback argument
   * @chainable
   * @private
   */

  _processesWin: function (callback) {
    cp.exec('tasklist /FO CSV', this._processListWin.bind(this, callback));
    return this;
  },

  /**
   * Deserializes the process list on win
   * 
   * @method _processListWin
   * @param {function} callback Callback to be executed after the list has been transformed
   * @param {object|null} err Error if error, else null
   * @param {string} stdout Output of the process list command
   * @chainable
   * @private
   */

  _processListWin: function (callback, err, stdout) {
    var p = [];
    stdout.split('\r\n').forEach(this._splitProcessListWin.bind(this, p));
    var proc = [];
    var head = null;
    while (p.length > 1) {
      var rec = p.shift();
      rec = rec.replace(/\"\,/gi,'";').replace(/\"|\'/gi,'').split(';');
      if (head === null){
        head = rec;
        for (var i=0;i<head.length;i++){
          head[i] = head[i].replace(/ /gi,'');
        }
      } else {
        var tmp = {};
        for (var j=0;j<rec.length;j++){
          tmp[head[j]] = rec[j].replace(/\"|\'/gi,'');
        }
        proc.push(tmp);
      }
    }

    var result = [];
    proc.forEach(this._filterProcessItemsWin.bind(this, result));
    callback(null, result);
    return this;
  },

  /**
   * Processes (transforms) the list of processes
   * 
   * @method _filterProcessItemsWin
   * @param {array} result Reference to the result process list
   * @param {object} process Single piece of process information
   * @chainable
   * @private
   */

  _filterProcessItemsWin: function (result, process) {
    Object.keys(process).forEach(function (key) {
      if (process[key] === this.processName) {
        result.push(process.PID);
      }
    }.bind(this));
    return this;
  },

  /**
   * Filters empty lines out of the process result
   * 
   * @method _splitProcessListWin
   * @param {array} p Reference to the process list
   * @param {string} line Process item
   * @chainable
   * @private
   */

  _splitProcessListWin: function (p, line) {
    if (line.trim().length !== 0) {
      p.push(line);
    }
    return this;
  },

  /**
   * Kills a process (based on a PID)
   * that was not opened BEFORE Dalek has
   * been started
   *
   * @method _killWindows
   * @param {integer} pid Process id
   * @chainable
   * @private
   */

  _killWindows: function (pid) {
    var kill = true;

    // check if the process was running BEFORE we started dalek
    this.openProcesses.forEach(function (opid) {
      if (opid === pid) {
        kill = false;
      }
    });

    // kill the browser process
    if (kill === true) {
      cp.exec('taskkill /PID ' + pid + ' /f', function(){});
    }

    return this;
  }

};

// expose the module
module.exports = ChromeDriver;