Sunday, April 3, 2016

Clean architecture of Selenium tests

In this blog post, I would like to introduce a clean architecture for Selenium tests with best design patterns: page object, page element (often called HTML wrapper) and self-developed, very small but smart framework. The architecture is not restricted to Java which is used in the examples and can be applied to Selenium tests in any other language as well.

Definitions and relations.

Page Object. A page object encapsulates the behavior of a web page. There is one page object per web page that abstracts the page's logic to the outside. That means, the interaction with the web page is encapsulated in the page object. Selenium's By locators to find elements on the page are not disclosed to the outside as well. The page object's caller should not be busy with the By locators, such as By.id, By.tageName, By.cssSelector, etc. Selenium test classes operate on page objects. Take an example from a web shop: the page object classes could be called e.g. ProductPage, ShoppingCartPage, PaymentPage, etc. These are always classes for the whole web pages with their own URLs.

Page Element (aka HTML Wrapper). A page element is another subdivision of a web page. It represents a HTML element and encapsulates the logic for the interaction with this element. I will term a page element as HTML wrapper. HTML wrappers are reusable because several pages can incorporate the same elements. For instance, a HTML wrapper for Datepicker can provide the following methods (API): "set a date into the input field", "open the calendar popup", "choose given day in the calendar popup", etc. Other HTML wrappes would be e.g. Autocomplete, Breadcrumb, Checkbox, RadioButton, MultiSelect, Message, ... A HTML Wrapper can be composite. That means, it can consist of multiple small elements. For instance, a product catalog consists of products, a shopping cart consists of items, etc. Selenium's By locators for the inner elements are encapsulated in the composite page element.

Page Object and HTML Wrappers as design patterns were described by Martin Fowler.

The skeletal structure of a Selenium test class.

A test class is well structured. It defines the test sequence in form of single process steps. I suggest the following structure:
public class MyTestIT extends AbstractSeleniumTest {

    @FlowOnPage(step = 1, desc = "Description for this method")
    void flowSomePage(SomePage somePage) {
        ...
    }

    @FlowOnPage(step = 2, desc = "Description for this method")
    void flowAnotherPage(AnotherPage anotherPage) {
        ...
    }

    @FlowOnPage(step = 3, desc = "Description for this method")
    void flowYetAnotherPage(YetAnotherPage yetAnotherPage) {
        ...
    }

    ...
}
The class MyTestIT is an JUnit test class for an integration test. @FlowOnPage is a method annotation for the test logic on a web page. The step parameter defines a serial number in the test sequence. The numeration starts with 1. That means, the annotated method with the step = 1 will be processed before the method with the step = 2. The second parameter desc stands for description what the method is doing.
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface FlowOnPage {

    int step() default 1;
 
    String desc();
}
The annotated method is invoked with a page object as method parameter. A switch to the next page normally occurs per click on a button or link. The developed framework should make sure that the next page is completely loaded before the annotated method with next step gets called. The next diagram illustrates the relationship between a test class, page objects and HTML wrappers.


But stop. Where is the JUnit method annotated with @Test and where is the logic for the parsing of @FlowOnPage annotation? That code is hidden in the super class AbstractSeleniumTest.
public abstract class AbstractSeleniumTest {

    // configurable base URL
    private final String baseUrl = System.getProperty("selenium.baseUrl", "http://localhost:8080/contextRoot/");

    private final WebDriver driver;

    public AbstractSeleniumTest() {
        // create desired WebDriver
        driver = new ChromeDriver();

        // you can also set here desired capabilities and so on
        ...
    }

    /**
     * The single entry point to prepare and run test flow.
     */
    @Test
    public void testIt() throws Exception {
        LoadablePage lastPageInFlow = null;
        List <Method> methods = new ArrayList<>();

        // Seach methods annotated with FlowOnPage in this and all super classes
        Class c = this.getClass();
        while (c != null) {
            for (Method method: c.getDeclaredMethods()) {
                if (method.isAnnotationPresent(FlowOnPage.class)) {
                    FlowOnPage flowOnPage = method.getAnnotation(FlowOnPage.class);
                    // add the method at the right position
                    methods.add(flowOnPage.step() - 1, method);
                }
            }

            c = c.getSuperclass();
        }

        for (Method m: methods) {
            Class<?>[] pTypes = m.getParameterTypes();

            LoadablePage loadablePage = null;
            if (pTypes != null && pTypes.length > 0) {
                loadablePage = (LoadablePage) pTypes[0].newInstance();
            }

            if (loadablePage == null) {
                throw new IllegalArgumentException("No Page Object as parameter has been found for the method " +
                    m.getName() + ", in the class " + this.getClass().getName());
            }

            // initialize Page Objects Page-Objekte and set parent-child relationship
            loadablePage.init(this, m, lastPageInFlow);
            lastPageInFlow = loadablePage;
        }

        if (lastPageInFlow == null) {
            throw new IllegalStateException("Page Object to start the test was not found");
        }

        // start test
        lastPageInFlow.get();
    }

    /**
     * Executes the test flow logic on a given page.
     *
     * @throws AssertionError can be thrown by JUnit assertions
     */
    public void executeFlowOnPage(LoadablePage page) {
        Method m = page.getMethod();
        if (m != null) {
            // execute the method annotated with FlowOnPage
            try {
                m.setAccessible(true);
                m.invoke(this, page);
            } catch (Exception e) {
                throw new AssertionError("Method invocation " + m.getName() +
                    ", in the class " + page.getClass().getName() + ", failed", e);
            }
        }
    }

    @After
    public void tearDown() {
        // close browser
        driver.quit();
    }

    /**
     * This method is invoked by LoadablePage.
     */
    public String getUrlToGo(String path) {
        return baseUrl + path;
    }

    public WebDriver getDriver() {
        return driver;
    }
}
As you can see, there is only one test method testIt which parses the annotations, creates page objects with relations and starts the test flow.

The structure of a Page Object.

