Node Module API

API

When using it as a node module do a require(browser-perf) after installing it using npm install --save browser-perf.

Usage

var browserPerf = require('browser-perf');
browserPerf('http://url-to-test.com', function(err, res){/*callback*/}, options);

The callback function is invoked after the URL is tested on all the browsers. The callback is passed two arguments - error and results. They are both arrays, with one entry per browser that the URL was tested on. More details about the options object below.

Options

The options object is a set of key value pairs as follows

configFile

No default value

A configuration file can be used to specify all the option. This is a JSON file with all the keys and values as described in this section. Any values specified directly in the object overrides the value in the configuration file. The path of this file is relative to the current working directory.

selenium

Default: http://localhost:4444/wd/hub

The address where the selenium server is running. See setting up selenium on information on how to get started with selenium. This can be an object like described here or a URL string. Some examples of the possible values for this key are

• http://localhost:4444/wd/hub for a local installation of selenium
• http://localhost:9515/ to directly connect to a chrome driver running locally
• ondemand.saucelabs.com, ondemand.saucelabs.com/wd/hub or http://ondemand.saucelabs.com to connect to selenium running on Saucelabs
• { hostname: '127.0.0.1',port: 4444, user: 'username', pwd: 'password'} to connect to selenium that is password protected locally

username, accesskey

Default: undefined for both username and accesskey

Services like Saucelabs or Browserstack also require a username or an access key to start the testing. These can be specified using the username and accesskey keys in the options object. They are automatically added to the URL in case of Saucelabs, or to the browser capabilities object in case of Browserstack. Note that the username and access key can also be specified in the Selenium URL.

browsers

Default: [{browserName: 'chrome',version: 32}]

This can either be a string separated by commas, an array of strings, or an array of objects with the desired capabilities. Some examples are

• chrome, firefox
• ['chrome', 'firefox']
• [{browserName: 'chrome', version: 32, chromeOptions: {args: ['--start-maximized'], loggingPrefs:{performance: 'ALL'}}}]

Note: When using any metric that relies on collecting information from Chrome's about:tracing, you should specify the platform (Windows, LINUX or OS X). This platform determines where the tracing output will be saved

Note: When using the chrome browser on android, the browserName should be android. Chrome should be installed on the emulator or the device and chromeOptions.androidPackage is automatically set to com.android.chrome

Note: When testing Cordova apps, set the androidActivity and androidPackage in the chrome options in case of Android. In case of Cordova iOS apps, set the app and bundleId parameters.

An example is

[{
	browserName: 'android',
	chromeOptions: {
		androidActivity: 'io.cordova.hellocordova.HelloCordova', // name of your activity
		androidPackage: 'io.cordova.hellocordova' // name of the package
	}
}]

preScript

No default value

The preScript key in the options object runs a selenium script before the metrics are measured. This is usually for logging in, setting cookies or deleting history. This should be a function and is passed the browser object. This should return a Q style promise once the task is done. An prescript function looks something like this

{
	preScript: function(browser) {
		return browser.get('http://example.com').then(function() {
			console.log('Filling in Username');
			return browser.elementByCssSelector('.UsernameClass')
		}).then(function(el) {
			return el.type('Username for site');
		}).then(function() {
			console.log('Filling in Password');
			return browser.elementByCssSelector('.PasswordFieldClass');
		}).then(function(el) {
			return el.type('password');
		}).then(function() {
			return browser.elementByCssSelector('.SubmitButton');
		}).then(function(el) {
			console.log('Clicking submit');
			return el.click();
		}).then(function() {
			return browser.sleep(5000);
		});
	}
}

The code is based on the wd module's promiseRemote flow. More examples here.

###preScriptFile

No default value

The preScript can be specified in a file instead of specifying it in the node module. The preScriptFile is required into the module, and is exactly like the prescript key above.

// preScriptFile.js
module.exports = function(browser){
  return browser.get('loginpage.html');
}

actions

Default: scroll

actions can also be any of the following strings - scroll, wait. These are built in actions.

The actions that should be performed on the page when the performance is measured. By default, the page is scrolled to measure for smoothness of the page. Other custom interactions (like clicks, swipes, etc) can also be added using custom scripts. To add a custom action, specify the function in the configuration object, like

{ 
   // ... other browser-perf config properties
   actions: [require('custom-action.js')(args)],
}

The custom-action.js file can look something like the following.

module.exports = function(cfg) {
        // cfg - The configuration object. args, from the example above.  
	return function(browser) {
            // browser is created using wd.promiseRemote()
            // More info about wd at https://github.com/admc/wd 
	    return browser.sleep(cfg || 5000);
	}
};

The browser object creating from wd library adds the ability to perform selenium actions like clicks, execute js, etc.

Alternatively, a custom script can also be specified inline, without specifying an external file as

{ 
   // ... other browser-perf config properties
   actions: function(browser){
      return browser.sleep(1000);
   },
}

Please note that custom actions should follow promises, which means all actions should be defined in the .then() syntax powered by Q. Please refer to the preScript section for a quick example.

metrics

Default: All builtIn metrics

The different performance metrics that should be collected when the actions are performed. These metrics include details like frame rates, layouts, paints, etc. This can be a comma separated string, or an array of strings specifying the metrics that need to be measured. Permitted values include ChromeTracingMetrics, NetworkResources, NetworkTimings, RafRenderingStats and TimelineMetrics. These are build in metrics. For example, to measure only metrics related to rendering and ignore metrics related to network, you could set metrics to be ['TimelineMetrics', 'ChromeTracingMetrics'].

debugBrowser

Default: false A value of true indicates that the browser window is left open after the tests. Useful when you want to inspect what happens during the tests.

Additional properties

browser-perf also exposed the following additional properties for convenience.

var browserPerf = require('browser-perf');
browserPerf.docs, browserPerf.actions, browserPerf.runner are available. 

browserPerf.docs

The docs property exposes documentation that each metric generates. browserPerf.docs.metrics returns all the available metrics with documentation.

browserPerf.actions

Exposes functions that can be passed to the actions or preScript configuration option. Typically used to configure the action, like set the username/password in case of login action. For example

... // other config options for browser-perf
actions: [browserPerf.actions.login({
  username: {
    field: 'CSS_for_Username_textbox_in_form',
    value: 'Username_to_be_typed'
  },
  password: {
   field: 'CSS_for_Password_textbox_in_form',
   value: 'password_to_be_typed'
  },
  submit:{
    field: 'Submit_Button_CSS_Selector_In_Form'
  }
})]

browserPerf.runner

A way to use browser-perf with other selenium frameworks. More documentation about this coming soon.

Examples

The API can be used like the following

var browserPref = require('browser-perf');
browserPerf('http://url-to-test.com', function(err, res){/*callback*/}, options);

The options variable can be one of the following

var options = {
	selenium: 'http://localhost:4444',
	browsers: ['chrome', 'firefox']
}

var options = {
	selenium: 'http://ondemand.saucelabs.com',
	username: process.env.SAUCE_USERNAME,
	accesskey: process.env.SAUCE_ACCESSKEY
	browsers: ['chrome', 'firefox'],
	actions: 'scroll'
} 

var options = {
	selenium: 'http://localhost:4444',
	prescriptFile: 'login.js'
	browsers: [{
		browserName: 'chrome',
		version: 32,
		platform: 'WINDOWS'
	}],
}

An example to use it with Cordova is here.