/*!
*
* 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 path = require('path');
var rimraf = require('rimraf');
var which = require('which').sync;
var portscanner = require('portscanner');
var spawn = require('child_process').spawn;
var Events = require('events').EventEmitter;
// int. libs
var Marionette = require('./lib/marionette');
var WebDriverServer = require('./lib/webdriver');
/**
* This module is a browser plugin for [DalekJS](//github.com/dalekjs/dalek).
* It provides all a WebDriverServer & browser launcher for Mozilla Firefox & Firefox OS.
*
* The browser plugin can be installed with the following command:
*
* ```bash
* $ npm install dalek-browser-firefox --save-dev
* ```
*
* You can use the browser plugin by adding a config option to the your Dalekfile
*
* ```javascript
* "browser": ["firefox"]
* ```
*
* Or you can tell Dalek that it should test in this browser via the command line:
*
* ```bash
* $ dalek mytest.js -b firefox
* ```
*
* Dalek looks for the browser in the std. installation directory, if you installed the
* browser in a different place, you can add the location of the browser executable to you Dalekfile,
* because Dalek isnʼt capable of finding the executable yet on its own.
*
* ```javascript
* "browsers": [{
* "firefox": {
* "path": "~/Apps/FirefoxNightlyDebug.app/Contents/MacOS/firefox-bin"
* }
* }]
* ```
*
* The Firefox plugin only implements a subset of Dalekʼs assertions & actions,
* so if you run into any bugs, the issue is most probably related to missing commands.
* Please report any issues you find, Thank you :)
*
* The Webdriver Server tries to open Port 9006 by default,
* if this port is blocked, it tries to use a port between 9007 & 9096
* You can specifiy a different port from within your [Dalekfile](/pages/config.html) like so:
*
* ```javascript
* "browsers": [{
* "firefox": {
* "port": 5555
* }
* }]
* ```
*
* It is also possible to specify a range of ports:
*
* ```javascript
* "browsers": [{
* "firefox": {
* "portRange": [6100, 6120]
* }
* }]
* ```
*
* If you would like to test Nightly, Aurora oder Firefox OS releases, you can simply apply a snd. argument,
* which defines the browser type:
*
* ```bash
* $ dalek mytest.js -b firefox:aurora
* ```
*
* for Firefox Aurora, and if you would like to use the Firefox OS, just append `:os`:
*
* ```bash
* $ dalek mytest.js -b firefox:os
* ```
*
* 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": [{
* "firefox": {
* "binary": "/Applications/Custom Located Firefox.app/MacOS/Contents/firefox-bin"
* }
* }]
* ```
*
* This also works for the aurora & Firefox OS builds
*
* ```javascript
* "browsers": [{
* "firefox:aurora": {
* "binary": "/Applications/Custom Located Firefox Aurora.app/MacOS/Contents/firefox-bin"
* }
* }]
* ```
*
* @module DalekJS
* @class FirefoxDriver
* @namespace Browser
* @part Firefox
* @api
*/
var FirefoxDriver = {
/**
* Verbose version of the browser name
*
* @property longName
* @type string
* @default Mozilla Firefox
*/
longName: 'Mozilla Firefox',
/**
* Default port of the FirefoxWebDriverServer
* 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 9006
*/
port: 9006,
/**
* Default maximum port of the WebDriverServer
* The port is the highest port in the range that can be allocated
* by the WebDriverServer
*
* @property maxPort
* @type integer
* @default 9096
*/
maxPort: 9096,
/**
* Default port of the Marionette TCP service
* The port may change, cause the port conflict resolution
* tool might pick another one, if the default one is blocked
*
* @property marionettePort
* @type integer
* @default 2828
*/
marionettePort: 2828,
/**
* Default host of the FirefoxWebDriverServer
* 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: 'firefox'
},
/**
* 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 FirefoxWebDriverServer
*
* @property path
* @type string
* @default ''
*/
path: '',
/**
* Path to the Firefox binary file
*
* @property binary
* @type string
* @default null
*/
binary: null,
/**
* Paths to the default Firefox binary files
*
* @property defaultBinaries
* @type object
*/
defaultBinaries: {
default: 'firefox',
darwin: '/Applications/Firefox.app/Contents/MacOS/firefox-bin',
win32: process.env.ProgramFiles + '\\Mozilla Firefox\\firefox.exe',
win64: process.env['ProgramFiles(x86)'] + '\\Mozilla Firefox\\firefox.exe'
},
/**
* Different browser types (Aurora / firefox OS) that can be controlled
* via the Firefox driver
*
* @property browserTypes
* @type object
*/
browserTypes: {
/**
* Nightly Firefox
*
* @property nightly
* @type object
*/
nightly: {
name: 'Firefox Nightly',
linux: 'firefox',
darwin: '/Applications/FirefoxNightlyDebug.app/Contents/MacOS/firefox-bin',
win32: process.env.ProgramFiles + '\\Nightly\\firefox.exe',
win64: process.env['ProgramFiles(x86)'] + '\\Mozilla Firefox Nightly\\firefox.exe'
},
/**
* Firefox Aurora
*
* @property aurora
* @type object
*/
aurora: {
name: 'Firefox Aurora',
linux: 'firefox',
darwin: '/Applications/FirefoxAuroraDebug.app/Contents/MacOS/firefox-bin',
win32: process.env.ProgramFiles + '\\AuroraDebug\\firefox.exe',
win64: process.env['ProgramFiles(x86)'] + '\\Mozilla AuroraDebug\\firefox.exe'
},
/**
* Firefox OS
*
* @property os
* @type object
*/
os: {
name: 'Firefox OS',
linux: 'b2g',
darwin: '/Applications/B2G.app/Contents/MacOS/b2g',
win32: process.env.ProgramFiles + '\\B2G\\b2g.exe',
win64: process.env.ProgramFiles + '\\B2G\\b2g.exe'
}
},
/**
* Child process instance of the Firefox browser
*
* @property spawned
* @type null|Object
* @default null
*/
spawned: null,
/**
* Collected data about the created profile,
* path, name, etc.
*
* @property profile
* @type null|object
* @default null
*/
profile: null,
/**
* 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 marionette port
*
* @method getMarionettePort
* @return {integer} port Marionette server port
*/
getMarionettePort: function () {
return this.marionettePort;
},
/**
* Returns the driver host
*
* @method getHost
* @return {string} host WebDriver server hostname
*/
getHost: function () {
return this.host;
},
/**
* Launches the FirefoxWebDriverServer,
* the marionette client, & the browser.
* Creates a user profile for the browser
*
* @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();
// init the webdriver server,
// marionette client, event glue
// and configuration settings
configuration = this._initialize({
userconfig: configuration,
reporterEvents: events,
config: config,
events: new Events()
});
// check for a user set port
var browsers = this.config.get('browsers');
if (browsers && Array.isArray(browsers)) {
browsers.forEach(this._checkUserDefinedPorts.bind(this));
}
// check the path of the browser binary
Q.when(this.findBrowserBinary(configuration))
.then(this._afterBinaryFound.bind(this, configuration, deferred));
return deferred.promise;
},
/**
* Shuts down the TCP (Marionette) & HTTP connection (Webdriver),
* then kills the browser process & cleans up the profiles
*
* @method kill
* @chainable
*/
kill: function () {
Q.all([
// shutdown Marionette client
this.marionette.kill(),
// shutdown webdriver server
this.webDriverServer.kill()
]).then(this._killProcess.bind(this));
return this;
},
/**
* Locates the browser binary
*
* @method findBrowserBinary
* @param {object} options Config options
* @return {object} Promise
*/
findBrowserBinary: function (options) {
var deferred = Q.defer();
// check if the user has set a custom binary
if (options && options.binary) {
this._checkUserSetBinary(options.binary, deferred);
return deferred.promise;
}
// get the defaukt binary for this OS
var defaultBinary = this._getDefaultBinary();
// check if the binary exists
if (fs.existsSync(defaultBinary)) {
this.binary = defaultBinary;
deferred.resolve(defaultBinary);
} else {
var msg = 'dalek-driver-firefox: Binary not found: ' + defaultBinary;
this.reporterEvents.emit('error', msg);
deferred.reject({error: true, msg: msg});
}
return deferred.promise;
},
/**
* Makes all needed modifications after we are sure if the
* browser binary has been found
*
* @method _afterBinaryFound
* @param {object} configuration User configuration
* @param {object} deferred Promise
* @chainable
* @private
*/
_afterBinaryFound: function (configuration, deferred) {
// generate the verbose browser name
this.longName = this._modifyVerboseBrowserName(configuration);
// check if we are driving a desktop browser
// when, create a profile, else, not
if (configuration.type !== 'os') {
Q.when(this._createProfile())
.then(this._afterDesktopBinaryFound.bind(this, deferred, configuration));
} else {
this._startBrowser(null, 'os', deferred);
}
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 + ')';
} else {
return this.longName;
}
},
/**
* Initiates the browser startup after the desktop binary has been found
*
* @method _afterDesktopBinaryFound
* @param {object} deferred Promise
* @param {object} profile Profile data
* @chainable
* @private
*/
_afterDesktopBinaryFound: function (deferred, configuration) {
this._startBrowser(this.profile.path, this.profile.name, deferred, configuration);
return this;
},
/**
* Kills the currently running browser process
*
* @method _killProcess
* @chainable
* @priavte
*/
_killProcess: function () {
// kill the browser process itself
this.spawned.kill('SIGTERM');
// check if we need to clean up some created profiles
// should always be the case except for Firefox OS
if (this.profile && this.profile.path) {
rimraf.sync(this.profile.path);
}
return this;
},
/**
* Initializes config & properties
*
* @method _initiaize
* @param {object} opts Config options
* @return {object} Processed userr config
* @private
*/
_initialize: function (opts) {
// store config class
this.config = opts.config;
// glue events
this.events = opts.events;
this.events.setMaxListeners(0);
this.reporterEvents = opts.reporterEvents;
// setup Marionette client & Webdriver server
this.marionette = new Marionette(this.events);
this.webDriverServer = new WebDriverServer(this.events);
return opts.userconfig === null ? {} : opts.userconfig;
},
/**
* Get the default binary location
*
* @method _getDefaultBinary
* @return {string} Path to binary
* @private
*/
_getDefaultBinary: function () {
var platform = process.platform;
// check default binary for linuy
if (platform !== 'darwin' && platform !== 'win32' && this.defaultBinaries[platform]) {
return which(this.defaultBinaries.linux);
}
// check to see if we are on Windows x64
if (platform === 'win32' && process.arch === 'x64') {
platform = 'win64';
}
return this.defaultBinaries[platform] ?
this.defaultBinaries[platform] :
which(this.defaultBinaries.default);
},
/**
* Launches the browser
*
* @method _startBrowser
* @param {string} profilePath Directory that contains the profile
* @param {string} profileName Name of the profile to use
* @param {object} deferred Promise
* @private
* @chainable
*/
_startBrowser: function (profilePath, profileName, deferred, configuration) {
var df = Q.defer();
var args = [];
// set args based on environment
if (profileName !== 'os') {
args = ['-marionette', '-turbo', '-profile', profilePath, '-no-remote', '-url', 'about:blank'];
}
// start the browser
this.spawned = spawn(this.binary, args);
// kind of an ugly hack, but I have no other idea to
// than to wait for 2 secs to ensure Firefox runs on windows
if (process.platform === 'win32' || (configuration && !configuration.type)) {
this.interval = setInterval(this._scanMarionettePort.bind(this, df), 50);
} else {
this.spawned.stdout.on('data', this._onBrowserStartup.bind(this, df));
}
// connect to the marionette socket server
// and the webdriver server & resolve the promise when done
df.promise.then(this._resolvePort.bind(this, deferred, profileName));
return this;
},
/**
* Repeatadly checks the status of the marionette port
*
* @method _scanMarionettePort
* @param {object} df Promise
* @private
* @chainable
*/
_scanMarionettePort: function (df) {
portscanner.checkPortStatus(this.getMarionettePort(), this.getHost(), this._startByInterval.bind(this, df));
return this;
},
/**
* Checks if the browser is available by listening on the marionette socket
*
* @method _startByInterval
* @param {object} df Promise
* @param {object} interval Reference to the portchecker interval
* @param {object|null} err Error or null
* @param {string} status Status of the marionette port
* @private
* @chainable
*/
_startByInterval: function (df, err, status) {
if (status === 'open') {
clearInterval(this.interval);
df.resolve();
}
return this;
},
/**
* Process user defined ports
*
* @method _checkUserDefinedPorts
* @param {object} browser Browser configuration
* @chainable
* @private
*/
_checkUserDefinedPorts: function (browser) {
// check for a single defined port
if (browser.firefox && browser.firefox.port) {
this.port = parseInt(browser.firefox.port, 10);
this.maxPort = this.port + 90;
this.reporterEvents.emit('report:log:system', 'dalek-browser-firefox: Switching to user defined port: ' + this.port);
}
// check for a port range
if (browser.firefox && browser.firefox.portRange && browser.firefox.portRange.length === 2) {
this.port = parseInt(browser.firefox.portRange[0], 10);
this.maxPort = parseInt(browser.firefox.portRange[1], 10);
this.reporterEvents.emit('report:log:system', 'dalek-browser-firefox: Switching to user defined port(s): ' + this.port + ' -> ' + this.maxPort);
}
return this;
},
/**
* Resolve the WebDriverServer port
*
* @method _resolvePort
* @param {object} deferred Promise
* @param {string} profileName Name of the profile
* @chainable
* @private
*/
_resolvePort: function (deferred, profileName) {
// check if the current port is in use, if so, scan for free ports
portscanner.findAPortNotInUse(
this.getPort(),
this.getMaxPort(),
this.getHost(),
this._afterPortResolved.bind(this, deferred, profileName)
);
return this;
},
/**
* Resolve the WebDriverServer port
*
* @method _resolvePort
* @param {object} deferred Promise
* @param {string} profileName Name of the profile
* @param {object|null} error Error object if there is one
* @param {integer} port Resolved port
* @chainable
* @private
*/
_afterPortResolved: function (deferred, profileName, error, port) {
// check for errors
if (error !== null && error.code !== 'ECONNREFUSED') {
this.reporterEvents.emit('error', 'dalek-browser-firefox: Error starting WebDriverServer, port ' + port + ' in use');
deferred.reject(error);
process.exit();
}
// 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-firefox: Switching to port: ' + port);
this.port = port;
}
// kickstart marionette client & webdriver server
Q.all([
this.webDriverServer.connect(this.getPort(), this.getHost()),
this.marionette.connect(this.getMarionettePort())
]).then(this._afterConnectionHasBeenEstablished.bind(this, profileName, deferred));
return this;
},
/**
* Callback that will be invoked after the marionette client has
* established a connection to the browser & after the webdriver server
* has been launched correctly
*
* @method _afterConnectionHasBeenEstablished
* @param {string} profileName Name of the user profile
* @param {object} deferred Promise
* @chainable
* @private
*/
_afterConnectionHasBeenEstablished: function (profileName, deferred) {
// Due to the lack of firefox os readiness events,
// we need to wait an additional second before reporting
// test readiness
if (profileName === 'os') {
setTimeout(deferred.resolve, 1000);
} else {
deferred.resolve();
}
return this;
},
/**
* Consumes the console output when the browser is started
*
* @method _onBrowserStartup
* @param {object} deferred Promise
* @param {string} data Output from the spawned binary
* @private
* @chainable
*/
_onBrowserStartup: function (deferred, data) {
if (this._browserIsReady(data)) {
deferred.resolve();
}
return this;
},
/**
* Checks if the browser is ready for communication
*
* @method _browserIsReady
* @param {string} data Output from the spawned binary
* @return {bool} true when ready, false when not
* @private
*/
_browserIsReady: function (data) {
// convert buffer to string
data = data+'';
// check for the ready signal on desktop firefox
var desktopReady = data.search('DOMWINDOW == 12') !== -1;
// check for the ready signal of the firefoxos emulator
var b2gReady = data.search('BrowserElementChildPreload.js loaded') !== -1;
return desktopReady || b2gReady;
},
/**
* Creates a new Firefox profile
*
* @method _createProfile
* @return {Q.promise}
* @private
*/
_createProfile: function () {
var deferred = Q.defer();
var profileName = 'dalekjs-' + Math.random().toString(16).slice(2);
this._createUserPreferences(deferred, profileName);
return deferred.promise;
},
/**
* Creates user preferences for the profile
* Saves them in `user.js` in the newly created profile
*
* @method _createProfile
* @param {string} profilePath User profile directory
* @return {Q.promise}
* @private
*/
_createUserPreferences: function (deferred, profileName) {
// create marionette specific user preferences
var prefs = 'user_pref("browser.shell.checkDefaultBrowser", false);\n';
prefs += 'user_pref("marionette.contentListener", false);\n';
prefs += 'user_pref("marionette.defaultPrefs.enabled", true);\n';
prefs += 'user_pref("browser.shell.checkDefaultBrowser", false);\n';
prefs += 'user_pref("browser.sessionstore.resume_from_crash", false);\n';
prefs += 'user_pref("browser.bookmarks.restore_default_bookmarks", false);\n';
prefs += 'user_pref("marionette.defaultPrefs.port", "' + this.getMarionettePort() + '");\n';
// store the user preferences
this.profile = {};
this.profile.path = path.join(process.cwd(), 'temp');
this.profile.name = profileName;
// check if the temp dir exists, else create
if (!fs.existsSync(this.profile.path)) {
fs.mkdirSync(this.profile.path);
}
// create the preference file
fs.writeFile(path.join(this.profile.path, 'prefs.js'), prefs, this._afterCreatingUserPreferences.bind(this, deferred));
return deferred.promise;
},
/**
* Callback that will be executed after the user preferences
* have been created
*
* @method _afterCreatingUserPreferences
* @param {object} deferred Promise
* @param {object|null} err Error or null
* @private
* @chainable
*/
_afterCreatingUserPreferences: function (deferred, err) {
// reject the deferred when an error occurrs
if (err !== null) {
this.reporterEvents.emit('error', 'dalek-browser-firefox: Error creating profile');
deferred.reject(err);
process.exit();
}
deferred.resolve();
return this;
},
/**
* Checks if the binary exists,
* when set manually by the user
*
* @method _checkUserSetBinary
* @param {string} userPath Path to the browser binary
* @param {object} deferred Promise
* @private
* @chainable
*/
_checkUserSetBinary: function (userPath, deferred) {
// check if we need to replace the users home directory
if (process.platform === 'darwin' && userPath.trim()[0] === '~') {
userPath = userPath.replace('~', process.env.HOME);
}
// check if the binary exists
if (fs.existsSync(userPath)) {
this.binary = userPath;
deferred.resolve(userPath);
} else {
var msg = 'dalek-driver-firefox: Binary not found: ' + userPath;
this.reporterEvents.emit('error', msg);
process.exit(); // MAYBE switch to Daleks 'killAll' Event
deferred.reject({error: true, msg: msg});
}
return this;
}
};
module.exports = FirefoxDriver;
