alt text

BDD (Behavior-driven development) is a process that easies the conversion of user features specifications to code that developers must write to satisfy them. In fact, with BDD tools developers can write test cases in a human-readable and non-technical language.

There are many libraries that allow developers to write tests in BDD-style; the most used ones are Cucumber, JBehave and Behat.

While JBehave and Behat are focused only on Java and PHP projects (respectively), Cucumber supports different software platforms with its implementations, like Ruby, JavaScript, Python, PHP, C++.

Cucumber uses the notions of feature, scenario, step and page to create the connection between an human readable language and the testing code.

With Cucumber’s Gherkin language developers can write test cases, describing software’s behaviour without detailing the implementation of that behaviour. Test cases are divided in features, which are sets of scenarios, which are sets of steps. One step is represented by a sentence. This sentence is associated with a regex written in a steps definition file, which contains the code to run when the Gherkin parser read the sentence. For example, the following feature has a 5-step scenario:

Feature: As a good developer i want to test my angular app in BDD

Scenario: I want to see the home page
    Given I am on the "login"
    When I fill "email" field with "donkeycode@example.org"
    And I fill "password" field with "donkeycode"
    And I click on the button "login"
    Then I should be redirected on "home"

The first and the third lines are feature and scenario headlines. They present the following syntaxes:

Feature: [Feature Title]

Scenario: [Scenario Title]

Every step must start with one of the keywords Given, When, Then, But or And. Cucumber treats them all the same, but for developers these keywords must have different purposes:

Given: to put the system in a known state
When: to describe the key action the user performs
Then: to observe outcomes
And or But: to use if there are several givens, whens or thens

More information about Gherkin keywords are available here.

In the above example, every step contains string values (“login”, “email”, “donkeycode@example.org”, “password”, “donkeycode”, “login” and “home”) which become arguments of functions in the steps definition file.

In web development, developers use page files to write the CSS selectors and the URLs needed to test the application.

The angular-protractor-cucumber library

If you are developing an Angular-based application and you want to use the Gherkin language to write your test cases, you do not have many ready-to-use libraries.

At DonkeyCode, we have developed the angular-protractor-cucumber library to easily integrate the Angular end-to-end test framework, Protractor, with Cucumber and Gherkin.

Interesting features of the library are:

more than 20 built-in sentences
automatic screenshots capturing after failing step
database mocking through .js files
dev environment to slow tests and easy the debugging
models definition

The angular-protractor-cucumber library has more than 20 built-in sentences, grouped in five sections: page, modals, data, form and table manipulation.

When we use CI (Continuous Integration) services like Travis CI or CI tools like Jenkins, it’s very difficult to debug testing errors because they use headless browsers to run tests. To make life easier, angular-protractor-cucumber takes a screenshot of the page after errors and save it in a .png file in the logs/test/e2e folder. With Travis CI, we can get these screenshots easily using Travis artifacts (based on AWS S3) or uploading them directly to AWS S3 (using AWS S3 CLI) or other similar 3rd-party services.

Models allow to define ids of objects in one file and use them in different test cases.

The full documentation of angular-protractor-cucumber is available here.

Installation

You can install angular-protractor-cucumber with:

npm install --save-dev angular-protractor-cucumber

After that, you have to write a configuration file (protractor.conf.js) in your Angular root directory, for example:

// protractor.conf.js

