ember-qunit

What is ember-qunit?

ember-qunit is an Ember.js testing framework that integrates QUnit with Ember.js applications. It provides a set of helpers and utilities to make it easier to write and run tests for Ember.js applications.

What are ember-qunit's main functionalities?

Module Setup

This feature allows you to set up a test module for unit testing. The `setupTest` helper sets up the necessary environment for testing an Ember.js service.

import { module, test } from 'qunit';
import { setupTest } from 'ember-qunit';

module('Unit | Service | my-service', function(hooks) {
  setupTest(hooks);

  test('it exists', function(assert) {
    let service = this.owner.lookup('service:my-service');
    assert.ok(service);
  });
});

Rendering Tests

This feature allows you to write rendering tests for Ember.js components. The `setupRenderingTest` helper sets up the environment for rendering a component and the `render` function is used to render the component in the test.

import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { render } from '@ember/test-helpers';
import hbs from 'htmlbars-inline-precompile';

module('Integration | Component | my-component', function(hooks) {
  setupRenderingTest(hooks);

  test('it renders', async function(assert) {
    await render(hbs`<MyComponent />`);
    assert.equal(this.element.textContent.trim(), 'expected text');
  });
});

Application Tests

This feature allows you to write application tests for Ember.js routes. The `setupApplicationTest` helper sets up the environment for testing an entire Ember.js application, and the `visit` function is used to navigate to a specific route in the test.

import { module, test } from 'qunit';
import { setupApplicationTest } from 'ember-qunit';
import { visit, currentURL } from '@ember/test-helpers';

module('Acceptance | my route', function(hooks) {
  setupApplicationTest(hooks);

  test('visiting /my-route', async function(assert) {
    await visit('/my-route');
    assert.equal(currentURL(), '/my-route');
  });
});

Other packages similar to ember-qunit

ember-mocha

ember-mocha is an alternative testing framework for Ember.js that integrates Mocha with Ember.js applications. It provides similar functionality to ember-qunit but uses Mocha as the testing framework instead of QUnit. This can be useful for developers who prefer Mocha's syntax and features.

ember-cli-qunit

ember-cli-qunit is another package that integrates QUnit with Ember.js applications. It provides a similar set of helpers and utilities as ember-qunit but is specifically designed to work with the Ember CLI build system.

ember-test-helpers

ember-test-helpers is a low-level library that provides a set of helpers for testing Ember.js applications. It is used internally by both ember-qunit and ember-mocha and can be used directly for more fine-grained control over test setup and execution.

README

Ember QUnit

IMPORTANT NOTE - The build process is currently changing for this project. In v0.1.8 and below, builds were pushed to a dist/ dir. Going forward, we're going to push builds to a separate repo: ember-qunit-builds. Until this transition is complete, please update your bower.json if it's referencing rwjblue/ember-qunit#master. Instead specify a version (rwjblue/ember-qunit#v0.1.8) or SHA (f3f852789bc80486afae1a9ddb7810356050fe9b or older).

---

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

Usage

Setting the resolver

// if you don't have a custom resolver, do it like this:
setResolver(Ember.DefaultResolver.create({namespace: App}));

// otherwise something like:
import Resolver from './path/to/resolver';
import {setResolver} from 'ember-qunit';
setResolver(Resolver.create());

Simple example:

// tell ember qunit what you are testing, it will find it from the
// resolver
moduleForComponent('x-foo', 'XFooComponent');

// run a test
test('it renders', function() {
  expect(2);

  // creates the component instance
  var component = this.subject();
  equal(component.state, 'preRender');

  // render the component on the page
  this.render();
  equal(component.state, 'inDOM');
});

Complex example

// a more complex example taken from ic-tabs
moduleForComponent('ic-tabs', 'TabsComponent', {

  // specify the other units that are required for this test
  needs: [
    'component:ic-tab',
    'component:ic-tab-panel',
    'component:ic-tab-list'
  ]
});

test('selects first tab and shows the panel', function() {
  expect(3);
  var component = this.subject({

    // can provide properties for the subject, like the yielded template
    // of a component (not the layout, in this case)
    template: Ember.Handlebars.compile(''+
      '{{#ic-tab-list}}'+
        '{{#ic-tab id="tab1"}}tab1{{/ic-tab}}'+
        '{{#ic-tab id="tab2"}}tab2{{/ic-tab}}'+
        '{{#ic-tab id="tab3"}}tab3{{/ic-tab}}'+
      '{{/ic-tab-list}}'+
      '{{#ic-tab-panel id="panel1"}}one{{/ic-tab-panel}}'+
      '{{#ic-tab-panel id="panel2"}}two{{/ic-tab-panel}}'+
      '{{#ic-tab-panel id="panel3"}}three{{/ic-tab-panel}}'
    })
  });
  this.render();
  var tab1 = Ember.View.views['tab1'];
  var panel1 = Ember.View.views['panel1'];
  ok(component.get('activeTab') === tab1);
  ok(tab1.get('active'));
  var el = tab1.$();
  ok(panel1.$().is(':visible'));
});

If you are using nested components with templates, you have to list them separately - otherwise your templates won't be loaded:

moduleForComponent('ic-tabs', 'TabsComponent', {

  // specify the other units and templates that are required for this test
  needs: [
    'component:ic-tab',
    'template:components/ic-tab',
    'component:ic-tab-panel',
    'template:components/ic-tab-panel',
    'component:ic-tab-list'
  ]
});
.....

Async Example

Under the hood, if you use Ember.RSVP.Promise, ember-qunit will call QUnit's start and stop helpers to stop the test from tearing down and running other tests while your asynchronous code runs. ember-qunit also asserts that the promise gets fulfilled.

In addition, you can also return promises in the test body:

// If you return a promise from a test callback it becomes an asyncTest. This
// is a key difference between ember-qunit and standard QUnit.
test('async is awesome', function() {
  expect(1);
  var myThing = MyThing.create();
  // myThing.exampleMethod() returns a promise
  return myThing.exampleMethod().then(function() {
    ok(myThing.get('finished'));
  });
});

If an error is thrown in your promise or a promise within test becomes rejected, ember-qunit will fail the test. To assert that a promise should be rejected, you can "catch" the error and assert that you got there:

test('sometimes async gets rejected', function(){
  expect(1);
  var myThing = MyThing.create()

  return myThing.exampleMethod().then(function(){
    ok(false, "promise should not be fulfilled");
  })['catch'](function(err){
    equal(err.message, "User not Authorized");
  });
});

Test Helpers

moduleFor(fullName [, description [, callbacks]])

• fullName: (String) - The full name of the unit, ie controller:application, route:index.

• description: (String) optional - The description of the module

• callbacks: (Object) optional - Normal QUnit callbacks (setup and teardown), with addition to needs, which allows you specify the other units the tests will need.

moduleForComponent(name, [description, callbacks])

• name: (String) - the short name of the component that you'd use in a template, ie x-foo, ic-tabs, etc.

moduleForModel(name, [description, callbacks])

• name: (String) - the short name of the model you'd use in store operations ie user, assignmentGroup, etc.

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 Ryan Florence and contributors. MIT License.