Every page object class inherits from the class LoadablePage which inherits again from the Selenium's class LoadableComponent. A good explanation for LoadableComponent is available in this well written article: Simple and advanced usage of LoadableComponent. LoadablePage is our own class, implemented as follows:
import org.openqa.selenium.support.ui.WebDriverWait;
import org.junit.Assert;
import org.openqa.selenium.By;
import org.openqa.selenium.Keys;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.interactions.Actions;
import org.openqa.selenium.support.PageFactory;
import org.openqa.selenium.support.ui.ExpectedCondition;
import org.openqa.selenium.support.ui.LoadableComponent;
import org.openqa.selenium.support.ui.WebDriverWait;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.lang.reflect.Method;
import java.util.List;

public abstract class LoadablePage<T extends LoadableComponent<T>> extends LoadableComponent<T> {

    private final static Logger LOGGER = LoggerFactory.getLogger(LoadablePage.class);

    private AbstractSeleniumTest seleniumTest;
    private String pageUrl;
    private Method method;
    private LoadablePage parent;

    /**
     * Init method (invoked by the framework).
     *
     * @param seleniumTest instance of type AbstractSeleniumTest
     * @param method to be invoked method annotated with @FlowOnPage
     * @param parent parent page of type LoadablePage
     */
    void init(AbstractSeleniumTest seleniumTest, Method method, LoadablePage parent) {
        this.seleniumTest = seleniumTest;
        this.pageUrl = seleniumTest.getUrlToGo(getUrlPath());
        this.method = method;
        this.parent = parent;

        PageFactory.initElements(getDriver(), this);
    }

    /**
     * Path of the URL without the context root for this page.
     *
     * @return String path of the URL
     */
    protected abstract String getUrlPath();

    /***
     * Specific check which has to be implemented by every page object.
     * A rudimentary check on the basis of URL is undertaken by this class.
     * This method is doing an extra check if the page has been proper loaded.
     *
     * @throws Error thrown when the check fails
     */
    protected abstract void isPageLoaded() throws Error;

    @Override
    protected void isLoaded() throws Error {
        // min. check against the page URL
        String url = getDriver().getCurrentUrl();
        Assert.assertTrue("You are not on the right page.", url.equals(pageUrl));

        // call specific check which has to be implemented on every page
        isPageLoaded();
    }

    @Override
    protected void load() {
        if (parent != null) {
            // call the logic in the parent page
            parent.get();

            // parent page has navigated to this page (via click on button or link).
            // wait until this page has been loaded.
            WebDriverWait wait = new WebDriverWait(getDriver(), 20, 250);
            wait.until(new ExpectedCondition<Boolean> () {
                @Override
                public Boolean apply(WebDriver d) {
                    try {
                        isLoaded();
                        return true;
                    } catch (AssertionError e) {
                        return false;
                    }
                }
            });
        } else {
            // Is there no parent page, the page should be navigated directly
            LOGGER.info("Browser: {}, GET {}", getDriver(), getPageUrl());
            getDriver().get(getPageUrl());
        }
    }

    /**
     * Ensure that this page has been loaded and execute the test code on the this page.
     *
     * @return T LoadablePage
     */
    public T get() {
        T loadablePage = super.get();

        // execute flow logic
        seleniumTest.executeFlowOnPage(this);

        return loadablePage;
    }

    /**
     * See {@link WebDriver#findElement(By)}
     */
    public WebElement findElement(By by) {
        return getDriver().findElement(by);
    }

    /**
     * See {@link WebDriver#findElements(By)}
     */
    public List<WebElement> findElements(By by) {
        return getDriver().findElements(by);
    }

    public WebDriver getDriver() {
        return seleniumTest.getDriver();
    }

    protected String getPageUrl() {
        return pageUrl;
    }

    Method getMethod() {
        return method;
    }
}
As you can see, every page object class needs to implement two abstract methods:
/**
 * Path of the URL without the context root for this page.
 *
 * @return String path of the URL
 */
protected abstract String getUrlPath();

/***
 * Specific check which has to be implemented by every page object.
 * A rudimentary check on the basis of URL is undertaken by the super class.
 * This method is doing an extra check if the page has been proper loaded.
 *
 * @throws Error thrown when the check fails
 */
protected abstract void isPageLoaded() throws Error;
Now I would like to show the code for a concrete page object and a test class which tests the SBB Ticket Shop, so that readers can acquire a taste for testing with page objects. The page object TimetablePage contains HTML wrappers for basic elements.
public class TimetablePage extends LoadablePage<TimetablePage> {

    @FindBy(id = "...")
    private Autocomplete from;
    @FindBy(id = "...")
    private Autocomplete to;
    @FindBy(id = "...")
    private Datepicker date;
    @FindBy(id = "...")
    private TimeInput time;
    @FindBy(id = "...")
    private Button search;

    @Override
    protected String getUrlPath() {
        return "pages/fahrplan/fahrplan.xhtml";
    }

    @Override
    protected void isPageLoaded() throws Error {
        try {
            assertTrue(findElement(By.id("shopForm_searchfields")).isDisplayed());
        } catch (NoSuchElementException ex) {
            throw new AssertionError();
        }
    }

    public TimetablePage typeFrom(String text) {
        from.setValue(text);
        return this;
    }

    public TimetablePage typeTo(String text) {
        to.setValue(text);
        return this;
    }

    public TimetablePage typeTime(Date date) {
        time.setValue(date);
        return this;
    }

    public TimetablePage typeDate(Date date) {
        date.setValue(date);
        return this;
    }

    public TimetablePage search() {
        search.clickAndWaitUntil().ajaxCompleted().elementVisible(By.cssSelector("..."));
        return this;
    }

    public TimetableTable getTimetableTable() {
        List<WebElement> element = findElements(By.id("..."));
        if (element.size() == 1) {
            return TimetableTable.create(element.get(0));
        }

        return null;
    }
}
In the page object, HTML wrappers (simple or composite) can be created either by the @FindBy, @FindBys, @FindAll annotations or dynamic on demand, e.g. as TimetableTable.create(element) where element is the underlying WebElement. Normally, the annotations don't work with custom elements. They only work with the Selenium's WebElement per default. But it is not difficult to get them working with the custom elements too. You have to implement a custom FieldDecorator which extends DefaultFieldDecorator. A custom FieldDecorator allows to use @FindBy, @FindBys, or @FindAll annotations for custom HTML wrappers. A sample project providing implementation details and examples of custom elements is available here. You can also catch the Selenium's infamous StaleElementReferenceException in your custom FieldDecorator and recreate the underlying WebElement by the original locator. A framework user doesn't see then StaleElementReferenceException and can call methods on WebElement even when the referenced DOM element was updated in the meantime (removed from the DOM and added with a new content again). This idea with code snippet is available here.

