nemo

Nemo

Nemo provides a simple way to add selenium automation to your NodeJS web projects. With a powerful configuration ability provided by krakenjs/confit, and plugin architecture, Nemo is flexible enough to handle any browser/device automation need.

Nemo is built to easily plug into any task runner and test runner. But in this README we will only cover setup and architecture of Nemo as a standalone entity.

Getting started

Pre-requisites

Webdriver

Please see here for more information about setting up a webdriver. As long as you have the appropriate browser or browser driver (selenium-standalone, chromedriver) on your PATH, the rest of this should work fine.

package.json changes

add the following to package.json devDependencies (assuming mocha is already integrated to your project):

"nemo": "git://github.com/paypal/nemo#1.0-develop",

Then npm install

Nemo and Confit in 90 seconds

Nemo uses confit - a powerful, expressive and intuitive configuration system - to elegantly expose the Nemo and selenium-webdriver APIs.

Direct configuration

If you install this repo you'll get the following in examples/setup.js. Note the Nemo() constructor is directly accepting the needed configuration, along with a callback function.

var nemo = Nemo({
  "driver": {
    "browser": "firefox"
  },
  'data': {
    'baseUrl': 'https://www.paypal.com'
  }
}, function (err) {
  //always check for errors!
  if (!!err) {
    console.log('Error during Nemo setup', err);
  }
  nemo.driver.get(nemo.data.baseUrl);
  nemo.driver.getCapabilities().
    then(function (caps) {
      console.info("Nemo successfully launched", caps.caps_.browserName);
    });
  nemo.driver.quit();
});

Run it:

$ node examples/setup.js
Nemo successfully launched firefox

Using config files

Look at examples/setupWithConfigFiles.js

//passing __dirname as the first argument tells confit to
//look in __dirname + '/config' for config files
var nemo = Nemo(__dirname, function (err) {
  //always check for errors!
  if (!!err) {
    console.log('Error during Nemo setup', err);
  }

  nemo.driver.get(nemo.data.baseUrl);
  nemo.driver.getCapabilities().
    then(function (caps) {
      console.info("Nemo successfully launched", caps.caps_.browserName);
    });
  nemo.driver.quit();
});

Note the comment above that passing a filesystem path as the first argument to Nemo() will tell confit to look in that directory + /config for config files.

Look at examples/config/config.json

{
  "driver": {
    "browser": "config:BROWSER"
  },
  "data": {
    "baseUrl": "https://www.paypal.com"
  },
  "BROWSER": "firefox"
}

That is almost the same config as the first example. But notice "config:BROWSER". Yes, confit will resolve that to the config property "BROWSER".

Run this and it will open the Firefox browser:

$ node examples/setup.js
Nemo successfully launched firefox

Now run this command:

$ node examples/setupWithConfigDir.js --BROWSER=chrome
Nemo successfully launched chrome

Here, confit resolves the --BROWSER=chrome command line argument and overrides the BROWSER value from config.json

Now this command:

$ BROWSER=chrome node examples/setupWithConfigDir.js
Nemo successfully launched chrome

Here, confit resolves the BROWSER environment variable and overrides BROWSER from config.json

What if we set both?

$ BROWSER=chrome node examples/setupWithConfigDir.js BROWSER=phantomjs
Nemo successfully launched chrome

You can see that the environment variable wins.

Now try this command:

$ NODE_ENV=special node examples/setupWithConfigDir.js
Nemo successfully launched phantomjs

Note that confit uses the value of NODE_ENV to look for an override config file. In this case config/special.json:

{
  "driver": {
    "browser": "phantomjs"
  },
  "data": {
    "baseUrl": "https://www.paypal.com"
  }
}

Hopefully this was an instructive dive into the possibilities of Nemo + confit. There is more to learn but hopefully this is enough to whet your appetite for now!

Nemo and Plugins in 60 Seconds

Look at the example/setupWithPlugin.js file:

var nemo = Nemo(basedir, function (err) {
  //always check for errors!
  if (!!err) {
    console.log('Error during Nemo setup', err);
  }
  nemo.driver.getCapabilities().
    then(function (caps) {
      console.info("Nemo successfully launched", caps.caps_.browserName);
    });
  nemo.driver.get(nemo.data.baseUrl);
  nemo.cookie.deleteAll();
  nemo.cookie.set('foo', 'bar');
  nemo.cookie.getAll().then(function (cookies) {
    console.log('cookies', cookies);
    console.log('=======================');
  });
  nemo.cookie.deleteAll();
  nemo.cookie.getAll().then(function (cookies) {
    console.log('cookies', cookies);
  });
  nemo.driver.quit();
});

Notice the nemo.cookie namespace. This is actually a plugin, and if you look at the config for this setup:

{
  "driver": {
    "browser": "firefox"
  },
  "data": {
    "baseUrl": "https://www.paypal.com"
  },
  "plugins": {
    "cookie": {
      "module": "path:./nemo-cookie"
    }
  }
}

You'll see the plugins.cookie section, which is loading examples/plugin/nemo-cookie.js as a plugin:

