How to Test Your JavaScript with Selenium WebDriver and Mocha

    Dimos Koromilas
    Dimos Koromilas

    This article was originally published on TestProject.

    In case you are looking to write a functional test in JavaScript, the following tutorial provides UI automation engineers with the perfect structural reference material for JavaScript testing with Selenium WebDriver 3, Mocha and NodeJS.

    These days, JavaScript is a ubiquitous web language which seems to overcome its ‘notorious’ past and has become a more solid platform not only for client-side, but for server domains too. Mocha.js, or simply Mocha, is a feature-rich JavaScript test framework running on Node.js, which provides the platform and the API for building standalone applications server-side using Google’s V8 JavaScript engine at its base.

    *Note: to get started with this JavaScript tutorial, you’ll need to be familiar with the basics of NodeJS and the JavaScript programming language.

    Tutorial Overview:

    1. Mocha Test Construction

    • Introduction
    • Installation
    • Installing Chai Assertion Module
    • Test suite and Test Case Structure
    • Constructing Tests with Mocha
    • Running Mocha’s Test Suite and Test Cases
    • Managing Syncing of Async Testing Code

    2. Using Javascript Selenium 3 API Integrated with MochaJS

    • Selenium Introduction
    • Selenium Installation
    • WebDriver Construction
    • Integrating MochaJS with Selenium WebDriver 3

    Versions used:

    • Node version used: 6.10.1 (LTS)
    • Mocha: 2.5.3
    • WebDriverJS: 3.3.0

    1. Constructing Tests with Mocha

    Introduction to Mocha

    As mentioned, Mocha is a JavaScript test framework that runs tests on Node. Mocha comes in the form of a Node package via npm, allowing you to use any library for assertions as a replacement to Node’s standard ‘assert’ function, such as ChaiJS. In addition, Mocha has several similar components to Jasmine, another popular test automation framework which we’ve mentioned in our research for Front End and Unit Test Automation Trends.

    Mocha provides an API, which specifies a way to structure the testing code into test suites and test case modules for execution, and later on to produce a test report. Mocha provides two modes for running: either by command line (CLI) or programmatically (Mocha API).

    Install Mocha

    If Mocha is to be used in CLI, then it should be installed globally as Node.js.

    npm install -g mocha

    Install Chai Assertion Module

    npm install --save chai

    The –save option is used to install the module in the project’s scope and not globally.

    Test Suite and Test Case Structure

    In Mocha, a test suite is defined by the ‘describe’ keyword which accepts a callback function. A test suite can contain child / inner test suites, which can contain their own child test suites, etc. A test case is denoted by the ‘it’ function, which accepts a callback function and contains the testing code.

    Mocha supports test suite setup and test case setup functions. A test suite setup is denoted by before while a test case setup applies beforeEach. beforeEach is actually a common setup for every case in the suite, and will be executed before each case.

    As with the setup, Mocha supports test suite and test case teardown functions. A test suite teardown is denoted by after, while a test case teardown is implemented with afterEach, functions that are executed after a test suite and after each test case respectively.

    Create a file that will ‘host’ the test suite, e.g. test_suite.js, and write the following to it;

    describe("Inner Suite 1", function(){
            // do something before test suite execution
            // no matter if there are failed cases
            // do something after test suite execution is finished
            // no matter if there are failed cases
            // do something before test case execution
            // no matter if there are failed cases
            // do something after test case execution is finished
            // no matter if there are failed cases
        it("Test-1", function(){
            // test Code
            // assertions
        it("Test-2", function(){
            // test Code
            // assertions
        it("Test-3", function(){
            // test Code
            // assertions

    Running Mocha Test Suite and Test Cases

    Mocha supports execution of tests in three ways: Whole Test Suite file, tests filtered by “grep” patterns and tests grep filtering looking in a directory tree (recursive option)

    Run whole Test Suite file:

    mocha /path/to/test_suite.js

    Run a specific suite or test from a specific suite file.

    If a suite is selected then all the child suites and/or tests will be executed.

    mocha -g “Test-2” /path/to/test_suite.js

    Run a specific suite or test file by searching recursively in a directory tree.

    mocha --recursive -g “Test-2” /directory/

    For extensive CLI options:

    mocha –-help

    Managing Syncing of Async Testing Code

    In case async functions are used with Mocha and not handled properly, you may find yourself struggling. If asyncing code (e.g. http requests, files, selenium, etc.) is to be used in a test case, follow these guidelines to overcome unexpected results:

    1. done Function

    In your test function (it) you need to pass the done function down the callback chain — this ensures it is executed after your last step.

    The example below emphasizes the done functionality. In this case three seconds of timeout will occur at the end of the test function.

    it(‘Test-1, function(done){
      // mocha will wait for done to be called before exiting function.
        }, 3000);

    2. Return Promise

    Returning a promise is another way to ensure Mocha has executed all code lines when async functions are used (‘done’ function is not needed in this case.)

    it(‘Test-1, function(done){
        var promise;
        promise = new Promise(function(resolve, reject){
            }, 3000);
        // mocha will wait for the promise to be resolved before exiting
        return promise;  

    2. Javascript Selenium 3 Integration with MochaJS

    Selenium Introduction

    Selenium is a library that controls a web browser and emulates the user’s behavior. More specifically, Selenium offers specific language library APIs called ‘bindings’ for the user. These ‘bindings’ act as a client in order to perform requests to intermediate components and acting as servers in order to finally control a Browser.

    Selenium APIs, or bindings, now exist in all popular developing languages. All language implementations have now agreed to keep a consistency with the API functions’ naming conventions.

    The intermediate components could be the actual webdriver, found natively in each Selenium package, the selenium-standalone-server, as well as vendor native browser controlling drivers — such as Geckodriver for Mozilla, chromedriver for Chrome, etc. Moreover, Selenium webdriver communicates with browser drivers via ‘JsonWired Protocol’ and becomes a W3C Web Standard.

    Selenium Installation

    Before diving any deeper into Selenium integration with MochaJS, we will take a quick look into Selenium implementation with NodeJS.

    In order to use the Selenium API for JavaScript (or Selenium JavaScript bindings), we should install the appropriate module:

    npm install selenium-webdriver

    At this point, it should be clarified that Javascript Selenium WebDriver can also be referred to as Webdriverjs (although not in npm). Webdrivejs is different than other libs/modules, such as WebdriverIO, Protractor, etc. selenium-webdriver is the official open-source base JavaScript Selenium library while the others are wrapper libraries/frameworks that are built on top of webdriverjs API, claiming to enhance usability and maintenance.

    In NodeJS code, the module is used by:


    WebDriver Construction

    In order to be able to use Selenium, we should build the appropriate ‘webdriver’ object which will then control our browser. Below, we can see how we use the “Builder” pattern to construct a webdriver object by chaining several functions.

    Builder with Options

    var webdriver = require('selenium-webdriver')
    var chrome = require('selenium-webdriver/chrome'),
    var firefox = require('selenium-webdriver/firefox');
    var driver = new webdriver.Builder()
        .setFirefoxOptions( /* … */)
        .setChromeOptions( /* … */)

    In the code above, we have managed to build a WebDriver object which aggregates configuration for more than one browser (notice the ‘options’ methods), despite the fact that the forBrowser() method explicitly sets firefox.

    The user can set the SELENIUM_BROWSER environmental variable on runtime to set the desired browser. It will override any option set by forBrowser, since we have already configured multiple browser capabilities by set<browser_name>Options.

    The browser properties can have several types of information depending on the browser under test. For example, in Mozilla’s properties we can set the desired ‘profile’ configuration as follows:

    var profile = new firefox.Profile( /* … path to firefox local profile … */);
    var firefoxOptions = new firefox Options().setProfile(profile);

    Then, in the above Builder snippet we can add:

    ‘setFirefoxOptions( firefoxOptions )

    Builder with Capabilities

    Selenium WebDriver JavaScript API documents several ways that a webdriver could be built. One more possible way is by setting all the required driver configurations in capabilities:

    var driver = new webdriver.Builder().
        .withCapabilities( { ‘browserName’ : ‘firefox’ } )

    Note that if setOptions are set after withCapabilities, the configurations will be overridden (e.g. proxy configurations).

    Selenium WebDriver Control Flow and Promise Management

    Since JavaScript and NodeJS are based on asynchronous principles, Selenium WebDriver behaves in a similar way. In order to avoid callback pyramids and to assist a test engineer with the scripting experience as well as code readability and maintainability, Selenium WebDriver objects incorporate a promise manager that uses a ‘ControlFlow’. ‘ControlFlow’ is a class responsible for the sequential execution of the asynchronous webdriver commands.

    Practically, each command is executed on the driver object and a promise is returned. The next commands do not need to be nested in ‘thens’, unless there is a need to handle a promise resolved value as follows:

    driver.getTitle().then(function( title ) {
        // google page title should be printed 

    Pointers for JavaScript Testing with Selenium WebDriver and Mocha

    1. driver is a webdriver object, not a promise object
    2. driver.getTitle() or driver.get(url), or any other Selenium command, returns a promise object!

    This means that we can perform the following:

    var titlePromise = driver.getTitle();
    1. Additionally, since driver is asyncing in its base, the following will not work:
    var title = driver.getTitle();
    expect (title).equals("Google");

    Note: title is a promise object and not an actual resolved value.

    MochaJS + Selenium WebDriver

    Generally speaking, Selenium WebDriver can be integrated with MochaJS since it is used in any plain NodeJS script. However, since Mocha doesn’t know when an asynchronous function has finished before a done() is called or a promise is returned, we have to be very careful with handling.

    Promise Based

    Selenium commands are registered automatically, to assure webdriver commands are executed in the correct sequential order a promise should be returned.

    The code below shows Mocha’s (before, beforeEach, after, afterEach) or test case body it hooks.

    describe( 'Test Suite' , function(){
            driver.get( my_service );
            // a promise is returned while ‘click’ action
            // is registered in ‘driver’ object
            return driver.findElement(;
            return driver.quit();
        it( 'Test Case', function(){

    The following actions will be executed:

    1. Browser page of “my_service” is loaded
    2. Text Field with id ‘username’ is located
    3. Text Field with id ‘username’ is filled with ‘my_username’
    4. Page title is retrieved and checked for equality against ‘my_title’
    5. WebDriver quits and browser window is closed. Browser process is terminated.

    Selenium Webdriver Support for MochaJS

    In order to perform JavaScript testing with Selenium WebDriver and Mocha in a simple way, WebDriver facilitates usage with MochaJS by wrapping around MochaJS test functions (before, beforeEach, it, etc.) with a test object. This creates a scope that provides awareness that WebDriver is being used. Therefore, there is no need for promise returns.

    First, the corresponding module should be loaded:

    var test = require('selenium-webdriver/testing');

    All the function of Mocha are preceded by ‘test.’ as follows:


    And so on. Then, the above code is fully re-written as:

    test.describe( 'Test Suite' , function(){
            driver.get( my_service );
    'Test Case' , function(){


    In this tutorial we got a chance to experience JavaScript testing with Selenium WebDriver and MochaJS. We should keep in mind the main difference when comparing to other programming language bindings, due to the asynchronous nature of NodeJS, MochaJS and Selenium WebDriver.

    As long as we keep returning promises in any function which creates a promise (either a custom test lib function or a MochaJS hook/testcase), Mocha will execute them in the correct order.

    Other frameworks such as WebdriverIO, Protractor and CodeseptJS provide wrapper solutions that hide some configurations from the user, and provide some promise-enhanced handling for a better scripting experience that many test automation experts might find helpful.

    Frequently Asked Questions (FAQs) about Testing JavaScript with Selenium WebDriver and Mocha

    How can I set up Selenium WebDriver for JavaScript testing?

    Setting up Selenium WebDriver for JavaScript testing involves a few steps. First, you need to install Node.js and npm (Node Package Manager) on your system. Once installed, you can use npm to install Selenium WebDriver by running the command npm install selenium-webdriver. You will also need to install a browser driver, such as ChromeDriver for Google Chrome, which can be done by running npm install chromedriver. After these installations, you can start writing your test scripts in JavaScript using Selenium WebDriver.

    What is Mocha and why is it used with Selenium WebDriver?

    Mocha is a popular JavaScript testing framework that provides a simple and flexible way to write and organize your test cases. It is often used with Selenium WebDriver because it offers features like asynchronous testing, which is crucial for handling operations with latency such as network requests and browser operations. Mocha also provides a clean and simple syntax, making your test cases easier to write and understand.

    How can I write a basic test case using Selenium WebDriver and Mocha?

    Writing a basic test case using Selenium WebDriver and Mocha involves creating a new JavaScript file and writing your test case within a Mocha describe and it block. Within this block, you can use Selenium WebDriver’s API to interact with the browser, such as navigating to a webpage, interacting with elements, and checking their properties. Here’s a basic example:

    const {Builder, By, Key, until} = require('selenium-webdriver');

    describe('Google Search', function() {
    it('should work', async function() {
    let driver = await new Builder().forBrowser('chrome').build();
    await driver.get('');
    await driver.findElement('q')).sendKeys('webdriver', Key.RETURN);
    await driver.wait(until.titleIs('webdriver - Google Search'), 1000);
    await driver.quit();

    How can I handle asynchronous operations in my test cases?

    Asynchronous operations can be handled in your test cases using JavaScript’s async/await syntax. This allows you to write asynchronous code in a synchronous manner, making it easier to read and understand. In the context of Selenium WebDriver, operations like navigating to a webpage, interacting with elements, and waiting for conditions are all asynchronous and can be handled using async/await.

    How can I run my test cases using Mocha?

    To run your test cases using Mocha, you can use the mocha command followed by the path to your test file. For example, if your test file is named test.js, you can run it using the command mocha test.js. Mocha will automatically find and run all test cases within this file.

    How can I use assertions in my test cases?

    Assertions in your test cases can be used to verify that certain conditions are met. For example, you might want to assert that the title of a webpage is what you expect after performing a search. Assertions can be written using JavaScript’s built-in assert module, or using a third-party library like Chai.

    How can I handle errors in my test cases?

    Errors in your test cases can be handled using JavaScript’s try/catch syntax. This allows you to catch any errors that occur during the execution of your test case and handle them appropriately, such as by logging the error and failing the test case.

    How can I interact with elements on a webpage?

    Interacting with elements on a webpage can be done using Selenium WebDriver’s API. This includes operations like clicking on elements, typing into input fields, and reading the properties of elements. These operations are performed using the driver.findElement method, which returns a WebElement object that you can interact with.

    How can I wait for conditions in my test cases?

    Waiting for conditions in your test cases can be done using Selenium WebDriver’s driver.wait method. This method takes a condition and an optional timeout, and waits until the condition is met or the timeout is reached. Conditions can be created using the until module, such as until.titleIs to wait for the title of a webpage to be a certain value.

    How can I run my test cases in different browsers?

    Running your test cases in different browsers can be done by specifying the browser when creating your WebDriver instance. For example, you can use new Builder().forBrowser('firefox') to run your test cases in Firefox, or new Builder().forBrowser('chrome') to run them in Chrome. You will need to have the appropriate browser driver installed for this to work.