Nightwatch.js adapter for Magellan


The NightwatchJSadapter for Magellan


In magellan-nightwatch@4.0.0we've removed Chromedriver, Phantomjs and Selenium-server as these are not required while running your test on Saucelabs. However, they are still necessary if you want to run test locally. To use them, you will have to

  1. Copy/cat following code to package.jsonof your test repo.

    "dependencies": {
     "selenium-server": "2.49.1",
     "chromedriver": "2.16.0",
     "phantomjs": "^1.9.19"
  2. Run npm installagain. Dependencies will be installed in ${REPO_ROOT}/node_modules.

  3. Make sure your nightwatch.jsonfile has the following change

    "selenium": {
     "start_process": true,
     "server_path": "./node_modules/selenium-server/lib/runner/selenium-server-standalone-2.49.1.jar",
     "log_path": "reports",
     "host": "",
     "port": 12001,
     "cli_args": {
       "webdriver.ie.driver": "",
       "webdriver.chrome.driver": "./node_modules/chromedriver/lib/chromedriver/chromedriver"

    if you're using Phantomjs

     "phantomjs": {
       "desiredCapabilities": {
         "browserName": "phantomjs",
         "javascriptEnabled": true,
         "acceptSslCerts": true,
         "phantomjs.binary.path": "./node_modules/phantomjs/bin/phantomjs"

Running Tests

For instructions on how to run tests, please see the magellandocumentation at: https://github.com/TestArmada/magellan

Writing Tests

Tests are structured as simple modules with a single exported object containing keyed functions. The functions are executed in the order in which they appear in the object source. Each function represents a step in the test, and its key in the test object should represent the name of the step. Each step function gets a clientas an argument which represents a browser. For more information on writing tests, see the Nightwatch.js documentation.

var MagellanTest = require("testarmada-magellan-nightwatch/lib/base-test-class");

  module.exports = new MyTest({
    "Load homepage": function (client) {

    "Verify header is visible": function (client) {

    "Reveal help modal": function (client)
        .assert.elContainsText("#help-modal", "This is the help modal");

For more examples, see the boilerplate project at: https://github.com/TestArmada/boilerplate

Command Vocabulary

magellan-nightwatchis a wrapper around Nightwatch.js, but is constrained to a limited subset of Nightwatch vocabulary to promote reliability.

Enhanced Command List

If you're familiar with Nightwatch or are looking to translate Nightwatch examples into magellan-nightwatch, refer to the table below for equivalent enhanced (i.e. more reliable) versions of Nightwatch commands:

Nightwatch Command / Assertion`magellan-nightwatch` EquivalentDescription
click("[data-automation-id="mybutton"])clickAutomationEl("mybutton")Needs "data-automation-id" attribute in the clickable HTML element's DOM for this command to work
waitForElementPresent or waitForElementVisiblegetEl(selector)
moveToElementmoveToEl(selector, xoffset, yoffset)
setValue(selector, value)setElValue(selector, value)
getValue(selector)getElValue(selector, callback)
elements(using, value, callback)getEls(selector, callback)
(no nightwatch equivalent)scrollToEl(selector)
(no nightwatch equivalent)setMaskedElValue(selector, value, [fieldLength])Set a value on a field that's using a mask (eg: MM/DD/YYYY or (555) 123-4567) with caret control
getPerformance(url)Retrieves basic performance metrics using Navigation API (http://www.w3.org/TR/navigation-timing/)
assert.containsText(selector, text)assert.elContainsText(selector, regex or text)
(no nightwatch equivalent)assert.elNotContainsText(selector, text)
(no nightwatch equivalent)assert.selectorHasLength(selector, expectedLength)
(no nightwatch equivalent)assert.elLengthGreaterThan(selector, selectUsing, lengthToCompare)

Custom selector tokens

All magellan-nightwatchselector paths can refer to a {token}which your application can implement a replacement value. The implementation is set as a static value on the BaseTestClassas selectorToken. For example, to replace {foo}with [data-automation-id="foo"]you would use

require('testarmada-magellan-nightwatch/lib/base-test-class').selectorToken = function (value) {
  return '[data-selector-id="' + value + '"]';

Custom Commands Examples

The commands included with magellan-nightwatchare safer, more reliable and "thrash-resistent" versions of Nightwatch commands. Note that clickEl(), clickAutomationEl(), and setElValue()are safe to call without first waiting for their selector to appear because they execute getEl()as part of their internals. Consider the following snippet:


The above snippet can be shortened to the following form (and will execute faster):


Our custom commands try be as readable and flexible as possible. For example, rather than just accepting text inside the `el(Not?)ContainsText commands, you can also include a regular expressionto match text in a much more flexible way

    .elContainsText("#submit_order", "Price \d+\.\d\d")

This would match "Price" followed by one more more digits, a decimal, then two more digits. You can use regexperto help visualize and debug regular expressions

As-is Supported Nightwatch Vocabulary

All Nightwatch commands and assertions are supported out of the box.

Supported Nightwatch Commands

Supported Nightwatch Assertions

Supported Node Assertions

  • fail
  • equal
  • notEqual
  • deepEqual
  • notDeepEqual
  • strictEqual
  • notStrictEqual
  • throws
  • doesNotThrow
  • ifError

Custom Commands

magellan-nightwatchsupports the development of custom commands to allow the re-use of common parts of tests. If you're using the same snippets of code to fill out a form that appears in many tests, or have a common way to sign into your application, etc, then custom commands are for you. Please see the Nightwatch.js documentationfor more on commands.

Migrating Nightwatch Configuration

To migrate an existing vanilla nightwatch.jsonconfiguration to magellan-nightwatch, update the following

Add Magellan's custom commands to your custom_commands_path:

"custom_commands_path": [

Add Magellan's custom assertions to your custom_assertions_path:

"custom_assertions_path": [

Ensure Selenium server/driver paths are correct:

"selenium": {
    "start_process": true,
    "server_path": "./node_modules/testarmada-magellan-nightwatch/node_modules/selenium-server/lib/runner/selenium-server-standalone-2.49.0.jar",
    "log_path": "reports",
    "host": "",
    "port": 4444,
    "cli_args": {
      "webdriver.chrome.driver": "./node_modules/testarmada-magellan-nightwatch/node_modules/chromedriver/lib/chromedriver/chromedriver",
      "webdriver.ie.driver": ""

Note: pay special attention to the version number for the selenium server above, currently at version 2.49.0*

Set up phantomjspath:

"phantomjs" : {
    "desiredCapabilities" : {
      "browserName" : "phantomjs",
      "javascriptEnabled" : true,
      "acceptSslCerts" : true,
      "phantomjs.binary.path" : "./node_modules/testarmada-magellan-nightwatch/node_modules/phantomjs/bin/phantomjs"


Version History


Released 25 July 2015

  • Full refactor


Released 28 July 2015

  • Added setMaskedElValue()
  • Updated READMEwith nightwatch.jsonmigration instructions, better base test example.
  • Updated selenium-serverto 2.46.0(see migration guide on how this affects nightwatch.json)


Released 06 August 2015

  • Use default node-chromedriver install instead of fork (previously needed to work around firewall issue)


Released 27 August 2015



  • Added getPerformance()command to retrieve the performance results for a url

  • Fixed problem with jQuery injection in some assertions.


Released 1 October 2015

  • Added getElValue()
  • Added getEls()
  • Added scrollToEl()


  • Updated selenium-standaloneto 2.49.0






扫码加入 JavaScript 社区