Aurelia is one of a crop of new front end JavaScript frameworks that make it easier to manage complex interactions in the browser. It implements a MVVM pattern and includes routing, dependency injection etc.

Unit testing Aurelia custom elements and attributes is described in the Aurelia docs (http://aurelia.io/hub.html#/doc/article/aurelia/testing/latest/testing-components. However, more general testing of business logic or service code is not discussed. This article gives a basic introduction to testing these classes using the Aurelia CLI.

1. What libraries are included in the CLI, what do they do?
2. Writing a basic test
3. Running tests
4. Improving the test output
5. Debugging tests
6. Mocking in tests
7. Testing code with promises.

Note: Aurelia supports the babel.js and Typescript transpilers. The code examples below are in Typescript but should be readable for anyone who is familiar with modern javascript.

1.      What libraries are included in the CLI, what do they do?

When creating an Aurelia project using the CLI the following testing libraries are included:

• Jasmine – popular BDD JavaScript testing framework. Provides the test structure and asserts.
• Karma – test runner. Allows you to run the tests from the command line and debug the tests within a browser.

Angular Protractor and selenium web-driver tests are also included – they are used for end to end testing and so not discussed in this article.

2.      Writing a basic test

Test classes are placed in the /tests folder and should include spec in the title e.g. articleStore.spec.js. The test class should include the following elements.

Import referenced classes

Import the class under test (and any other relevant classes) at the top of the test class e.g.

Import { ArticleStore } from ‘../../src/articles/ArticleStore’;

Create a top level describe function.

Create a describe function that indicates the name of the class under test as a string and the details of the tests as an argument e.g.

describe(‘the ArticleStore’, () => {…});

Note: The text ‘the ArticleStore’ will then be outputted when we run the tests.

Create a test setup

As with most testing framework Jasmine provides a mechanism to run setup and teardown code before/after each individual test. This is achieved by creating a beforeEach/afterEach function that takes a function as an argument.

In this example we will use this to create an instance of the class under test before each test is run e.g.

let target: ArticleStore;

beforeEach(() => {

      this.target = new ArticleStore();

});

Create a test

To create the test itself we create an it() function which takes the name of the test as a string and the test code as an function argument. Again, the name of the test will be outputted by the test runner.

The test itself makes use of the Jasmine asserts to confirm expected state.

e.g.

it(“should have an empty articles collection”, () = {

      expect(this.target.Articles).not.toBeNull();

      expect(this.target.Articles.length).toBe(0);

});

3.      Running tests

To run the tests issue the following statement from a command prompt:

au test

This invokes the Karma test runner to run any tests it finds in files ending spec.js and outputs the details of any tests that have failed.

“au test” will run the tests once, report the output and close. However, as with the “Aurelia run” command you can include the watch argument:

au test --watch

This will run the tests, report the output but not close. The test runner will maintain a watch for any changes to code and when new code is saved will rerun the tests and display the new output.

4.      Improving the test output

The default configuration of Karma within Aurelia will only report failing tests. To get a comprehensive list of all tests that were run make the following change to the /karma.conf.js file:

Change this:      reporters: [‘progress’],

To this:               reporters: [‘spec’],

5.      Debugging tests

Karma makes debugging quite easy as it creates a browser instance and allows you to use the standard in browser debug tools (F12). As well as being simple to use, debugging in the browser is more accurate than debugging in an IDE or similar, as it will correctly replicate any browser issues.

To debug from the Karma test runner:

• In the command prompt run: au test –watch
• A browser spins up. Click the ‘Debug’ button in the green bar on the top right.
• A new tab opens with the unit tests loaded. Press F12 to open developer tools, view the source, add breakpoints etc. as normal and press refresh to re-run the tests and hit the breakpoints.

6.      Mocking in Aurelia tests

Mocking is an important part of any unit testing strategy. Currently the standard tool for mocks/stubs/spies in Javascipt is to use the sinon.js library. However in my experience this did not play well with Jasmine.

An alternative, simpler and more modern mocking library is called TestDouble (https://github.com/testdouble/testdouble.js) . This can be imported via NPM.

Import the testdouble package

npm install testdouble –save-dev

Add testdouble as a vendor-bundle dependency.

This is optional but adding the following to the dependencies section of the /aurelia-project/aurelia.json file, vendor-bundle dependencies section makes regularly including the testdouble library within test classes simpler as you can refer to it with a simple name rather than needing the relative path.

{
        "name": "testdouble",
        "path": "../node_modules/testdouble/dist/testdouble"
}

Import TestDouble in your test class

Import * as TestDouble from ‘testdouble’;

Note include the relative path if you did not complete the previous step

Create/Destroy the mock objects

Within the test code create a variable for the object being mocked, with the type of the object being mocked e.g. if we are mocking a class of type ApiConnector

let apiConnector: ApiConnector;

Initialize the mock on the beforeEach() method, and call TestDouble.reset() on the afterEach() method e.g.

beforeEach(() => {
      this.apiConnector = TestDouble.object(ApiConnector);
});

afterEach(() => {
      TestDouble.reset();
});

Setup and/or verify the mocks within the tests

It(‘getStatus should return the updating status from the apiConnector”, () => {

      // setup the mock
      let knownStatus = “cached”;
      TestDouble.when(this.apiConnector.getStatus).thenReturn(knownStatus);

      // make the call under test
      Let result = this.articleStore.getStatus();
      
      // assert the mocked result is returned and the call was made on the mock object
      Expect(result).toBe(knownStatus);

      this.articleStore.verify(getApiStatus);
});

7.      Testing code containing promises

Asynchronous code is very common in the JavaScript world and a modern approach to implementing async code is to use promises. Asynchronous code and promises requires some minor changes in testing approach.

To handle async code Jasmine takes an optional argument to the it(), beforeEach() and afterEach() methods called “done”. The “done” argument is a method that should be called once all other test code has completed. When using a promises approach to asynchronous code this would typically be at the end of the last “then” call.

The following code gives an example of creating a promise object and returning this promise from a mocked method. This is a common scenario e.g. where an ajax call which returns a promise needs to be mocked.

For a promise to be processed either its resolve or reject method should be called. In this example the mock returns a promise that has a resolve method and the test asserts that when that promise is successfully resolved the refreshAll method returns a promise with the data true.

it("refreshAll returns a promise with data:true when api call successful", (done) =>  {
       // arrange       
        let promise = new Promise((resolve, reject) => { resolve("Success data"); });

        TestDouble.when(this.apiConnector.getMany()).thenReturn(promise);

        // act
        let result = this.articleStore.refreshAll();

        // assert
        result.then(data => {
            expect(data).toBe(true);

            done();
        }); 

    });

Complete example code

As a summary, I have included below a complete example of an Aurelia test class which mocks promises:

import { ArticleStore } from '../../../../src/resources/data-service/ArticleStore';

import { ApiConnector } from '../../../../src/resources/data-service/ApiConnector';

import * as TestDouble from 'testdouble';

describe('the ArticleStore', () => {

    // setup

    let apiConnector: ApiConnector;

    let articleStore: ArticleStore;

    beforeEach(() => {

        TestDouble.reset();
        this.apiConnector = TestDouble.object(ApiConnector);
        this.articleStore = new ArticleStore(this.apiConnector);       

    });




    afterEach(() => {
        TestDouble.reset();
    });




    it("refreshAll returns a promise with data:true when api call successful", (done) =>  {
        // arrange       
        let promise = new Promise((resolve, reject) => { resolve("Success data"); });
        TestDouble.when(this.apiConnector.getMany()).thenReturn(promise);

        // act
        let result = this.articleStore.refreshAll();

        // assert
        result.then(data => {
            expect(data).toBe(true);
            done();
        }); 

    });

});

Our tale begins a month and a half ago, in a lab at the University of Southampton….

I was at the beginning of my internship, and we had decided one of the key jobs was fleshing out our data. The Open Data Service previously gathered data using pen and whiteboard. The issue with these archaic tools is time. Not just the time spent gathering data, but processing it all by hand at the other end.

As such, I set out on journey. A journey to create one tool that would facilitate the easy gathering of data. It’s still far from complete, but here’s what it does so far.

Overview
DISCLAIMER: None of this tool is considered “stable” at this point in time. Data formats can and will change, use at your own risk!

The aims of the tool are:

• To speed up the gathering and processing of data. More specifically, data gathered on-location.
• To enable and encourage non-technical people to contribute open data.

The result is a responsive website, written in PHP. PHP was chosen as it’s trivially integrated into the Open Data service. – https://github.com/Spoffy/OpenGather

User Interface

The current interface is extremely simple, but it gets the job done. It shows a set of object types (schemas) people can submit. Changing the schema changes the form fields shown. These can then be filled in and submitted. Any required fields that weren’t filled in are highlighted in red.

The tool currently supports text fields, dropdown fields and geolocation fields. For geolocation fields, the initial values of longitude and latitude use the phone’s GPS. It’s possible to click on the map to select a more precise location. This is especially useful when recording the location-sensitive objects such as doors.

The Database

A small subset of the tables.

The tool uses MySQL as its default backend. The details are configurable in config.php. There’s a single central table that records each data item entered. It stores an id, the time and the schema id.

Each schema has its own table of details. Each entry’s id acts a foreign key, relating an entry to the details about it in the schema’s table.

Exporting Data

Currently, the data is exportable as JSON. This format allows several schemas to exist together seamlessly. JSON is also human editable, making it easy to correct long-term data. The tool makes the export publically available at http://yourwebsite/path/to/tool/dumpjson.php. There’s no issue with making data public, as it’s designed to gather OpenData.

The data is also available through the MySQL instance. This method of access isn’t recommended.

The Schema Generator

Personally, I think this is the coolest part of the system. It allows you to quickly specify a schema using PHP. This schema is then transformed into HTML for the web forms and SQL for the database. The web interface updates the schema list when the page loads. Dynamically loading these schemas allows submissions to go straight to the database.

The upshot is that defining new schema is incredibly easy. There’s no need to mess around with HTML or SQL. Just a few PHP objects gets the job done!

The following is a sample schema I use to gather data from around the University:

//Format: 
//    new ObjectSchema($name, $fieldsArray);
//    new TextField($name, $id, $required);
//    new DropdownField($name, $id, $optionsArray, $required=true);

$schemas = array(
    new ObjectSchema("Building Entrance", array(
        new TextField("Building Number", "buildingId", true),
        new TextField("Entrance Label", "entranceId", false),
        new TextField("Description", "description", true),
        new GeoField("Latitude", "lat", true),
        new GeoField("Longitude", "long", true),
        new DropdownField("Access Method Daytime", "accessDaytime", $accessOptions),
        new DropdownField("Access Method Evening", "accessEvening", $accessOptions),
        new DropdownField("Opening Method", "openingMethod", $openingOptions)
    )),

    new ObjectSchema("Drinking Water Source", array(
        new TextField("Building Number", "buildingId", true),
        new TextField("Floor", "floor", true),
        new GeoField("Latitude", "lat", true),
        new GeoField("Longitude", "long", true)
    ))
);

In conclusion….
The tool is still very much in the early stages of development. Feel free to use it, but be wary that things may break between versions! If you’re feeling particularly adventurous, merge requests are more than welcome…

Improvements currently on the roadmap include:

• An updated, friendlier user interface.
• Versioning for the schema, including a tool to move data between schema versions. This should help with the long-term preservation for data.
• Support for image uploading. One major weakness is the need to take images seperately and link them later.
• Add a README to explain installation and usage.

The source code is available at https://github.com/Spoffy/OpenGather

(Edit) Next week Eventually, I’ll be talking about taming QGIS, building tilesets and designing GeoJSON maps!

Skills Demonstrated
– User Consultation
– Specification Acquisition
– Adding Functionality to Legacy Code

This was another successful week working on choices. Just like the previous six weeks. Due to my mangers spontaneous expedition to Iceland, Docpot was put on hold. I’ve been to Iceland before, didn’t take me a whole week to get my groceries though…(Sorry).

The medical department uses a convoluted method to allocate students to their courses. This requires a separate allocation algorithm due to the uniqueness of their demands. Last year they split the students into three cohorts depending on their background. Some students were able to pick a language in both slots; some could not as one slot was pre-allocated. This needs changing now. It turns out that choices has finally forced me to make an appointment in the hospital. Meetings are much more productive when all parties are in the same room, even if that room is in a dark corner of a large city hospital. The medical department was a pleasure to work with. It’s refreshing when an agreed solution doesn’t need a complete reworking of existing code.

Kev and I split the work between ourselves. The endgame was to ask questions about the language options so students were aware of the requirements. There were three difficulties of a language: beginner, intermediate and advanced. Each required varied qualifications. We needed to implement questions which are only asked when a student pick specific options. If the student does not pick the option, the answer should be set to a default false value. Kev worked on making actions to add choosers to groups depending on their options. I made the changes to the add and edit questions pages to allow a admin to add this functionality to their form. Using what I learnt last week, I refactored the questions controller so it was easier to work with. I cannot stress the usefulness of testing enough!

We got a working demo working by Friday. Kev was showcasing it to the medical department this morning. There are a few minor bugs to fix but they seemed happy with our progress.

I am now over half way through my internship. Choices starting to look healthier now. I know I say every week but I am looking forward to when i can move on from choices. This week TIDT are doing WAISFest, which is a hackathon hosted by the university. It should give me a good enough reason to escape choices. We shall see…

Skills Demonstrated
– Integration Testing
– Refactoring Legacy Code

So week 5 was the tail end of front-end fortnight, what is that you ask? Well I can tell you in layman’s terms as I was the only one in the whole team who had no involvement with it. Our team had two weeks to figure out which front-end framework they would use for the foreseeable future. That left me pretty much to my own devices for the duration. That meant choices for me – there is always something to fix in choices.

The more astute of my readers will have noticed that this blog post covers two weeks. These few weeks have left my blogging ability rather diminished. But I digress.

It is now where I would like to link to you my managers recent blog post “Zen and the Art of Legacy Camp Site Cleaning”. I paraphrase: “Bolting unit tests onto legacy code is pretty much impossible. Untested legacy code which has been chugging along without issue should not be rewritten. The trick is to leave the campsite cleaner than you found it”. There were two incomprehensible behemoth functions in the options controller totalling about 400 lines. Much like choices, 70% of the universe consists of dark energy. No physicist can explain what dark energy is, or how it got there; only what it does. This is where integration tests come in handy. Unlike in unit testing, the controller communicates with fake databases called fixtures. This allowed me to give this pile of code a data set and then examine how it was digested at the other end. I assumed the add and edit functions worked before I touched them and proceeded to make many integration tests using this method. It was important that I had good code coverage in the tests before starting the cleaning process. Good testing allowed for quick refactoring thanks to immediate feedback.

Since pushing choices to live, we’ve had even more requests from users. And so it goes on. A user found a bug where the ‘all pages’ button on the paginator was dysfunctional. The code for the all button was commented out, it appeared as though somebody couldn’t get it to work but then forgot to remove the button from the view. The fix was actually simple. They tried setting the options per page limit to 1000 to make the all button work. This would have worked but there is a sneaky cake setting called ‘max-limit’ which is set to 100 by default, this overrode the 1000 limit.

There are few more things which I fixed and implemented on choices this week. But this blog post is already getting rather long for my liking, and most likely yours so this is it for now.