But ok, let me show the test class. In the test class, we want to test if a hint appears in the shopping cart when a child under 16 years travels without parents. Firts of all, we have to type the stations "from" and "to", click on a desired connection in the timetable and add a child on the next page which shows travel offers for the choosen connection.
public class HintTravelerIT extends AbstractSeleniumTest {

    @FlowOnPage(step = 1, desc = "Seach a connection from Bern to Zürich and click on the first 'Buy' button")
    void flowTimetable(TimetablePage timetablePage) {
        // Type from, to, date and time
        timetablePage.typeFrom("Bern").typeTo("Zürich");
        Date date = DateUtils.addDays(new Date(), 2);
        timetablePage.typeDate(date);
        timetablePage.typeTime(date);

        // search for connections
        timetablePage.search();

        // click on the first 'Buy' button
        TimetableTable table = timetablePage.getTimetableTable();
        table.clickFirstBuyButton();
    }

    @FlowOnPage(step = 2, desc = "Add a child as traveler and test the hint in the shopping cart")
    void flowOffers(OffersPage offersPage) {
        // Add a child
        DateFormat df = new SimpleDateFormat("dd.MM.yyyy", Locale.GERMAN);
        String birthDay = df.format(DateUtils.addYears(new Date(), -10));
        offersPage.addTraveler(0, "Max", "Mustermann", birthDay);
        offersPage.saveTraveler();

        // Get hints
        List<String> hints = offersPage.getShoppingCart().getHints();

        assertNotNull(hints);
        assertTrue(hints.size() == 1);
        assertEquals("A child can only travel under adult supervision", hints.get(0));
    }
}

The structure of a HTML Wrapper.

I suggest to create an abstract base class for all HTML wrappers. Let's call it HtmlWrapper. This class can provide some common methods, such as click, clickAndWaitUntil, findElement(s), getParentElement, getAttribute, isDisplayed, ... For editable elements, you can create a class EditableWrapper which inherits from the HtmlWrapper. This class can provide some common methods for editable elements, such as clear (clears the input), enter (presses the enter key), isEnabled (checks if the element is enabled), ... All editable elements should inherit from the EditableWrapper. Futhermore, you can provide two interfaces EditableSingleValue and EditableMultipleValue for single and multi value elements respectively. The next diagram demonstrates the idea. It shows the class hierarchy for three basic HTML wrappes:

Datepicker. It inherits from the EditableWrapper and implements the EditableSingleValue interface.
MultiSelect. It inherits from the EditableWrapper and implements the EditableMultiValue interface.
Message. It extends directly the HtmlWrapper because a message is not editable.


Do you want more implementation details for HTML wrappers? Details for an jQuery Datepicker can be found for example in this great article. The MultiSelect is a wrapper around the famous Select2 widget. I have implemented the wrapper in my project in the following way:
public class MultiSelect extends EditableWrapper implements EditableMultiValue<String> {

    protected MultiSelect(WebElement element) {
        super(element);
    }

    public static MultiSelect create(WebElement element) {
        assertNotNull(element);
        return new MultiSelect(element);
    }

    @Override
    public void clear() {
        JavascriptExecutor js = (JavascriptExecutor) getDriver();
        js.executeScript("jQuery(arguments[0]).val(null).trigger('change')", element);
    }

    public void removeValue(String...value) {
        if (value == null || value.length == 0) {
            return;
        }

        JavascriptExecutor js = (JavascriptExecutor) getDriver();
        Object selectedValues = js.executeScript("return jQuery(arguments[0]).val()", element);
        String[] curValue = convertValues(selectedValues);
        String[] newValue = ArrayUtils.removeElements(curValue, value);

        if (newValue == null || newValue.length == 0) {
            clear();
        } else {
            changeValue(newValue);
        }
    }

    public void addValue(String...value) {
        if (value == null || value.length == 0) {
            return;
        }

        JavascriptExecutor js = (JavascriptExecutor) getDriver();
        Object selectedValues = js.executeScript("return jQuery(arguments[0]).val()", element);
        String[] curValue = convertValues(selectedValues);
        String[] newValue = ArrayUtils.addAll(curValue, value);

        changeValue(newValue);
    }

    @Override
    public void setValue(String...value) {
        clear();
        if (value == null || value.length == 0) {
            return;
        }

        changeValue(value);
    }

    @Override
    public String[] getValue() {
        JavascriptExecutor js = (JavascriptExecutor) getDriver();
        Object values = js.executeScript("return jQuery(arguments[0]).val()", element);

        return convertValues(values);
    }

    private void changeValue(String...value) {
        Gson gson = new Gson();
        String jsonArray = gson.toJson(value);

        String jsCode = String.format("jQuery(arguments[0]).val(%s).trigger('change')", jsonArray);
        JavascriptExecutor js = (JavascriptExecutor) getDriver();
        js.executeScript(jsCode, element);
    }

    @SuppressWarnings("unchecked")
    private String[] convertValues(Object values) {
        if (values == null) {
            return null;
        }

        if (values.getClass().isArray()) {
            return (String[]) values;
        } else if (values instanceof List) {
            List<String> list = (List<String> ) values;
            return list.toArray(new String[list.size()]);
        } else {
            throw new WebDriverException("Unsupported value for MultiSelect: " + values.getClass());
        }
    }
}
And an example of Message implementation for the sake of completeness:
public class Message extends HtmlWrapper {

    public enum Severity {
        INFO("info"),
        WARNING("warn"),
        ERROR("error");

        Severity(String severity) {
            this.severity = severity;
        }

        private final String severity;

        public String getSeverity() {
            return severity;
        }
    }

    protected Message(WebElement element) {
        super(element);
    }