'use strict';

module.exports = {
  "setup": function (nemo, callback) {
    nemo.cookie = {};
    nemo.cookie.delete = function (name) {
      return nemo.driver.manage().deleteCookie(name);
    };
    nemo.cookie.deleteAll = function () {
      return nemo.driver.manage().deleteAllCookies();
    };
    nemo.cookie.set = function (name, value, path, domain, isSecure, expiry) {
      return nemo.driver.manage().addCookie(name, value, path, domain, isSecure, expiry)
    };
    nemo.cookie.get = function (name) {
      return nemo.driver.manage().getCookie(name);
    };
    nemo.cookie.getAll = function () {
      return nemo.driver.manage().getCookies();
    };
    callback(null);

  }
};

Running this example:

$ node examples/setupWithPlugin.js
Nemo successfully launched firefox
cookies [ { name: 'foo',
   value: 'bar',
   path: '',
   domain: 'www.paypal.com',
   secure: false,
   expiry: null } ]
=======================
cookies []
$

This illustrates how you can create a plugin, and the sorts of things you might want to do with a plugin.

Nemo Constructor

var nemo = Nemo([[nemoBaseDir, ]config, ]callback);

@argument nemoBaseDir {String} (optional) - If provided, should be a filesystem path to your test suite. Nemo will expect to find a /config directory beneath that. <nemoBaseDir>/config/config.json should have your default configuration (described below). nemoBaseDir can alternatively be set as an environment variable. If it is not set, you need to pass your configuration as the config parameter (see below).

@argument config {Object} (optional) - Can be a full configuration (if nemoBaseDir not provided) or additional/override configuration to what's in your config files.

@argument callback {Function} - This function will be called once the nemo object is fully resolved. It may be called with an error argument which has important debugging information. So make sure to check for an error.

@returns nemo {Object} - The nemo object has the following properties:

• driver The live selenium-webdriver API. See WebDriver API Doc: http://selenium.googlecode.com/git/docs/api/javascript/class_webdriver_WebDriver.html

• wd This is a reference to the selenium-webdriver module: http://selenium.googlecode.com/git/docs/api/javascript/module_selenium-webdriver.html

• data Pass through of any data included in the data property of the configuration

• _config This is the confit configuration object. Documented here: https://github.com/krakenjs/confit#config-api

• plugin namespace(s) Plugins are responsible for registering their own namespace under nemo. The convention is that the plugin should register the same namespace as is specified in the plugin configuration. E.g. the nemo-view module registers itself as nemo.view and is configured like this:

{
  "driver": ...
  "plugins": {
    "view": {
      "module": "nemo-view"
    }
  }

You could also have a config that looks like this, and nemo-view will still register itself as nemo.view

{
  "driver": ...
  "plugins": {
    "cupcakes": {
      "module": "nemo-view"
    }
  }

But that's confusing. So please stick to the convention.

Typical usage of Nemo constructor

A typical pattern would be to use mocha as a test runner, resolve nemo in the context of the mocha before function, and use the mocha done function as the callback:

var nemo;
describe('my nemo suite', function() {
  before(function(done) {
    nemo = Nemo(config, done);
  });
  it('will launch browsers!', function(done) {
    nemo.driver.get('https://www.paypal.com');
    nemo.driver.quit().then(function() {
       done();
    });
  });
});

Nemo Configuration

{
  "driver": { /** properties used by Nemo to setup the driver instance **/ },
  "plugins": { /** plugins to initialize **/},
  "data": { /** arbitrary data to pass through to nemo instance **/ }
}

This configuration object is optional, as long as you've got nemoData set as an environment variable (see below).

driver

Here are the driver properties recognized by Nemo. This is ALL of them. Please be aware that you really only need to supply "browser" to get things working initially.

browser (optional)

Browser you wish to automate. Make sure that your chosen webdriver has this browser option available

local (optional, defaults to false)

Set local to true if you want Nemo to attempt to start a standalone binary on your system (like selenium-standalone-server) or use a local browser/driver like Chrome/chromedriver or PhantomJS.

server (optional)

Webdriver server URL you wish to use.

If you are using sauce labs, make sure server is set to correct url like "http://yourkey:[e-mail]:80/wd/hub"

serverProps (optional/conditional)

Additional server properties required of the 'targetServer'

You can also set args and jvmArgs to the selenium jar process as follows:

'serverProps': {
  'port': 4444,
  'args': ['-firefoxProfileTemplate','/Users/medelman/Desktop/ffprofiles'],
  'jvmArgs': ['-someJvmArg', 'someJvmArgValue']
}

jar (optional/conditional)

Path to your webdriver server Jar file. Leave unset if you aren't using a local selenium-standalone Jar (or similar).

serverCaps (optional)

serverCaps would map to the capabilities here: http://selenium.googlecode.com/git/docs/api/javascript/source/lib/webdriver/capabilities.js.src.html

Some webdrivers (for instance ios-driver, or appium) would have additional capabilities which can be set via this variable. As an example, you can connect to saucelabs by adding this serverCaps:

"serverCaps": {
	"username": "medelman",
	"accessKey": "b38e179e-079a-417d-beb8-xyz", //not my real access key
	"name": "Test Suite Name", //sauce labs session name
	"tags": ['tag1','tag2'] //sauce labs tag names
}

proxyDetails (optional)

If you want to run test by setting proxy in the browser, you can use 'proxyDetails' configuration. Following options are available: direct, manual, pac and system. Default is 'direct'. For more information refer : https://selenium.googlecode.com/git/docs/api/javascript/module_selenium-webdriver_proxy.html

"proxyDetails" : {
    method: "manual",
    args: [{"http": "localhost:9001","ftp":"localhost:9001","https":"localhost:9001"}]
}

builders (optional)

This is a JSON interface to any of the Builder methods which take simple arguments and return the builder. See the Builder class here: http://selenium.googlecode.com/git/docs/api/javascript/module_selenium-webdriver_class_Builder.html

Useful such functions are:

• forBrowser (can take the place of "browser", "local" and "jar" properties above)
• withCapabilities (can take the place of "serverCaps" above)

There may be some overlap between these functions and

plugins

Plugins are registered with JSON like the following (will vary based on your plugins)

{
	"plugins": {
		"samplePlugin": {
			"module": "path:plugin/sample-plugin",
			"arguments: [...]
			"priority": 99
		},
		"view": {
			"module": "nemo-view"
		}
	}
}

Plugin.pluginName parameters:

• module {String} - Module must resolve to a require'able module, either via name (in the case it is in your dependency tree) or via path to the file or directory.

• arguments {Array} (optional, depending on plugin) - Your plugin will be called via its setup method with these arguments: [configArg1, configArg2, ..., ]nemo, callback. Please note that the braces there indicate "optional". The arguments will be applied via Function.apply

• priority {Number} (optional, depending on plugin) - A priority value of < 100 will register this plugin BEFORE the selenium driver object is created. This means that such a plugin can modify config properties prior to driver setup. Leaving priority unset will register the plugin after the driver object is created.

data

Data will be arbitrary stuff that you might like to use in your tests. In a lot of the examples we set data.baseUrl but again, that's arbitrary and not required. You could pass and use data.cupcakes if you want. Cupcakes are awesome.

Shortstop handlers

Shortstop handlers are data processors that key off of directives in the JSON data. Ones that are enabled in nemo are:

path

use path to prepend the nemoBaseDir (or process.cwd()) to a value. E.g. if nemoBaseDir is .../myApp/tests then a config value of 'path:plugin/myPlugin' will resolve to .../myApp/tests/plugin/myPlugin

env

use env to reference environment variables. E.g. a config value of 'env:PATH' will resolve to /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:...

config

Use config to reference data in other parts of the JSON configuration. E.g. in the following config.json:

{
  'driver': {
    ...
  },
  'plugins': {
    'myPlugin': {
      'module': 'nemo-some-plugin',
      'arguments': ['config:data.someProp']
    }
  },
  'data': {
    'someProp': 'someVal'
  }
}

The value of plugins.myPlugin.arguments[0] will be someVal

Plugins

Authoring a plugin, or using an existing plugin, is a great way to increase the power and usefulness of your Nemo installation. A plugin should add its API to the nemo object it receives and passes on in its constructor (see "plugin interface" below)

plugin interface

A plugin should export a setup function with the following interface:

module.exports.setup = function myPlugin([arg1, arg2, ..., ]nemo, callback) {
  ...
  //add your plugin to the nemo namespace
  nemo.myPlugin = myPluginFactory([arg1, arg2, ...]); //adds myMethod1, myMethod2

  //error in your plugin setup
  if (err) {
    callback(err);
    return;
  }
  //continue
  callback(null);
};

When nemo initializes your plugin, it will call the setup method with any arguments supplied in the config plus the nemo object, plus the callback function to continue plugin initialization.

Then in your module where you use Nemo, you will be able to access the plugin functionality:

var Nemo = require('nemo');
var nemo = Nemo({
  'driver': {
    'browser': 'firefox',
    'local': true,
    'jar': '/usr/local/bin/selenium-server-standalone.jar'
  },
  'data': {
    'baseUrl': 'https://www.paypal.com'
  },
  'plugins': {
    'myPlugin': {
      'module': 'path:plugin/my-plugin',
      'arguments': [...]
      'priority': 99
    },
  }
}, function () {
  nemo.driver.get(nemo.data.baseUrl);
  nemo.myPlugin.myMethod1();
  nemo.myPlugin.myMethod2();
  nemo.driver.sleep(5000).
    then(function () {
      console.info('Nemo was successful!!');
      nemo.driver.quit();
    });
});

Logging and debugging

Nemo uses the debug module for console logging and error output. There are two classes of logging, nemo:log and nemo:error

If you want to see both classes of output, simply use the appropriate value of the DEBUG environment variable when you run nemo:

$ DEBUG=nemo:* <nemo command>

To see just one:

$ DEBUG=nemo:error <nemo command>

Why Nemo?

Because we NEed MOre automation testing!