-
Notifications
You must be signed in to change notification settings - Fork 61
Node Module API
When using it as a node module do a require(browser-perf)
after installing it using npm install --save browser-perf
.
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.
The options object is a set of key value pairs as follows
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.
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
orhttp://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
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.
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
}
}]
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 require
d into the module, and is exactly like the prescript key above.
// preScriptFile.js
module.exports = function(browser){
return browser.get('loginpage.html');
}
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.
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']
.
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.
browser-perf also exposed the following additional properties for convenience.
var browserPerf = require('browser-perf');
browserPerf.docs, browserPerf.actions, browserPerf.runner are available.
The docs property exposes documentation that each metric generates. browserPerf.docs.metrics
returns all the available metrics with documentation.
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'
}
})]
A way to use browser-perf with other selenium frameworks. More documentation about this coming soon.
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.