exports.config = {
    allScriptsTimeout: 99999,

    // The address of a running selenium server.
    // seleniumAddress: 'http://127.0.0.1:4444/wd/hub',

    // The location of the selenium standalone server .jar file, relative
    // to the location of this config. If no other method of starting selenium
    // is found, this will default to
    // node_modules/protractor/selenium/selenium-server...
    seleniumServerJar: './node_modules/protractor/selenium/selenium-server-standalone-2.47.1.jar',

    // The port to start the selenium server on, or null if the server should
    // find its own unused port.
    seleniumPort: 4444,

    // Capabilities to be passed to the webdriver instance.
    capabilities: {
        'browserName': 'chrome'
    },

    baseUrl: 'http://localhost:9876/',

    framework: 'cucumber',

    // Spec patterns are relative to the current working directly when protractor is called.
    specs: [
        'test/e2e/**/*.feature'
    ],

    // Options to be passed to Cucumber.
    cucumberOpts: {
        // Require files before executing the features.
        require: [
            'node_modules/angular-protractor-cucumber/src/step-definitions/**/*.js',
            'node_modules/angular-protractor-cucumber/src/support/**/*.js',
            'test/e2e/step-definitions/**/*.js',
            'test/e2e/support/**/*.js'
        ],
        // Only execute the features or scenarios with tags matching @dev.
        // This may be an array of strings to specify multiple tags to include.
        // tags: '@dev',
        // How to format features (progress, summary, pretty, json)
        format: 'pretty',
    },

    resultJsonOutputFile: './test/e2e/results.json'
};

Using this configuration, Chrome is the testing browser and we have to write features files in test/e2e/** directories and use the .feature extension. In baseUrl we have to write the URL address of the application we want to test.

To run tests, you have to execute the following command:

./node_modules/protractor/bin/protractor protractor.conf.js

And to use the slow dev environment:

./node_modules/protractor/bin/protractor protractor.conf.js --cucumberOpts.env=dev

A first simple feature

If we use the above configuration file, we have to write our tests in test/e2e/*** folders. For example, let’s write a first feature in *test/e2e/home/sample.feature:

# test/e2e/home/sample.feature

Feature: As a good developer i want to test my angular app in BDD

Scenario: I want to see the home page
    Given I am on the "login"
    When I fill "email" field with "donkeycode@example.org"
    And I fill "password" field with "donkeycode"
    And I click on the button "login"
    Then I should be redirected on "home"

The line

Given I am on the "login"

is one of the built-in sentences in the page manipulation section. It’s used to change the URL address. We have to define the “login” page in a test/e2e/support/pages/**/.js* file. This file contains at least the URL property:


// test/e2e/support/pages/login/login.js

'use strict';

module.exports = function login() {
    return {
        url: "login"
    };
}();

The following test line is:

When I fill "email" field with "donkeycode@example.org"

This line is another built-in sentence (in the form manipulation section). We need to define the “email” field in the login.js file:


// test/e2e/support/pages/login/login.js

'use strict';

module.exports = function login() {
    return {
        url: "login",
        getFieldByName: function (name) {
            var mapping = {
                "email": 'input[ng-model="login.mail"]'
            };

            return mapping[name];
        }
    };
}();

The getFieldByName() function allows us to reference the email field with its CSS selector (input[ng-model=”login.mail”]).

The following testing line uses the same sentence (Cucumber treats When and And all the same):

And I fill "password" field with "donkeycode"

So we need to add the “password” field CSS selector:

// test/e2e/support/pages/login/login.js

'use strict';

module.exports = function login() {
    return {
        url: "login",
        getFieldByName: function (name) {
            var mapping = {
                "email": 'input[ng-model="login.mail"]',
                "password": 'input[ng-model="login.password"]'
            };

            return mapping[name];
        }
    };
}();

The following line in the scenario is:

And I click on the button "login"

Now we have to add the button selector (in this case .btn) with the function getButtonByName():

// test/e2e/support/pages/login/login.js

'use strict';

module.exports = function login() {
    return {
        url: "login",
        getButtonByName: function (buttonName) {
            var mapping = {
                "login": ".btn"
            };

            return mapping[buttonName];
        },
        getFieldByName: function (name) {
            var mapping = {
                "email": 'input[ng-model="login.mail"]',
                "password": 'input[ng-model="login.password"]',
            };

            return mapping[name];
        }
    };
}();

The last testing line is:

Then I should be redirected on "home"

With this one, protractor checks if there is a redirection to the “home” page after the click on the “login” button. So we have to define the “home” page in a new .js file:

// test/e2e/support/pages/home/home.js

'use strict';

module.exports = function home() {
    return {
        url: "home"
    };
}();

In future posts we will add more interesting examples to show other features of angular-protractor-cucumber. Stay tuned!