caseywatts / ember-mocha

Mocha helpers for testing Ember.js applications

ember-mocha

ember-mocha simplifies unit testing of Ember applications with Mocha by providing Mocha-specific wrappers around the helpers contained in ember-test-helpers.

Upgrading from an earlier version? Have a look at our Upgrade Guide below.

Installation

Installation with Ember CLI

In order to use Ember Mocha with Ember CLI, please follow the instructions for ember-cli-mocha.

Standalone Installation

Ember Mocha can also be installed with bower and used directly in any Ember project:

$ bower install ember-mocha

You can then choose to include the global (ember-mocha.js) or AMD (ember-mocha.amd.js) build when running your tests.

Usage

Setting the Resolver

You'll typically want to set a single resolver for your test suite:

import resolver from './helpers/resolver';
import { setResolver } from 'ember-mocha';

setResolver(resolver);

If you want to use multiple resolvers in your test suite, you can also call setResolver in the beforeSetup callback of your test modules.

Setup Tests

The setupTest function can be used to setup a unit test for any kind of "module/unit" of your application that can be looked up in a container.

For example, the following is a unit test for the SidebarController:

import { describe, it } from 'mocha';
import { setupTest } from 'ember-mocha';

describe('SidebarController', function() {
  setupTest('controller:sidebar', {
    // Specify the other units that are required for this test.
    // needs: ['controller:foo']
  });
  
  // Replace this with your real tests.
  it('exists', function() {
    var controller = this.subject();
    expect(controller).to.be.ok;
  });
});

The subject is specified as controller:sidebar, which is the key that will be used to look up this controller in the isolated container that will be created for this test.

Setup Component Tests

The setupComponentTest function is specifically designed to test components and provides additional render and $ helpers within a test's context.

import { describe, it } from 'mocha';
import { setupComponentTest } from 'ember-mocha';

describe('GravatarImageComponent', function() {
  setupComponentTest('gravatar-image', {
    // specify the other units that are required for this test
    // needs: ['component:foo', 'helper:bar']
  });

  it('renders', function() {
    // creates the component instance
    var component = this.subject();
    expect(component._state).to.equal('preRender');

    // renders the component on the page
    this.render();
    expect(component._state).to.equal('inDOM');
  });
});

Setup Model Tests

The setupModelTest function can be used to test Ember Data models and provides an additional store helper within a test's context.

import { describe, it } from 'mocha';
import { setupModelTest } from 'ember-mocha';

describe('Contact', function() {
  setupModelTest('contact', {
    // Specify the other units that are required for this test.
    needs: []
  });
  
  // Replace this with your real tests.
  it('exists', function() {
    var model = this.subject();
    // var store = this.store();
    expect(model).to.be.ok;
  });
});

Acceptance Tests

The setupAcceptanceTest function can be used to run acceptance tests as the name suggests. It will automatically setup an application instance for you, which is provided at this.application.

import Ember from 'ember';
import { describe, it } from 'mocha';
import { setupAcceptanceTest } from 'ember-mocha';

var Application = Ember.Application.extend({
  rootElement: '#ember-testing',
});

describe('basic acceptance test', function() {
  setupAcceptanceTest({ Application });

  it('can visit /', function() {
    visit('/');

    return andThen(() => {
      expect(currentURL()).to.equal('/');
    });
  });
});

Please make sure to always return your last async test helper from the test function. This will actually return a Promise which is letting the Mocha test framework know that this is an async test. Note that you can also add return wait(); to the end of your acceptance tests.

While this currently still works without the return, it will fail once this library is updated to Mocha 3.x!

Using async/await

In case your project supports the async/await feature of ES2016 you can simplify the test function to this:

it('can visit /', async function() {
  await visit('/');
  expect(currentURL()).to.equal('/');
});

• add the async keyword in front of the test function
• add await in front of all async test helper calls
• remove the andThen() wrappers

Upgrading

Previous releases promoted the use of describeModule(), describeComponent() and describeModel() instead of the describe() function of Mocha itself. These functions have been deprecated and replaced by the setupTest() functions mentioned above. The following example will explain how to update your code.

Before:

import {expect} from 'chai';
import {it} from 'mocha';
import {describeModule} from 'ember-mocha';

describeModule(
  'route:subscribers',
  'Unit: Route: subscribers',
  {
    needs: ['service:notifications']
  },
  function() {
    it('exists', function() {
      let route = this.subject();
      expect(route).to.be.ok;
    });
  }
);

After:

import {expect} from 'chai';
import {it, describe} from 'mocha';
import {setupTest} from 'ember-mocha';

describe('Unit: Route: subscribers', function() {
  setupTest('route:subscribers', {
    needs: ['service:notifications']
  });

  it('exists', function() {
    let route = this.subject();
    expect(route).to.be.ok;
  });
});

• import it from mocha instead of ember-mocha
• replace the describeModule import with a setupTest import
• add a setupTest() call to the test function with the second and third argument of the describeModule() call (module name and options)
• replace the describeModule() call with a describe() call with the first and fourth argument of the describeModule() call (description and test function)

Instead of refactoring all your files by hand we recommend to use the ember-mocha-codemods to automatically convert your tests:

npm install -g jscodeshift
jscodeshift -t https://raw.githubusercontent.com/Turbo87/ember-mocha-codemods/master/import-it-from-mocha.js tests
jscodeshift -t https://raw.githubusercontent.com/Turbo87/ember-mocha-codemods/master/new-testing-api.js tests

Contributing

Contributions are welcome. Please follow the instructions below to install and test this library.

Installation

npm install

Testing

In order to test in the browser:

npm start

... and then visit http://localhost:4200/tests.

In order to perform a CI test:

npm test

Copyright and License

Copyright 2014 Switchfly

This product includes software developed at Switchfly (http://www.switchfly.com).

NOTICE: Only our own original work is licensed under the terms of the Apache License Version 2.0. The licenses of some libraries might impose different redistribution or general licensing terms than those stated in the Apache License. Users and redistributors are hereby requested to verify these conditions and agree upon them.

This repository also contains the ember-mocha-adapter originally developed by Teddy Zeenny at https://github.com/teddyzeenny/ember-mocha-adapter/ under the MIT license.