testarmada-magellan-nightwatch

magellan-nightwatch

The NightwatchJS adapter for Magellan

IMPORTANT UPDATE NOTICE

In magellan-nightwatch@4.0.0 we'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.json of your test repo.

"dependencies": {
  "selenium-server": "2.49.1",
  "chromedriver": "2.16.0",
  "phantomjs": "^1.9.19"
}

1. Run npm install again. Dependencies will be installed in ${REPO_ROOT}/node_modules.
2. Make sure your nightwatch.json file 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": "127.0.0.1",
  "port": 12001,
  "cli_args": {
    "webdriver.ie.driver": "",
    "webdriver.chrome.driver": "./node_modules/chromedriver/lib/chromedriver/chromedriver"
  }
}

if you're using Phantomjs

"test_settings":{
  "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 magellan documentation 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 client as 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) {
      client
        .url("http://localhost/");
    },
 
    "Verify header is visible": function (client) {
      client
        .getEl("#header");
    }
 
    "Reveal help modal": function (client)
      client
        .clickAutomationEl("show-help")
        .getEl("#help-modal")
        .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-nightwatch is 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` Equivalent	Description
click("[data-automation-id="mybutton"])	clickAutomationEl("mybutton")	Needs "data-automation-id" attribute in the clickable HTML element's DOM for this command to work
click(selector)	clickEl(selector)
waitForElementPresent or waitForElementVisible	getEl(selector)
moveToElement	moveToEl(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 [phone]) with caret control
waitForElementNotPresent(selector)	waitForElNotPresent(selector)
waitForElementNotPresent(selector)	waitForElNotPresent(selector)
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-nightwatch selector paths can refer to a {token} which your application can implement a replacement value. The implementation is set as a static value on the BaseTestClass as 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-nightwatch are 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:

  client
    .getEl("#submit_order")
    .clickEl("#submit_order")

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

  client
    .clickEl("#submit_order")

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 expression to match text in a much more flexible way

  client
    .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 regexper to 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

• Please refer to Nightwatch Commands API for a list of supported Nightwatch commands

Supported Nightwatch Assertions

• Please refer to Nightwatch Assertions API for a list of supported Nightwatch assertions

Supported Node Assertions

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

Custom Commands

magellan-nightwatch supports 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 documentation for more on commands.

Migrating Nightwatch Configuration

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

Add Magellan's custom commands to your custom_commands_path:

  "custom_commands_path": [
    "./node_modules/testarmada-magellan-nightwatch/lib/commands",

Add Magellan's custom assertions to your custom_assertions_path:

  "custom_assertions_path": [
    "./node_modules/testarmada-magellan-nightwatch/lib/assertions",

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": "127.0.0.1",
    "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 phantomjs path:

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

=======

Version History

1.4.19

Released 25 July 2015

• Full refactor

1.4.20

Released 28 July 2015

• Added setMaskedElValue()
• Updated README with nightwatch.json migration instructions, better base test example.
• Updated selenium-server to 2.46.0 (see migration guide on how this affects nightwatch.json)

1.4.23

Released 06 August 2015

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

1.5.1

Released 27 August 2015

1.5.2

1.5.3

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

• Fixed problem with jQuery injection in some assertions.

1.5.5

Released 1 October 2015

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

4.0.0

• Updated selenium-standalone to 2.49.0