    public static Message create(WebElement element) {
        assertNotNull(element);
        return new Message(element);
    }

    public boolean isAnyMessageExist(Severity severity) {
        List<WebElement> messages = findElements(
      By.cssSelector(".ui-messages .ui-messages-" + severity.getSeverity()));
        return messages.size() > 0;
    }

    public boolean isAnyMessageExist() {
        for (Severity severity: Severity.values()) {
            List<WebElement> messages = findElements(
       By.cssSelector(".ui-messages .ui-messages-" + severity.getSeverity()));
            if (messages.size() > 0) {
                return true;
            }
        }

        return false;
    }

    public List<String> getMessages(Severity severity) {
        List<WebElement> messages = findElements(
      By.cssSelector(".ui-messages .ui-messages-" + severity.getSeverity() + "-summary"));
        if (messages.isEmpty()) {
            return null;
        }

        List<String> text = new ArrayList<> ();
        for (WebElement element: messages) {
            text.add(element.getText());
        }

        return text;
    }
}
The Message wraps the Message component in PrimeFaces.

Conclusion: when you finished the writing of page objects and HTML wrappers, you can settle back and concentrate on the comfortable writing of Selenium tests. Feel free to share your thoughts.

Sunday, March 20, 2016

Promises in AngularJS. Part II. $q service.

I have already blogged about Promises in AngularJS 1.x. This is the second part which describes the Angular's $q service. The $q service can be used in two different ways. The first way mimics the Q library for creating and composing asynchronous promises in JavaScript. The second way mimics the ECMAScript 2015 (ES6) style. Let's begin with the first way. First of all, you have to create a deferred object by $q.defer().
 
var deferred = $q.defer();
 
A deferred object can be created within an asynchronous function. The function should return a promise object created from the deferred object as follows:
 
return deferred.promise;
 
A promise is always in either one of three states:
  1. Pending: the result hasn't been computed yet
  2. Fulfilled: the result was computed successfully
  3. Rejected: a failure occurred during computation
When the asynchronous function finished the execution, it can invoke one of the two methods:
deferred.resolve(...)
deferred.reject(...)
The first call deferred.resolve(...) puts the promise into the fulfilled state. As result a success callback will be invoked. The second call deferred.reject(...) puts the promise into the rejected state. As result an error callback will be invoked. It is also possible to invoke
 
deferred.notify(...)
 
during the function's execution to propogate some progress from the asynchronous function to an update callback. All three callbacks can be registered on the promise as parameters of the function then:
var promise = someAsynchronousFunction();
promise.then(function(value) {
    // success
    ...
}, function(reason) {
    // failure
    ...
}, function(update) {
    // update
    ...
});
Let's implement an example. We will take setTimeout() as an asynchronous function. In the real application, you will probably use some other asynchronous services. In the setTimeout(), we will generate a random number after 1 sek. If the number is less than 0.5, we will invoke deferred.resolve(random), otherwise deferred.reject(random). The entire logic is implemented in the controller PromiseController.
var app = angular.module('app', []);
app.controller('PromiseController', PromiseController);

function PromiseController($q) {
    var _self = this;
    this.message = null;

    var asyncFunction = function() {
        var deferred = $q.defer();

        setTimeout(function() {
            var random = Math.random().toFixed(2);

            if (random < 0.5) {
                deferred.resolve(random);
            } else {
                deferred.reject(random);
            }
        }, 1000);

        return deferred.promise;
    }

    this.invokeAsyncFunction = function() {
        var promise = asyncFunction();

        promise.then(function(message) {
            _self.message = "Success: " + message;
        }, function(message) {
            _self.message = "Error: " + message;
        });
    }
}
As you can see, the asynchronous function asyncFunction is invoked in the controller's method invokeAsyncFunction. The function asyncFunction returns a promise. In the success case, the promise gets fulfilled and the first registered success callback gets executed. In the error case, the promise gets rejected and the second registered error callback gets executed. The invokeAsyncFunction is bound to the onclick event on a button.
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta content="IE=edge" http-equiv="X-UA-Compatible" />
    <script src="https://code.angularjs.org/1.4.8/angular.js"></script>
</head>

<body ng-app="app" ng-controller="PromiseController as ctrlPromise">
    <div ng-bind="ctrlPromise.message"></div>
    <p></p>
    <button ng-click="ctrlPromise.invokeAsyncFunction()">
        Invoke asynchronous function
    </button>

    <script src="controller.js"></script>
</body>
</html>
The message in GUI looks like as follows (success case as example):


The Plunker of this example is available here. Here is another picture that visualize the relation between methods of the deferred object:


As you can see, the asynchronous function doesn't return the deferred object directly. The reason for that is obvious. If the deferred object would be returned instead of deferred.promise, the caller of the asynchronous function could be able to trigger callbacks by invoking deferred.resolve(...), deferred.reject(...) or deferred.notify(...). For this reason these methods are protected from being invoking from outside by the caller.

The example above can be rewritten in the ECMAScript 2015 (ES6) style (I mentioned this way at the beginning). A promise in ECMAScript 2015 can be created as an instance of Promise object.
var promise = new Promise(function(resolve, reject) {
    ...
    if(...) {
        resolve(value); // success
    } else {
        reject(reason); // failure
    }
});
Our asyncFunction function looks in this case as follows:
var asyncFunction = function() {
    return $q(function(resolve, reject) {

        setTimeout(function() {
            var random = Math.random().toFixed(2);

            if (random < 0.5) {
                resolve(random);
            } else {
                reject(random);
            }
        }, 1000);
    });
}
The remaining code stays unchanged. Let's go on. The next question is, how can we produce a rejection in success or error callbacks? For instance, you check some condition in a callback and want to produce an error if the condition is not fulfilled. Sometimes, we also want to forward rejection in a chain of promises. That means, you catch an error via an error callback and you want to forward the error to the promise derived from the current promise. There are two ways to achieve this qoal. The first one consists in using the $q.reject(...) like shown below.
var promise = someAsynchronousFunction();
promise.then(function(value) {
    // success
    ...
    if(someCondition) {
        $q.reject("An error occurred!");
    }
}, function(reason) {
    // failure
    ...
}).catch(function(error) {
    // do something in error case
    ...
});
In our example, we will adjust the function invokeAsyncFunction in order to check very small values (smaller than 0.1).
this.invokeAsyncFunction = function() {
    var promise = asyncFunction();

    promise.then(function(random) {
        if (random < 0.1) {
            return $q.reject("Very small random value!");
        }

        _self.message = "Success: " + random;
    }, function(random) {
        _self.message = "Error: " + random;
    }).catch(function(error) {
        _self.message = "Special error: " + error;
    });
}


