ember-fastboot-app-tests

This is an ember-cli addon that makes writing FastBoot tests for your Ember app easy and straightforward!

It works by spinning up a local FastBoot server using ember-cli-fastboot, and then runs your Mocha-based end-to-end tests to assert that your app works as expected in a FastBoot environment.

Note that this is for Ember apps only. For testing addons you can use this related project: ember-fastboot-addon-tests.

Installation

ember install ember-fastboot-app-tests

After installing the addon you should find a new folder fastboot-tests which will hold your test files. The default blueprint will have installed a first simple test to start with.

Testing principles

Before we get our hands dirty let's make some important things clear first! Because there are some significant differences between the FastBoot tests that this addon adds support for, and the usual Ember.js tests as you might know them.

Ember.js tests

The normal Ember.js tests, no matter whether these are unit, integration or acceptance tests, all run in the same browser (a real or a headless one like PhantomJS) and process as the actual code you test. So you can import any module from your app/addon, you have a DOM available (where your integration or acceptance tests render into), you have jQuery and so on.

FastBoot tests

Contrary to that for your FastBoot tests, your test and the code to test for run in two separate processes. The FastBoot server runs your app, but you can only access that through FastBoot's HTTP server. Your test itself runs in a node.js environment, not a browser! You can send a HTTP GET request to your FastBoot server, and it gives you a response, that is some HTTP headers and basically a plain string of HTML.

So this is a real end to end test, like the tests you do with tools like Selenium/WebDriver. Your running app is a black box, and you have no information about what is happening inside it, except for the HTML it returns. So no import, no document, no DOM, no jQuery (ok, wait, I might be proven wrong there!).

Testing basics

A test file generated by this addon will look like this:

const expect = require('chai').expect;

describe('index', function() {

  it('renders', function() {
    return this.visit('/')
      .then(function(res) {
        let $ = res.jQuery;
        let response = res.response;

        // add your real tests here
        expect(response.statusCode).to.equal(200);
        expect($('body').length).to.equal(1);
      });
  });

});

This Mocha test file defines a simple test that asserts that your app's index route returns the expected HTML that the default index.hbs defines. Although this might seem not worth testing at first sight, your app still can easily break that, e.g. by importing some external JavaScript that can only run on a browser or accessing the DOM in a component from within init.

You may wonder here where all the necessary bootstrap code is, for building the app and spinning up the FastBoot server. The good news is, you do not have to care about this, this addon takes care of this for you! All the setup and tear down code is added to your test suite in some before and after Mocha hooks.

But you still may have stumbled upon the use of jQuery in the above test, although a chapter before it was said that you have no DOM and no jQuery available to your tests. This is where the visit helper comes into play...

The visit helper

This addon gives you a visit helper that makes testing pretty easy. You give it a route of your app (as you would do it with the visit helper in an acceptance test) to make a request to. It then makes a HTTP request to your FastBoot server for that route, and returns a Promise. If the request was successfull, it resolves with a response object, which is a POJO with the following properties:

• response: the node.js response (an instance of http.IncomingMessage). You can use that e.g. to check the HTTP headers received by accessing response.headers.
• jQuery: although the tests run in node-land and have no real DOM available, with the help of jsdom - a JavaScript implementation of the DOM standard - a kind of faked DOM is available that jQuery can operate upon. So you can express your DOM assertions in a way you are used to from normal Ember tests.

Adding tests

Besides the already generated test file for you index route, adding a new route is easy:

ember g fastboot-test foo

This will add a foo-test.js file with the boilerplate for your new test.

Running your tests

ember fastboot:test

This will run all your FastBoot tests.

Contributions

To make this addon useful for as many users as possible, please contribute, by giving some feedback, submitting issues or pull requests!

Authors

Simon Ihmig @simonihmig