This guide provides instruction for upgrading your test suite
- from the Legacy APIs to Ember's latest testing APIs based on RFCs 232 and 268.
- from very early releases of Ember Mocha, based on custom
describe*
functions to the later introducedsetupTest()
functions, both based on Ember's Legacy APIs
For the complete introduction to the new testing APIs, please read the latest Ember Guides. The following examples will give you an overview how to migrate your existing Ember Mocha based test suite.
Before:
import { expect } from 'chai';
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;
});
});
After:
import { expect } from 'chai';
import { describe, it } from 'mocha';
import { setupTest } from 'ember-mocha';
describe('SidebarController', function() {
setupTest();
// Replace this with your real tests.
it('exists', function() {
let controller = this.owner.lookup('controller:sidebar');
expect(controller).to.be.ok;
});
});
- Use
setupTest()
without any arguments to opt into the new testing system - Use the Owner object given by
this.owner
directly instead ofthis.subject()
Before:
import { expect } from 'chai';
import { describe, it } from 'mocha';
import { setupComponentTest } from 'ember-mocha';
import hbs from 'htmlbars-inline-precompile';
describe('GravatarImageComponent', function() {
setupComponentTest('gravatar-image', {
integration: true
});
it('renders', function() {
this.render(hbs`{{gravatar-image}}`);
expect(this.$('img')).to.exist;
});
});
After:
import { expect } from 'chai';
import { describe, it } from 'mocha';
import { setupRenderingTest } from 'ember-mocha';
import { render } from '@ember/test-helpers';
import hbs from 'htmlbars-inline-precompile';
describe('GravatarImageComponent', function() {
setupRenderingTest();
it('renders', async function() {
await render(hbs`{{gravatar-image}}`);
expect(this.element.querySelector('img')).to.exist;
});
});
- Use
setupRenderingTest()
instead ofsetupComponentTest()
- Render using the
render()
helper from@ember/test-helpers
instead ofthis.render()
render()
is now always an async call, so useasync
/await
to wait for it to complete- Use
this.element
to get access to the rendered DOM - Replace
this.on
when testing action invocation withthis.set
and convertstring
references to the action name with the name of the variable that contains the function - Do not use jQuery for DOM interaction, instead use the
DOM Interaction Helpers
from
@ember/test-helpers
For migrating to the DOM interaction helpers, you can use the ember-test-helpers-codemod to automatically convert all or most of it.
Before:
import { describe, it, beforeEach, afterEach } from 'mocha';
import { expect } from 'chai';
import startApp from 'app/tests/helpers/start-app';
import destroyApp from 'app/tests/helpers/destroy-app';
describe('basic acceptance test', function() {
let application;
beforeEach(function() {
application = startApp();
});
afterEach(function() {
destroyApp(application);
});
it('can visit /', function() {
visit('/');
return andThen(() => {
expect(currentURL()).to.equal('/');
});
});
});
After:
import { expect } from 'chai';
import { describe, it } from 'mocha';
import { setupApplicationTest } from 'ember-mocha';
import { visit, currentURL } from '@ember/test-helpers';
describe('basic acceptance test', function() {
setupApplicationTest();
it('can visit /', async function() {
await visit('/');
expect(currentURL()).to.equal('/');
});
});
- Use
setupApplicationTest()
instead ofsetupAcceptanceTest()
or thebeforeEach
/afterEach
hooks from the example above - Use the Routing Helpers
from
@ember/test-helpers
instead of the global helpers, e.g.visit
- Do not use the "global" test helpers for DOM interaction, instead use the
DOM Interaction Helpers
from
@ember/test-helpers
- use
async
/await
to wait for asynchronous operations likevisit()
orclick()
- use
this.element
to get access to the rendered DOM
For migrating from the global test helpers to those proved by
@ember/test-helpers
, you can use the
ember-test-helpers-codemod
to assist you with that task.
Very early 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 in the Legacy Guide. 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()
frommocha
instead ofember-mocha
- replace the
describeModule()
import with asetupTest()
import - add a
setupTest()
call to the testfunction
with the second and third argument of thedescribeModule()
call (module name and options) - replace the
describeModule()
call with adescribe()
call with the first and fourth argument of thedescribeModule()
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
This will migrate you to the testing API described in the Legacy Guide. After that you can follow the other migration guides above to upgrade to the new shared testing APIs.