A Plunker example is available here. Keep in mind the difference between deferred.reject(...) and $q.reject(...). The call deferred.reject(...) puts the corresponding promise into the rejected state. The call $q.reject(...) creates a new promise which is already in the rejected state.

The second way to produce a rejection in success or error callbacks consists in throwing an exception with throw new Error(...).
this.invokeAsyncFunction = function() {
    var promise = asyncFunction();

    promise.then(function(random) {
        if (random < 0.1) {
            throw new Error("Very small random value!");
        }

        _self.message = "Success: " + random;
    }, function(random) {
        _self.message = "Error: " + random;
    }).catch(function(error) {
        _self.message = "Special error: " + error;
    });
}
AngularJS will catch the exception, create a promise in the rejected state and forward it to the next block in the chain of promises. In the example, the error will be forwarded to the catch block. One downside of this approach with throw new Error(...) is that the error will be logged in the console. Picture from the Chrome Dev Tools:


But well, it works as designed and probably it is even an advantage to see thrown errors in the console.

There is also an opposite method $q.when(...) which returns an immediately resolved promise. The documentation says: $q.when(...) "wraps an object that might be a value or a (3rd party) then-able promise into a $q promise. This is useful when you are dealing with an object that might or might not be a promise, or if the promise comes from a source that can't be trusted." You can e.g. wrap an jQuery Deferred Object with $q.when(...) or simple write
$q.when("Finished!").then(
    function handleResolve(value) {
        console.log("Resolved with value: ", value);
    }
);
and see Resolved with value: Finished! in the console. The alias of $q.when(value) is $q.resolve(value). This was introduced later in order to maintain naming consistency with ECMAScript 2015.

Last but not least is the method $q.all(promises) where promises is an array of multiple promises. This call returns a single promise that is resolved when all promises in the given array gets resolved.
var promise1 = someAsynchronousFunction1();
var promise2 = someAsynchronousFunction2();

$q.all([promise1, promise2]).then(function(result) {
    console.log("Promises " + result[0] + " and " + result[1] + " finished their work successfully");
});
As you can see, the result passed into the callback function is an array of two outcomes - the outcome of the first and the outcome of the second callback.

Sunday, January 3, 2016

Installing Babel command line and playing with ES6

If you would like to play with ECMAScript6, you can install Babel CLI globally on your machine and run the babel-node command. babel-node is a version of the Node.js executable that understands ES6. It can be installed with the package manager NPM. Installation instructions are listed below.

1) Install two Node.js modules babel and babel-cli one after another. Note: if you have some troubles during installation, update your Node.js and NPM to the latest stable versions.

npm install --global babel
npm install --global babel-cli

2) Install a set of plugins for available ES6 (ES2015) features. Without these plugins you will get errors about unexpected token or similar. See http://babeljs.io/docs/plugins/preset-es2015/ for more details about supported ES6 features.

npm install --global babel-preset-es2015

3a) Start interactive REPL and type ES6 code. Note: globally installed modules on Windows are located under C:\Users\<Username>\AppData\Roaming\npm\node_modules, so that we need to put a complete path to them.

babel-node --presets C:\\Users\\Oleg\\AppData\\Roaming\\npm\\node_modules\\babel-preset-es2015
> let arr = [1,2,3]
> arr.map(x => x * x)
Output: [1,4,9]


3b) Alternative, you can place some ES6 code into a file, e.g. testes6.js, and let it run.

babel-node --presets C:\\Users\\Oleg\\AppData\\Roaming\\npm\\node_modules\\babel-preset-es2015 testes6.js
Output: [1,4,9]


In the example, babel-node is executed in the same directory where the file testes6.js is located.

Enjoy.

Wednesday, December 30, 2015

The best way for sharing data between controllers in AngularJS 1.x

You may know the situation in AngularJS 1.x when multiple independent controllers need to share some data. E.g. one controller adds some data that should be available in the other controllers in the same view. So far as I know there are three possibilities:
  • Using $scope, e.g. $scope of a common parent controller or $rootScope
  • Using publish-subscribe design pattern via $emit / $broadcast (fire events) and $on (listen for events)
  • Using services which can be injected in multiple controllers.
The first possibility to share data via $scope is a bad idea. If you share data via scopes, you have to know controllers' parent-child relationship. That means, your controllers are tightly coupled and the refactoring is hard to master. Some AngularJS examples save the data on the $rootScope, but the pollution of $rootScope is not recommended. Keep the $rootScope as small as possible. The event based possibility to share data via $emit, $broadcast and $on is a better approach in comparison to scope based one. The controllers are loosely coupled. But there is a disadvantage as well - the performance. The performance is ok for a small application, but for a large application with hundreds of $on listeners, the AngularJS has to introspect all scopes in order to find the $on listeners that fit to the corresponsing $emit / $broadcast. From the architecture point there is a shortcoming as well - we still need scopes to register $emit, $broadcast and $on. Some people also say - communication details should be hidden for the same reason we keep $http hidden behind a service layer. There are 5 guidelines for avoiding scope soup in AngularJS. The last 5. rule is called Don't Use Scope To Pass Data Around. It advices against using scopes directly and against event based approach. Last but not least - think about the upcomming AngularJS 2. It doesn't have scopes!

