stefanpenner/ember-app-kit — pull request #452 by stefanpenner (2014-01-28 05:27:54+00:00)
Title: Improved Test Helpers

Although ember has pretty good architecture that facilitates
good testing, for some things such as components and ember data models,
it can be tricky to figure out how to even get started testing.

Within ember apps, we tend to use context specific naming conventions
such as this.store(), or needs[ ], why do
we need to change this convention for our testing.

Also, although QUnit provides a battle tested testing framework
some conventions are pretty bar bone. Async testing, management of
test run specific properties, all leave much to be desired.

Async testing:

Currently, patterns such as the following might be possible.

```js
test("foo", function(){

stop();
somethingAsync().then(function(){
start();
ok(true, '');
});
})
```

But what if simply returning a promise to the callback
handled the start/stop/timeout book keeping for us?

Bonus: what if when the test framework detected a returned
promise, it also asserted that it must settled fulfilled.

```js
test("foo", function(){
return somethingAsync().then(function(){
ok(true, 'something important');
});
})
```

It is common for your tests to have various variables constructor
During the setup and teardown phase of our tests. Unfortunately,
sometimes its common to leak them by accident, or not tear them down.

Such as.

```js
var foo, bar, baz;

module("testing the thing", {
setup: function() {
foo = Ember.Object.create();
bar = Ember.Object.create();
},

teardown: function() {
foo = null;
bar = null;
}
});

test("a test run", function(){
ok(foo);
equal(foo, bar);
});
```

So instead, lets let the test framework handle the hard work.

```js

moduleFor('controller:bar', 'testing the thing', {
setup: function(factory, container) {
factory // => factoryFor controller:bar
container // => container for injections to be specified.
},
// setup: still exists if you need;
foo: function() {
return Ember.Object.create();
},
bar: function() {
return Ember.Object.create();
}
// teardown: still exists if you need,
// but cleanup happens automatically.
});

test("a test run", function() {
// these variables are lazily instantiated, and cached per test run
var foo = this.foo();
var bar = this.bar();

var controller = this.subject(); // instance of controller:bar

ok(foo);
equal(foo, bar);
});
```

component example:

```js
moduleForComponent('foo');

test("testing foo focuses on entry", function(){

var component = this.subject();

// component is rendered the first time we invoke `this.$()`
// as that is the first time we are inspecting the DOM.
ok(this.$().is(':focus'));
ok(component.$().is(':focus'));
});
```

extensibility:

Currently `moduleFor` and `test` are the foundational api's

the first level of configuration is via the module hash

```js
moduleFor('controller:foo', 'description', {
subject: function(factory, options) {
return factory.create(options); // override the default "subject"
},
setup: function(container) {
// register factories or injection rules on the container
},
bar: function() { }, // other managed variables
baz: function() { }
});
```

the second is by specifying a custom `moduleForHelper`, this API and functionality
is still in its infancy so expect it to change some, but an example is the implementation of moduleForModel:

```js
function moduleForModel(name, description, callbacks) {
moduleFor('model:' + name, description, callbacks, function(factory, container, context) {
container.register('store:main', DS.Store);
container.register('adapter:application', DS.FixtureAdapter);

context.__setup_properties__.store = function () {
return container.lookup('store:main');
}
}
}
```

paired with @hjdavid
high level ideas derived from conversation with @tomdale + @wycats