A handy library for BDD specification tests to a JS app
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


sunset-watch Build Status GitHub issues GitHub forks GitHub stars GitHub license NPM


Sunset-watch is an extremely lightweight JavaScript library that allows running BDD style tests over web applications.


sunset-watch allows you to run BDD specifications on your web application but unlike Selenium, it runs into the same browser session as the web application itself. Which makes it super easy to configure and run tests with minimum dependencies (only jQuery at this moment) with other tools.

The idea in a nutshell is like following:

  • Add the script reference of the library into the html file.
  • Write your BDD features in an easy to read format (pseudo Gherkin).
  • Kick off the tests when the page is ready.
  • The report will be shown up on the page after the test run.
  • The report can be posted to another HTTP server.


  • Install the sunset-watch npm package.
    > npm install sunset-watch --save
  • Create a javascript file (i.e. browserTest.js) to boot your BDD tests.
import $ from 'jquery';
import {BDD} from 'sunset-watch';

// We are running the test once the page has been loaded successfully
// Using jQuery ready for that.
$(document).ready(function() {

    // Including a feature into the BDD runtime

    BDD.Behaviors.run((report) => {

Include the test file in the index.html (or any other page) that boots your web application up.

Write the feature

In the test file above we saw a product.feature reference, we will write that now in a product.feature.js file.

import {BDD} from 'sunset-watch';
import steps from './stepDefinitions/product.stepDefinitions';

var Feature = BDD.Feature;

Feature('Product', steps)   
    .Scenario('Search product')
        .Given('I clicked on product Tab')          
        .When('I enter the word - "addidas"')           
        .Then('I see products matched they query');

Now, we will write another file that will glue this feature with the actual application. This file is known as step definitions file. The idea of the step definition is pretty much the same as other popular BDD JS frameworks (i.e. Cucumber). This is where you locate DOM elements, raise events on them and do the relevant asserts.

import {BDD} from 'sunset-watch';

var StepDefinitions = BDD.StepDefinitions;
var Dom = BDD.DOM;

class ProductStepDefinitions extends StepDefinitions {

    clickProductTab(next) {
        Dom.by.id('productTab').to.be.present(function (tab) {
            tab ?  tab.click(next) : next(false);

    search(next) {        
        Dom.by.id('productSearch').to.be.present(function(searchBox) {
            searchBox.sendKeys('Canon EOS 5d mark III', next);

    checkResult(next) {        
        Dom.by.id(this.firstProductSpanId).to.be.present(function(span) {
            next(span != null);

    getStepDefinitions() {
        return [ {
            title: 'Search product',
            steps: [{
                title: 'I clicked on product Tab',
                fn: this.clickProductTab
            }, {
                title: 'I enter the word - "addidas"',
                fn: this.search
            }, {
                title: 'I see products matched they query',
                fn: this.checkResult

export default new ProductStepDefinitions();

Now load the application in the browser and see it will play all the steps.


After it finishes all the steps, the report will be visible on the browser html.

Alt text


This library is very lightweight and feature wise limited compared to other sophisticated tools like Selenium. But this is way-less overhead when you want to write BDD tests quickly and increase productivity at max in a Dev machine.

Nevertheless, this is by no means indicate that it’s an alternate to Selenium.