In my opinion, the preferred way for sharing data between controllers in AngularJS 1.x is the third possibility. We can use services. A service can keep data or acts as event emitter (example is shown below). Any service can be injected into controllers, so that conrollers still don't know from each other and thus are loosely coupled. I will refactor and extend one example from this blog post. The author of this blog post implemented two controllers for two panes. In the left pane we can input some text and add it as an item to a list in the right pane. The list itself is placed in a service (service encapsulates the data). This is probably a good idea when you have different views or controllers in conditional ng-if. But if controllers exist in the same view and show their data at the same time, the list should reside in the controller for the right pane and not in the service. The list belongs to the second controller. This is my opinion, so I will move the list into the controller and also add a third "message controller" which is responsible for messages when user adds items to the list or removes them from the list. We thus have three controllers and one service. The idea is to apply the listener pattern (also known as observer) to the service. The service acts as event emitter. Every controller can fire an ADD or REMOVE operation and register a listener function to be notified when the operation is done. The added / removed item acts as data passed along with operation into all registered listeners for the given operation. The live example is implemented on Plunker.

The first picture shows the adding process (click on the button Add To List) with a message about the successfully added item.


The second picture shows the removing process (click on a link with x symbol) with a message about the successfully removed item.


The HTML part looks as follows:
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta content="IE=edge" http-equiv="X-UA-Compatible" />
    <script src="https://code.angularjs.org/1.4.8/angular.js"></script>
</head>

<body ng-app="app">
    <div ng-controller="MessageController as ctrlMessage" style="margin-bottom:20px;">
        <span ng-bind-html="ctrlMessage.message"></span>
    </div>

    <div ng-controller="PaneOneController as ctrlPaneOne">
        <input ng-model="ctrlPaneOne.item">
        <button ng-click="ctrlPaneOne.addItem(ctrlPaneOne.item)">Add To List</button>
    </div>

    <div ng-controller="PaneTwoController as ctrlPaneTwo" style="float:right; width:50%; margin-top:-20px;">
        <ul style="margin-top:0">
            <li ng-repeat="item in ctrlPaneTwo.list track by $index">
                {{item}}
                <a href style="margin-left:5px;" title="Remove" ng-click="ctrlPaneTwo.removeItem($index)">x</a>
            </li>
        </ul>
    </div>

    <script src="controller.js"></script>
    <script src="service.js"></script>
</body>
</html>
As you can see, there are three independent HTML div elements with ng-controller directive. The MessageController shows a message above. The PaneOneController keeps an input value and the function addItem(). The PaneTwoController keeps a list with all items and the function removeItem(). The controllers look as follows in details:
(function() {
    var app = angular.module('app', []);
    app.controller('PaneOneController', PaneOneController);
    app.controller('PaneTwoController', PaneTwoController);
    app.controller('MessageController', MessageController);

    /* first controller */
    function PaneOneController(EventEmitterListService) {
        var _self = this;
        this.item = null;

        this.addItem = function(item) {
            EventEmitterListService.emitAddItem(item);
            _self.item = null;
        }
    }

    /* second controller */
    function PaneTwoController($scope, EventEmitterListService) {
        var _self = this;
        this.list = [];

        this.removeItem = function(index) {
            var removed = _self.list.splice(index, 1);
            EventEmitterListService.emitRemoveItem(removed[0]);
        }

        EventEmitterListService.onAddItem('PaneTwo', function(item) {
            _self.list.push(item);
        });

        $scope.$on("$destroy", function() {
            EventEmitterListService.clear('PaneTwo');
        });
    }

    /* third controller */
    function MessageController($scope, $sce, EventEmitterListService) {
        var _self = this;
        this.message = null;

        EventEmitterListService.onAddItem('Message', function(item) {
            _self.message = $sce.trustAsHtml("<strong>" + item + "</strong> has been added successfully");
        });

        EventEmitterListService.onRemoveItem('Message', function(item) {
            _self.message = $sce.trustAsHtml("<strong>" + item + "</strong> has been removed successfully");
        });

        $scope.$on("$destroy", function() {
            EventEmitterListService.clear('Message');
        });
    }
})();
All three controllers communicate with a service called EventEmitterListService. The service exposes three methods:
  • emitAddItem - notifies listeners that are interested in adding an item to the list. The item is passed as parameter.
  • emitRemoveItem - notifies listeners that are interested in removing an item from the list. The item is passed as parameter.
  • onAddItem - registers a listener function that is interested in adding an item to the list. The listener is passed as parameter.
  • onRemoveItem - registers a listener function that is interested in removing an item from the list. The listener is passed as parameter.
  • clear - removes all registered listeners which belong to the specified controller. The controller is identified by the scope parameter (simple unique string).
The clear method is important when the $scope gets destroyed (e.g. when the DOM associated with the $scope gets removed due to ng-if or view switching). This method should be invoked on $destroy event - see code snippets with $scope.$on("$destroy", function() {...}). The full code of the service is listed below:
(function() {
    var app = angular.module('app');
    app.factory('EventEmitterListService', EventEmitterListService);

    function EventEmitterListService() {
        // Format of any object in the array:
        // {scope: ..., add: [...], remove: [...]}
        // "scope": some identifier, e.g. it can be the part of controller's name
        // "add": array of listeners for the given scope to be notified when an item is added
        // "remove": array of listeners for the given scope to be notified when an item is removed
        var listeners = [];

        function emitAddItem(item) {
            emitAction('add', item);
        }

        function onAddItem(scope, listener) {
            onAction('add', scope, listener);
        }

        function emitRemoveItem(item) {
            emitAction('remove', item);
        }

        function onRemoveItem(scope, listener) {
            onAction('remove', scope, listener);
        }

        function clear(scope) {
            var index = findIndex(scope);
            if (index > -1) {
                listeners.splice(index, 1);
            }
        }

        function emitAction(action, item) {
            listeners.forEach(function(obj) {
                obj[action].forEach(function(listener) {
                    listener(item);
                });
            });
        }

        function onAction(action, scope, listener) {
            var index = findIndex(scope);
            if (index > -1) {
                listeners[index][action].push(listener);
            } else {
                var obj = {
                    'scope': scope,
                    'add': action == 'add' ? [listener] : [],
                    'remove': action == 'remove' ? [listener] : []
                }
                listeners.push(obj);
            }
        }

        function findIndex(scope) {
            var index = -1;
            for (var i = 0; i < listeners.length; i++) {
                if (listeners[i].scope == scope) {
                    index = i;
                    break;
                }
            }

            return index;
        }

        var service = {
            emitAddItem: emitAddItem,
            onAddItem: onAddItem,
            emitRemoveItem: emitRemoveItem,
            onRemoveItem: onRemoveItem,
            clear: clear
        };

        return service;
    }
})();
That's all. Happy New Year!

