This project attempts to provide a quick working sample of Nightwatch with Cucumber tests.

Based on the great work done on :

• Cucumber JS
• Nightwatch Cucumber
• Cucumber HTML Reporter
• Cucumber Junit
• Selenium, ChromeDriver, GeckoDriver
• and all the tools needed by these ones

Thanks to you guys !

Disclosure : Only tested with Chrome (58) and Firefox (54) on Windows.

about those tools

Cucumber.js Guides

Cucumber.js

• Hooks
• Event Handlers

View the project on Github

Nightwatch Guides

WARNING : the nightwatch-cucumber module promisify the nightwatch API. Be carfeful of always use and return promises in your steps definitions.

Nighwatch.js Developer Guide

• Page objects

Nighwatch.js API Reference

View the project on Github

Nightwatch and cucumber integration

The nightwatch-cucumber Project

How do they fit together and what do you have to develop ?

About this sample

It runs the cucumber features defined in the tests/features folder.

Those are "Human Behavior on Browser" features.

After run, you can view :

• the generated HTML reports in the reports folder. Tools used for generation : Cucumber HTML Reporter and Cucumber Junit
• the generated documentation in the doc folder.

Installation and configuration

Simply run :

npm install

Browser drivers

In case of annoying issues because of proxies or anything else when installing, you can provide the urls or paths of the drivers.

Chromedriver AND NOW geckodriver support CDN Urls :

• GECKODRIVER_CDNURL
  • GECKODRIVER_CDNURL=https://INTERNAL_CDN/geckodriver/download
  • more infos
• CHROMEDRIVER_CDNURL
  • CHROMEDRIVER_CDNURL=https://npm.taobao.org/mirrors/chromedriver npm install chromedriver
• with local file path : CHROMEDRIVER_FILEPATH=/path/to/chromedriver_mac64.zip
  • more infos

On other platforms than Windows, for local tests, the paths indicated in the options of the nightwatch.conf.js file need to be adapted with the linux equivalent (without the .cmd at the end of the filenames):

cli_args: {
      'webdriver.gecko.driver': './node_modules/.bin/geckodriver.cmd',
      'webdriver.chrome.driver': './node_modules/.bin/chromedriver.cmd',
    },

to be replaced with :

cli_args: {
      'webdriver.gecko.driver': './node_modules/.bin/geckodriver',
      'webdriver.chrome.driver': './node_modules/.bin/chromedriver',
    },

Remote Selenium Server or Grid

See below to how use env vars for the selenium server or adapt the nightwatch.conf.js file with your settings for more persistent changes :

// remote selenium server
  nightwatchConf.test_settings.default.selenium_host = 'your_remote_selenium_server';
  nightwatchConf.test_settings.default.selenium_port = 4444;

Launch the tests

By default on Chrome local in standalone mode (no selenium server, no java required) :

npm run test
# equivalent
npm run test:localchrome

local selenium server

for firefox :

npm run test:localfirefox

remote selenium server

npm run test:chrome

or

npm run test:firefox

With some debug :

DEBUG=* npm run test

Run only some tags

# run only the Features or Scenarios annotated by @Useful
TAGS='@Useful' npm test

View the full documentation of Tags Syntax

Other examples :

# run only the Features or Scenarios annotated by @Useful and @LessUseful
TAGS='@Useful and @LessUseful' npm test
# don't run the Features or Scenarios annotated by @LessUseful
TAGS='not @LessUseful' npm test

Available Options :

Remote Selenium Server

Use env vars

SELENIUM_HOST=my_server_host SELENIUM_PORT=my_server_port npm test

those options are not used in case of localfirefox or localchrome profiles

Parallel mode

Execute on 3 browsers in parallel :

PARALLEL=true PARALLEL_NB_UNITS=3 npm test

Nightwatch Timeout

from Nightwatch-cucumber timeouts

DEFAULT_TIMEOUT is expressed in seconds.

Execute Test with a timeout for nightwatch actions of 15 seconds :

DEFAULT_TIMEOUT=15 npm test

Defaults to : 20 seconds.

Multi-Environments execution

Use the tests/env folder to declare your environments : one js file by environment.

Use this feature to define configuration options that will be available in your tests under the config object.

To run under an environment :

ENV=MYENV npm test

It supposes that you created a MYENV.js file.

Sample :

'use strict';

const config = {
  users: {
    'VIP': {
      login: '[email protected]',
      password: 'super_password',
    }
  },
};

module.exports = config;

Then import the config.js in steps definitions or Page Objects :

const config = require('../support/config');
...
...
  authenticate(config.users['VIP'].login, config.users['VIP'].password);
...

using globals could avoid to import the config in each js

A Full multi-options example :

Execute the Features or Scenarios :

• tagged @Useful
• on 2 Firefox browsers in parallel
• controlled by the selenium server "my_server_host" on port "my_server_port"
• against an environment called MYENV
• with DEBUG logs activated on all packages
• and a timeout for nightwatch of 10 seconds

TAGS='@Useful' PARALLEL=true PARALLEL_NB_UNITS=2 SELENIUM_HOST=my_server_host SELENIUM_PORT=my_server_port DEFAULT_TIMEOUT=10 ENV=MYENV DEBUG=* npm test:firefox

Reports

After run, 3 reports are available in the reports directory :

• json format : reports/cucumber.json
• html format : reports/cucumber_report.html
• JUnit XML format : reports/cucumber.junit.xml

Screenshots

Screenshots are generated for each Scenario if they failed or even if they passed. They are automatically integrated in the reports (base64 embedded images).

Living Documentation

After run, an HTML documentation of all the features is available from here : doc/index.html

Troubleshooting

Java Version Error when launching the local selenium server

Stack trace

> nightwatch --env chrome || ( node cucumber-report.js && npm run report:junit )

Starting selenium server... There was an error while starting the Selenium server:

java.lang.UnsupportedClassVersionError: org/openqa/grid/selenium/GridLauncherV3 : Unsupported major.minor version 52.0
        at java.lang.ClassLoader.defineClass1(Native Method)
        at java.lang.ClassLoader.defineClass(Unknown Source)
        at java.security.SecureClassLoader.defineClass(Unknown Source)
        at java.net.URLClassLoader.defineClass(Unknown Source)
        at java.net.URLClassLoader.access$100(Unknown Source)
        at java.net.URLClassLoader$1.run(Unknown Source)
        at java.net.URLClassLoader$1.run(Unknown Source)
        at java.security.AccessController.doPrivileged(Native Method)
        at java.net.URLClassLoader.findClass(Unknown Source)
        at java.lang.ClassLoader.loadClass(Unknown Source)
        at sun.misc.Launcher$AppClassLoader.loadClass(Unknown Source)
        at java.lang.ClassLoader.loadClass(Unknown Source)
        at sun.launcher.LauncherHelper.checkAndLoadMain(Unknown Source)
Exception in thread "main"
module.js:472
    throw err;
    ^

Cause : The JVM 1.8 is required to run the local selenium server.

Execute the command to check the current resolved JVM :

java -version

Resolution : Change the JVM version

• If not installed, you need to install a jdk 1.8.
• If installed, you need to change the PATH environment variable.

export JAVA_HOME=path_to_jdk1.8
export PATH=$JAVA_HOME/bin:$PATH