Wednesday, December 23, 2015

Mock responses to HTTP calls with network traffic simulation by using ngMockE2E

The AngularJS' module ngMockE2E allows to fake HTTP backend implementation for unit testing and to respond with static or dynamic responses via the when API and its shortcuts (whenGET, whenPOST, etc). In this post, I will only demonstrate how to respond to any HTTP calls by mocking the responses. We will also see how the network load can be simulated. Such behavior gives a feeling of real remote calls. The implemented example is available on Plunker. It shows a small CRUD application to manage imaginary persons. There are four buttons for sending AJAX requests in a REST like manner. When a request is sent, you can see the text Loading... which disappears after 2 seconds when the response "is arrived". In fact, no request is sent of course. This is just a simulation with the AngularJS' module ngMockE2E. The network load takes exactly 2 seconds but you can set another delay value if you want


The first button sends a GET request to /persons to receives all available persons. If you click on this button, you will see three persons received from the imaginary backend.


The second button sends a GET request to /person/:id to receives one person by its ID. The ID is appended to the URI part /person/. If you type e.g. 2 and click on this button, you should see the following person


There is also a proper validation. If you type e.g. 4, no person will be found because no person with the ID 4 exists in "the backend".


If you type some wrong ID which is not a numeric value, an error message will be shown as well.


The third button sends a POST request to /person to create a new person or update existing one. The input fields name and birthday are required. You can type a name and birthday for a new person, sends the POST request and see the created person recived from "the backend".


Now, if you sends a GET request to /persons (the first button), you should see the created person in the list of all persons.


The last button deletes a person by sending the DELETE request to /person/:id. The deleted person is shown above the buttons.


Click on the first button again to ensure that the person was deleted and doesn't exist more.


Let's show the code. First of all you have to include the file angular-mocks.js after the file angular.js in order to overwrite the original $httpBackend functionality.
<script src="https://code.angularjs.org/1.4.8/angular.js"></script>
<script src="https://code.angularjs.org/1.4.8/angular-mocks.js"></script>
What is $httpBackend? In AngularJS, we normally use a high level $http or $resource service for HTTP calls. These services use for their part a low level service called $httpBackend. The $httpBackend has useful methods to create new backend definitions for various request types. There is a method when(method, url, [data], [headers], [keys]) and many shortcut methods such as
  • whenGET(url, [headers], [keys])
  • whenHEAD(url, [headers], [keys])
  • whenDELETE(url, [headers], [keys])
  • whenPOST(url, [data], [headers], [keys])
  • whenPUT(url, [data], [headers], [keys])
  • ...
The most interesting parameter is the url. This can be a String like /persons, a regular expression like /^\/person\/([0-9]+)$/ for /person/:id or a function that receives the url and returns true if the url matches the current definition. These methods return an object with respond and passThrough functions that control how a matched request is handled. The passThrough is useful when the backend REST API is ready to use and you want to pass mocked request to the real HTTP call. In this example, we only use the respond. The respond can take the object to be returned, e.g. $httpBackend.whenGET('/persons').respond(persons) or a function function(method, url, data, headers, params) which returns an array containing response status (number), response data (string), response headers (object), and the text for the status (string). The file app.js demonstrates how to use the $httpBackend.
(function() {
    var app = angular.module('app', ["ngMockE2E"]);
    app.run(HttpBackendMocker);

    // original list of persons
    var persons = [
      {id: 1, name: 'Max Mustermann', birthdate: '01.01.1970'},
      {id: 2, name: 'Sara Smidth', birthdate: '31.12.1982'},
      {id: 3, name: 'James Bond', birthdate: '05.05.1960'}
    ];

    // Reg. expression for /person/:id
    var regexPersonId = /^\/person\/([0-9]+)$/;

    function HttpBackendMocker($httpBackend) {
        // GET /persons
        $httpBackend.whenGET('/persons').respond(persons);

        // GET /person/:id
        $httpBackend.whenGET(regexPersonId).respond(function(method, url) {
            var id = url.match(regexPersonId)[1];
            var foundPerson = findPerson(id);

            return foundPerson ? [200, foundPerson] : [404, 'Person not found'];
        });

        // POST /person
        $httpBackend.whenPOST('/person').respond(function(method, url, data) {
            var newPerson = angular.fromJson(data);
            // does the person already exist?
            var existingPerson = findPerson(newPerson.id);

            if (existingPerson) {
                // update existing person
                angular.extend(existingPerson, newPerson);
                return [200, existingPerson];
            } else {
                // create a new person
                newPerson.id = persons.length > 0 ? persons[persons.length - 1].id + 1 : 1;
                persons.push(newPerson);
                return [200, newPerson];
            }
        });

        // DELETE: /person/:id
        $httpBackend.whenDELETE(regexPersonId).respond(function(method, url) {
            var id = url.match(regexPersonId)[1];
            var foundPerson = findPerson(id);

            if (foundPerson) {
                persons.splice(foundPerson.id - 1, 1);
                // re-set ids
                for (var i = 0; i < persons.length; i++) {
                    persons[i].id = i + 1;
                }
            }

            return foundPerson ? [200, foundPerson] : [404, 'Person not found'];
        });

        // helper function to find a person by id
        function findPerson(id) {
            var foundPerson = null;
            for (var i = 0; i < persons.length; i++) {
                var person = persons[i];
                if (person.id == id) {
                    foundPerson = person;
                    break;
                }
            }

            return foundPerson;
        }
    }
})();
Now we need a custom service that encapsulates the $http service. The service will get the name DataService. It is placed in the file service.js.
(function() {
    var app = angular.module('app');
    app.factory('DataService', DataService);

    function DataService($http) {
        var service = {
            getPersons: getPersons,
            getPerson: getPerson,
            addPerson: addPerson,
            removePerson: removePerson
        };

        return service;

        function getPersons() {
            return $http.get('/persons').then(
                function(response) {
                    return response.data;
                },
                function(error) {
                    // do something in failure case
                }
            );
        }

        function getPerson(id) {
            return $http.get('/person/' + id).then(
                function(response) {
                    return response.data;
                },
                function(error) {
                    if (error.status && error.status === 404) {
                        return error.data;
                    } else {
                        return "Unexpected request";
                    }
                }
            );
        }

        function addPerson(person) {
            return $http.post('/person', person).then(
                function(response) {
                    return response.data;
                },
                function(error) {
                    // do something in failure case
                }
            );
        }

        function removePerson(id) {
            return $http.delete('/person/' + id).then(
                function(response) {
                    return response.data;
                },
                function(error) {
                    if (error.status && error.status === 404) {
                        return error.data;
                    } else {
                        return "Unexpected request";
                    }
                }
            );
        }
    }
})();
The service DataService is invoked by a controller which I named DataController and placed in the controller.js.
(function() {
    var app = angular.module('app');
    app.controller('DataController', DataController);

    function DataController($scope, DataService) {
        var _self = this;
        this.persons = [];
        this.personId = null;
        this.person = {};
        this.message = null;
        this.loading = false;

        this.getPersons = function() {
            init();

            DataService.getPersons().then(function(data) {
                _self.persons = data;
                _self.loading = false;
            })
        }

        this.getPerson = function(id) {
            // check required input
            if ($scope.form.id4get.$error.required) {
                _self.message = "Please add person's id";
                return;
            }

            init();

            DataService.getPerson(id).then(function(data) {
                if (typeof data === "string") {
                    // error
                    _self.message = data;
                    _self.persons = null;
                } else {
                    _self.persons = [data];
                }

                _self.loading = false;
            })
        }

        this.addPerson = function(person) {
            // check required input
            if ($scope.form.name.$error.required) {
                _self.message = "Please add person's name";
                return;
            }
            if ($scope.form.birthdate.$error.required) {
                _self.message = "Please add person's birthdate";
                return;
            }

            init();

            DataService.addPerson(person).then(function(data) {
                _self.persons = [data];
                _self.loading = false;
            })
        }

        this.removePerson = function(id) {
            // check required input
            if ($scope.form.id4delete.$error.required) {
                _self.message = "Please add person's id";
                return;
            }

            init();

            DataService.removePerson(id).then(function(data) {
                if (typeof data === "string") {
                    // error
                    _self.message = data;
                    _self.persons = null;
                } else {
                    _self.persons = [data];
                }

                _self.loading = false;
            })
        }

        // helper function to reset internal state
        var init = function() {
            _self.persons = [];
            _self.message = null;
            _self.loading = true;
        }
    }
})();
Now we can use the controller in the view - the file index.html
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta content="IE=edge" http-equiv="X-UA-Compatible" />
    <script src="https://code.angularjs.org/1.4.8/angular.js"></script>
    <script src="https://code.angularjs.org/1.4.8/angular-mocks.js"></script>
</head>
<body ng-app="app">
    <div ng-controller="DataController as ctrl" ng-cloak>
        <ul style="padding-left:0; list-style:none;">
            <li ng-repeat="person in ctrl.persons">
                {{person.id}} - {{person.name}} - {{person.birthdate}}
            </li>
        </ul>

        <div style="margin-bottom:15px;" ng-show="ctrl.loading">Loading ...</div>
        <div style="color:red; margin-bottom:15px;" ng-show="ctrl.message">{{ctrl.message}}</div>

        <form name="form" novalidate>
            <button ng-click="ctrl.getPersons()">GET /persons</button>
            <p></p>
            <button ng-click="ctrl.getPerson(ctrl.personId)">GET /person/:id</button>
            <input ng-model="ctrl.personId" name="id4get" required placeholder="id" />
            <p></p>
            <button ng-click="ctrl.addPerson(ctrl.person)">POST /person</button>
            <input ng-model="ctrl.person.name" name="name" required placeholder="name" />
            <input ng-model="ctrl.person.birthdate" name="birthdate" required placeholder="birthdate" />
            <p></p>
            <button ng-click="ctrl.removePerson(ctrl.personId)">DELETE /person/:id</button>
            <input ng-model="ctrl.personId" name="id4delete" required placeholder="id" />
        </form>
    </div>

    <script src="app.js"></script>
    <script src="config.js"></script>
    <script src="service.js"></script>
    <script src="controller.js"></script>
</body>
</html>
The current implementation has one shortcoming. The text Loading ... is not shown at all because the response is delivered very quickly, so that user doesn't see it. It would be nice to delay HTTP calls in order to simulate the network load. For this purpose we can use the $provide service and register a service decorator for the $httpBackend. The service decorator acts as proxy. If you look into the source code of the $httpBackend, you can see that the $httpBackend is created by the constructor function(method, url, data, callback, headers, timeout, withCredentials). The four parameter callback is responsible for the response. We have to provide our own implementation which I named delayedCallback. The delayedCallback function invokes the original callback with a delay (here 2 seconds) by means of setTimeout(). We delegate the proxy call to the $httpBackend instantiation, but with the new delayed callback. The injected $delegate object points exactly to the $httpBackend. The full code is shown below.
(function() {
    var app = angular.module('app');
    app.config(HttpBackendConfigurator);

    function HttpBackendConfigurator($provide) {
        $provide.decorator('$httpBackend', HttpBackendDecorator);

        function HttpBackendDecorator($delegate) {
            var proxy = function(method, url, data, callback, headers, timeout, withCredentials) {
                // create proxy for callback parameter
                var delayedCallback = function() {
                    // simulate network load with 2 sec. delay
                    var delay = 2000;

                    // Invoke callback with delaying
                    setTimeout((function() {
                        callback.apply(this, arguments[0]);
                    }.bind(this, arguments)), delay);
                };

                // delegate to the original $httpBackend call, but with the new delayed callback
                $delegate(method, url, data, delayedCallback, headers, timeout, withCredentials);
            };

            // the proxy object should get all properties from the original $httpBackend object 
            angular.extend(proxy, $delegate);

            // return proxy object
            return proxy;
        }
    }
})();